1 .\" Copyright (c) 2001, 2002 Steven Knight
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 "November 2002"
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
68 option. If the specified file is not
69 in the local directory,
71 will internally change its working
72 directory (chdir) to the directory containing the file.
74 The configuration files
75 (generically referred to as
78 specify the target files to be built, and
79 (optionally) the rules to build those targets. Reasonable default
80 rules exist for building common software components (executable
81 programs, object files, libraries), so that for most software
82 projects, only the target and input files need be specified.
85 reads and executes the SConscript files as Python scripts,
86 so you may use normal Python scripting capabilities
87 (such as flow control, data manipulation, and imported Python libraries)
88 to handle complicated build situations.
90 however, reads all of the SConscript files
92 it begins building any targets.
95 prints the following messages about what it is doing:
99 scons: Reading SConscript files ...
100 scons: done reading SConscript files.
101 scons: Building targets ...
103 scons: done building targets.
107 These status messages may be suppressed using the
112 can scan known input files automatically for dependency
113 information (for example, #include statements
114 in C or C++ files) and will rebuild dependent files appropriately
115 whenever any "included" input file changes.
118 ability to define new scanners for unknown input file types.
121 is normally executed in a top-level directory containing a
123 file, specifying the target or targets to be built as
124 command-line arguments. The command
130 will build all target files in or below the current directory
137 will build all target files in or below the root directory (i.e.,
138 all files). Specific targets may be supplied:
144 Targets may be omitted from the command line,
145 in which case the targets specified
146 in the SConscript file(s) as
148 targets will be built:
154 Specifying "cleanup" targets in SConscript files is not
157 flag removes all files
158 necessary to build the specified target:
164 to remove all target files, or:
167 scons -c build export
170 to remove target files under build and export.
171 Additional files or directories to remove can be specified using the
174 A subset of a hierarchical tree may be built by
175 remaining at the top-level directory (where the
177 file lives) and specifying the subdirectory as the target to be
184 or by changing directory and invoking scons with the
186 option, which traverses up the directory
187 hierarchy until it finds the
189 file, and then builds
190 targets relatively to the current subdirectory:
198 supports building multiple targets in parallel via a
200 option that takes, as its argument, the number
201 of simultaneous tasks that may be spawned:
207 builds four targets in parallel, for example.
209 Values of variables to be passed to the SConscript file(s)
210 may be specified on the command line:
216 These variables are available in SConscript files
217 through the ARGUMENTS dictionary,
218 and can be used in the SConscript file(s) to modify
219 the build in any way:
222 if ARGUMENTS.get('debug', 0):
223 env = Environment(CCFLAGS = '-g')
229 .\" can maintain a cache of target (derived) files that can
230 .\" be shared between multiple builds. When caching is enabled in a
231 .\" SConscript file, any target files built by
234 .\" to the cache. If an up-to-date target file is found in the cache, it
235 .\" will be retrieved from the cache instead of being rebuilt locally.
236 .\" Caching behavior may be disabled and controlled in other ways by the
237 .\" .BR --cache-force ,
238 .\" .BR --cache-disable ,
241 .\" command-line options. The
243 .\" option is useful whenever multiple builds may be
244 .\" trying to update the cache simultaneously.
247 requires Python version 1.5.2 or later.
248 There should be no other dependencies or requirements to run
253 configuration assumes
254 use of the Microsoft Visual C++ compiler suite on WIN32 systems,
255 and assumes a C compiler named
257 and a C++ compiler named
259 (such as found in the GNU C compiler suite)
260 on any other type of system.
261 You may, of course, override these default values
262 by appropriate configuration of
263 Environment construction variables.
268 supports the same command-line options as GNU
270 and many of those supported by
275 Ignored for compatibility with non-GNU versions of
279 -c, --clean, --remove
280 Clean up by removing all target files for which a construction
281 command is specified.
282 Also remove any files or directories associated to the construction command
283 using the Clean() function.
286 .\" --cache-disable, --no-cache
287 .\" Disable caching. Will neither retrieve files from cache nor flush
288 .\" files to cache. Has no effect if use of caching is not specified
289 .\" in an SConscript file.
292 .\" --cache-force, --cache-populate
293 .\" Populate a cache by forcing any already-existing up-to-date
294 .\" target files to the cache, in addition to files built by this
295 .\" invocation. This is useful to populate a new cache with
296 .\" appropriate target files, or to make available in the cache
297 .\" any target files recently built with caching disabled via the
298 .\" .B --cache-disable
303 .\" When retrieving a target file from a cache, show the command
304 .\" that would have been executed to build the file. This produces
305 .\" consistent output for build logs, regardless of whether a target
306 .\" file was rebuilt or retrieved from cache.
309 .RI "-C" " directory" ", --directory=" directory
310 Change to the specified
312 before searching for the
317 file, or doing anything
320 options are interpreted
321 relative to the previous one, and the right-most
323 option wins. (This option is nearly
325 .BR "-f directory/SConstruct" ,
326 except that it will search for
331 in the specified directory.)
335 .\" Display dependencies while building target files. Useful for
336 .\" figuring out why a specific file is being rebuilt, as well as
337 .\" general debugging of the build process.
341 Works exactly the same way as the
343 option except for the way default targets are handled.
344 When this option is used and no targets are specified on the command line,
345 all default targets are built, whether or not they are below the current
350 Debug the build process.
352 specifies what type of debugging:
356 Re-run SCons under the control of the
361 argument will be stripped from the command-line,
362 but all other arguments will be passed in-order
363 to the SCons invocation run by the debugger.
367 Print the dependency tree
368 after each top-level target is built. This prints out the complete
369 dependency tree including implicit dependencies and ignored
374 Print the dependency tree
375 after each top-level target is built. This prints out only derived files.
379 Prints various time profiling information: the time spent
380 executing each build command, the total build time, the total time spent
381 executing build commands, the total time spent executing SConstruct and
382 SConscript files, and the total time spent executing SCons itself.
385 -e, --environment-overrides
386 Variables from the execution environment override construction
387 variables from the SConscript files.
390 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
393 as the initial SConscript file.
396 is in another directory,
398 will change to that directory before building targets.
402 Print a local help message for this build, if one is defined in
403 the SConscript file(s), plus a line that describes the
405 option for command-line option help. If no local help message
406 is defined, prints the standard help message about command-line
407 options. Exits after displaying the appropriate message.
411 Print the standard help message about command-line options and
416 Ignore all errors from commands executed to rebuild files.
419 .RI -I " directory" ", --include-dir=" directory
423 imported Python modules. If several
426 are used, the directories are searched in the order specified.
430 Cache implicit dependencies. This can cause
432 to miss changes in the implicit dependencies in cases where a new implicit
433 dependency is added earlier in the implicit dependency search path
434 (e.g. CPPPATH) than a current implicit dependency with the same name.
437 --implicit-deps-changed
438 Force SCons to ignore the cached implicit dependencies. This causes the
439 implicit dependencies to be rescanned and recached. This implies
440 .BR --implicit-cache .
443 --implicit-deps-unchanged
444 Force SCons to ignore changes in the implicit dependencies.
445 This causes cached implicit dependencies to always be used.
447 .BR --implicit-cache .
450 .RI -j " N" ", --jobs=" N
451 Specifies the number of jobs (commands) to run simultaneously.
452 If there is more than one
454 option, the last one is effective.
458 .\" is specified without an argument,
460 .\" will not limit the number of
461 .\" simultaneous jobs.
465 Continue as much as possible after an error. The target that
466 failed and those that depend on it will not be remade, but other
467 targets specified on the command line will still be processed.
470 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
471 .\" No new jobs (commands) will be started if
472 .\" there are other jobs running and the system load
473 .\" average is at least
475 .\" (a floating-point number).
479 .\" List derived files (targets, dependencies) that would be built,
480 .\" but do not build them.
481 .\" [XXX This can probably go away with the right
482 .\" combination of other options. Revisit this issue.]
486 .\" List derived files that would be built, with the actions
487 .\" (commands) that build them. Does not build the files.
488 .\" [XXX This can probably go away with the right
489 .\" combination of other options. Revisit this issue.]
493 .\" List derived files that would be built, plus where the file is
494 .\" defined (file name and line number). Does not build the files.
495 .\" [XXX This can probably go away with the right
496 .\" combination of other options. Revisit this issue.]
500 Ignored for compatibility with non-GNU versions of
504 .RI --max-drift= SECONDS
505 Set the maximum expected drift in the modification time of files to
507 This value determines how old a file must be before its content signature
508 is cached. The default value is 2 days, which means a file must have a
509 modification time of at least two days ago in order to have its content
510 signature cached. A negative value means to never cache the content
511 signature and to ignore the cached value if there already is one. A value
512 of 0 means to always cache the signature, no matter how old the file is.
515 -n, --just-print, --dry-run, --recon
516 No execute. Print the commands that would be executed to build
517 any out-of-date target files, but do not execute the commands.
520 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
524 .\" not rebuild anything due to changes in the contents of
527 .\" .RI --override " file"
528 .\" Read values to override specific build environment variables
529 .\" from the specified
533 .\" Print the data base (construction environments,
534 .\" Builder and Scanner objects) that are defined
535 .\" after reading the SConscript files.
536 .\" After printing, a normal build is performed
537 .\" as usual, as specified by other command-line options.
538 .\" This also prints version information
543 .\" To print the database without performing a build do:
551 Run SCons under the Python profiler
552 and save the results in the specified
554 The results may be analyzed using the Python
558 Do not run any commands, or print anything. Just return an exit
559 status that is zero if the specified targets are already up to
560 date, non-zero otherwise.
563 Quiets SCons status messages about
564 reading SConscript files,
566 and entering directories.
567 Commands that are executed
568 to rebuild target files are still printed.
571 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
572 .\" Clear the default construction variables. Construction
573 .\" environments that are created will be completely empty.
577 .\" Build dependencies in a random order. This is useful when
578 .\" building multiple trees simultaneously with caching enabled as a
579 .\" way to prevent multiple builds from simultaneously trying to build
580 .\" or retrieve the same target files.
583 -s, --silent, --quiet
584 Silent. Do not print commands that are executed to rebuild
586 Also suppresses SCons status messages.
589 -S, --no-keep-going, --stop
590 Ignored for compatibility with GNU
595 Ignored for compatibility with GNU
597 (Touching a file to make it
598 appear up-to-date is unnecessary when using
602 -u, --up, --search-up
603 Walks up the directory structure until an
608 file is found, and uses that
609 as the top of the directory tree. Only targets at or below the
610 current directory will be built.
614 Works exactly the same way as the
616 option except for the way default targets are handled.
617 When this option is used and no targets are specified on the command line,
618 all default targets that are defined in the SConscript(s) in the current
619 directory are built, regardless of what directory the resultant targets end
626 version, copyright information,
627 list of authors, and any other relevant information.
631 -w, --print-directory
632 Print a message containing the working directory before and
633 after other processing.
636 .RI --warn= type ", --warn=no-" type
637 Enable or disable warnings.
639 specifies the type of warnings to be enabled or disabled:
642 .RI --warn=all ", " --warn=no-all
643 Enables or disables all warnings.
646 .RI --warn=dependency ", " --warn=no-dependency
647 Enables or disables warnings about dependencies.
648 These warnings are disabled by default.
651 .RI --warn=deprecated ", " --warn=no-deprecated
652 Enables or disables warnings about use of deprecated features.
653 These warnings are enabled by default.
657 Turn off -w, even if it was turned on implicitly.
660 .\" .RI --write-filenames= file
661 .\" Write all filenames considered into
665 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
666 .\" Pretend that the target
669 .\" modified. When used with the
672 .\" show you what would be rebuilt if you were to modify that file.
678 .\" --warn-undefined-variables
679 .\" Warn when an undefined variable is referenced.
682 .RI -Y " repository" ", --repository=" repository
683 Search the specified repository for any input and target
684 files not found in the local directory hierarchy. Multiple
686 options may specified, in which case the
687 repositories are searched in the order specified.
689 .SH CONFIGURATION FILE REFERENCE
690 .\" .SS Python Basics
691 .\" XXX Adding this in the future would be a help.
692 .SS Construction Environments
693 A construction environment is the basic means by which the SConscript
694 files communicate build information to
696 A new construction environment is created using the
704 By default, a new construction environment is
705 initialized with a set of builder methods
706 and construction variables that are appropriate
707 for the current platform.
708 An optional platform keyword argument may be
709 used to specify that an environment should
710 be initialized for a different platform:
713 env = Environment(platform = 'cygwin')
714 env = Environment(platform = 'os2')
715 env = Environment(platform = 'posix')
716 env = Environment(platform = 'win32')
719 Specifying a platform initializes the appropriate
720 construction variables in the environment
721 to use and generate file names with prefixes
722 and suffixes appropriate for the platform.
724 The platform argument may be function or callable object,
725 in which case the Environment() method
726 will call the specified argument to update
727 the new construction environment:
730 def my_platform(env):
733 env = Environment(platform = my_platform)
736 Additionally, a specific set of tools
737 with which to initialize the environment
738 may specified as an optional keyword argument:
741 env = Environment(tools = ['msvc', 'lex'])
744 The elements of the tools list may also
745 be functions or callable objects,
746 in which case the Environment() method
747 will call the specified elements
748 to update the new construction environment:
752 env['XYZZY'] = 'xyzzy'
754 env = Environment(tools = [my_tool])
757 If no tool list is specified, then SCons will auto-detect the installed
758 tools using the PATH variable in the ENV construction variable and the
759 platform name when the Environment is constructed. Changing the PATH
760 variable after the Environment is constructed will not cause the tools to
763 SCons supports the following tool specifications
764 out of the box on all platforms:
791 On posix and cygwin platforms the GNU tools (e.g. gcc) are preferred by SCons,
792 on win32 the Microsoft tools (e.g. msvc) are preferred by SCons, and in OS/2 the IBM
793 tools (e.g. icc) are preferred by SCons.
797 Build rules are specified by calling a construction
798 environment's builder methods.
799 The arguments to the builder methods are
801 (a list of target files)
804 (a list of source files).
806 Because long lists of file names
807 can lead to a lot of quoting,
811 function that splits a single string
812 into a list, separated on
813 strings of white-space characters.
814 (This is similar to the
815 string.split() method
816 from the standard Python library.)
818 Like all Python arguments,
819 the target and source arguments to a builder
820 can be specified either with or without
821 the "target" and "source" keywords.
822 When the keywords are omitted,
824 followed by the source.
825 The following are equivalent examples of calling the Program builder:
828 env.Program('bar', ['bar.c', 'foo.c'])
829 env.Program('bar', Split('bar.c foo.c'))
830 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
831 env.Program(target = 'bar', Split('bar.c foo.c'))
832 env.Program('bar', source = string.split('bar.c foo.c'))
835 When the target shares the same base name
836 as the source and only the suffix varies,
837 and if the builder has a suffix defined for the target file type,
838 then the target argument may be omitted completely,
841 will deduce the target file name from
842 the source file name.
843 The following examples all build the
850 from the bar.c source file:
853 env.Program(target = 'bar', source = 'bar.c')
854 env.Program('bar', source = 'bar.c')
855 env.Program(source = 'bar.c')
859 It is possible to override or add construction variables when calling a
860 builder by passing additional keyword arguments. These overriden or added
861 variables will only be in effect when building the target, so they will not
862 effect other parts of the build. For example, if you want to add additional
863 libraries for just one program:
866 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
869 or generate a shared library with a nonstandard suffix:
872 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
875 All Builders return a Node or a list of Nodes,
876 representing the target or targets that will be built.
877 A list of Nodes is returned if there is more than one target,
878 and a single Node is returned if there is only one target.
881 is an internal SCons object
883 build targets or sources.
886 can be passed to other builder methods as source(s)
887 or passed into to any SCons function or method
888 where a filename would normally be accepted.
889 For example, if it were necessary
892 flag when compiling one specific object file:
895 bar_obj = env.StaticObject('bar.c', CCFLAGS='-DBAR')
896 env.Program(source = ['foo.c', bar_obj, 'main.c'])
899 Using a Node in this way
900 makes for a more portable build
901 by avoiding having to specify
902 a platform-specific object suffix
903 when calling the Program() builder.
905 The path name for a Node's file may be used
906 by passing the Node to the Python-builtin
911 bar_obj = env.StaticObject('bar.c', CCFLAGS='-DBAR')
912 print "The path to bar_obj is:", str(bar_obj)
915 provides the following builders:
918 Builds a static object file
919 from one or more C, C++, or Fortran source files.
920 Source files must have one of the following extensions:
922 .asm assembly language file
923 .ASM assembly language file
934 .F WIN32: Fortran file
935 POSIX: Fortran file + C pre-processor
938 .fpp Fortran file + C pre-processor
939 .FPP Fortran file + C pre-processor
940 .s assembly language file
941 .S WIN32: assembly language file
942 POSIX: assembly language file + C pre-processor
943 .spp assembly language file + C pre-processor
944 .SPP assembly language file + C pre-processor
947 The target object file prefix
948 (specified by the $OBJPREFIX construction variable; nothing by default)
950 (specified by the $OBJSUFFIX construction variable;
951 \.obj on Windows systems, .o on POSIX systems)
952 are automatically added to the target if not already present.
956 env.StaticObject(target = 'aaa', source = 'aaa.c')
957 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
958 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
961 Builds an object file for
962 inclusion in a shared library
963 (that is, built with the '-fPIC' option when using gcc).
964 Source files must have one of the same set of extensions
965 specified above for the
968 The target shared object file prefix
969 (specified by the $SHOBJPREFIX construction variable;
970 by default, the same as $OBJPREFIX)
972 (specified by the $SHOBJSUFFIX construction variable;
973 by default, the same as $OBJSUFFIX)
974 are automatically added to the target if not already present.
978 env.SharedObject(target = 'ddd', source = 'ddd.c')
979 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
980 env.SharedObject(target = 'fff.obj', source = 'fff.for')
989 Builds a Microsoft Visual C++ precompiled header. Calling this builder
990 returns a list of two targets: the PCH as the first element, and the object
991 file as the second element. Normally the object file is ignored. This builder is only
992 provided when Microsoft Visual C++ is being used as the compiler.
993 The PCH builder is generally used in
994 conjuction with the PCH construction variable to force object files to use
995 the precompiled header:
998 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1002 Builds an executable given one or more object files or C, C++
1003 or Fortran source files.
1004 If any C, C++ or Fortran source files are specified,
1005 then they will be automatically
1006 compiled to object files using the
1009 see that builder's description for
1010 a list of legal source file suffixes
1011 and how they are interpreted.
1012 The target executable file prefix
1013 (specified by the $PROGPREFIX construction variable; nothing by default)
1015 (specified by the $PROGSUFFIX construction variable;
1016 by default, .exe on Windows systems, nothing on POSIX systems)
1017 are automatically added to the target if not already present.
1021 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1025 Builds a Microsoft Visual C++ resource file. This builder is only
1026 provided when Microsoft Visual C++ is being used as the compiler. The
1028 suffix is added to the target name if no other suffix is given. The source
1029 file is scanned for implicit dependencies as though it were a C file. Example:
1032 env.RES('resource.rc')
1036 Builds a static library given one or more object files
1037 or C, C++ or Fortran source files.
1038 If any source files are given,
1039 then they will be automatically
1040 compiled to object files.
1041 The static library prefix and suffix (if any)
1042 are automatically added to the target.
1043 The target library file prefix
1044 (specified by the $LIBPREFIX construction variable;
1045 by default, lib on POSIX systems, nothing on Windows systems)
1047 (specified by the $LIBSUFFIX construction variable;
1048 by default, .lib on Windows systems, .a on POSIX systems)
1049 are automatically added to the target if not already present.
1053 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1057 Any object files listed in the
1059 must have been built for a static library
1064 will raise an error if there is any mismatch.
1067 Builds a shared library
1068 (.so on a POSIX system, .dll on WIN32)
1069 given one or more object files
1070 or C, C++ or Fortran source files.
1071 If any source files are given,
1072 then they will be automatically
1073 compiled to object files.
1074 The static library prefix and suffix (if any)
1075 are automatically added to the target.
1076 The target library file prefix
1077 (specified by the $SHLIBPREFIX construction variable;
1078 by default, lib on POSIX systems, nothing on Windows systems)
1080 (specified by the $SHLIBSUFFIX construction variable;
1081 by default, .dll on Windows systems, .so on POSIX systems)
1082 are automatically added to the target if not already present.
1086 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1089 On WIN32 systems, the
1091 builder will always build an import (.lib) library
1092 in addition to the shared (.dll) library,
1093 adding a .lib library with the same basename
1094 if there is not already a .lib file explicitly
1095 listed in the targets.
1097 Any object files listed in the
1099 must have been built for a shared library
1104 will raise an error if there is any mismatch.
1112 Builds a C source file given a lex (.l) or yacc (.y) input file.
1113 The suffix specified by the $CFILESUFFIX construction variable
1115 is automatically added to the target
1116 if it is not already present. Example:
1120 env.CFile(target = 'foo.c', source = 'foo.l')
1122 env.CFile(target = 'bar', source = 'bar.y')
1126 Builds a C++ source file given a lex (.ll) or yacc (.yy) input file.
1127 The suffix specified by the $CXXFILESUFFIX construction variable
1129 is automatically added to the target
1130 if it is not already present. Example:
1134 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1136 env.CXXFile(target = 'bar', source = 'bar.yy')
1140 Builds a .dvi file from a .tex, .ltx or .latex input file.
1142 (hard-coded within TeX itself)
1143 is automatically added to the target
1144 if it is not already present. Example:
1147 # builds from aaa.tex
1148 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1150 env.DVI(target = 'bbb', source = 'bbb.ltx')
1151 # builds from ccc.latex
1152 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1156 Builds a .pdf file from a .dvi input file
1157 (or, by extension, a .tex, .ltx, or .latex input file).
1158 The suffix specified by the $PDFSUFFIX construction variable
1160 is added automatically to the target
1161 if it is not already present. Example:
1164 # builds from aaa.tex
1165 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1166 # builds bbb.pdf from bbb.dvi
1167 env.PDF(target = 'bbb', source = 'bbb.dvi')
1171 Builds a .ps file from a .dvi input file
1172 (or, by extension, a .tex, .ltx, or .latex input file).
1173 The suffix specified by the $PSSUFFIX construction variable
1175 is added automatically to the target
1176 if it is not already present. Example:
1179 # builds from aaa.tex
1180 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1181 # builds bbb.ps from bbb.dvi
1182 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1187 C source files, C++ source files,
1188 Fortran source files with
1190 (POSIX systems only),
1195 and assembly language files with
1197 (POSIX systems only),
1202 for C preprocessor dependencies,
1203 so the dependencies do not need to be specified explicitly.
1204 In addition, all builder
1205 targets automatically depend on their sources.
1206 An explicit dependency can
1207 be specified using the
1209 method of a construction environment (see below).
1211 .SS Other Construction Environment Methods
1212 Additional construction environment methods include:
1215 .RI Alias( alias ", " targets )
1216 Creates a phony target that
1217 expands to one or more other targets.
1218 Returns the Node object representing the alias,
1219 which exists outside of any file system.
1220 This Node object, or the alias name,
1221 may be used as a dependency of any other target,
1222 including another alias. Alias can be called multiple times for the same
1223 alias to add additional targets to the alias.
1226 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
1227 env.Alias('install', ['/usr/local/man'])
1231 .RI Append( key = val ", [...])"
1232 Appends the specified keyword arguments
1233 to the end of construction variables in the environment.
1234 If the Environment does not have
1235 the specified construction variable,
1236 it is simply added to the environment.
1237 If the values of the construction variable
1238 and the keyword argument are the same type,
1239 then the two values will be simply added together.
1240 Otherwise, the construction variable
1241 and the value of the keyword argument
1242 are both coerced to lists,
1243 and the lists are added together.
1244 (See also the Prepend method, below.)
1247 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
1251 .RI Command( target ", " source ", " commands )
1252 Executes a specific action
1253 (or list of actions)
1254 to build a target file or files.
1255 This is more convenient
1256 than defining a separate Builder object
1257 for a single special-case build.
1259 Note that an action can be an external command,
1260 specified as a string,
1261 or a callable Python object;
1262 see "Action Objects," below.
1266 env.Command('foo.out', 'foo.in',
1267 "$FOO_BUILD < $SOURCES > $TARGET")
1269 env.Command('bar.out', 'bar.in',
1271 "$BAR_BUILD < $SOURCES > $TARGET"])
1273 def rename(env, target, source):
1275 os.rename('.tmp', str(target[0]))
1277 env.Command('baz.out', 'baz.in',
1278 ["$BAZ_BUILD < $SOURCES > .tmp",
1283 .RI Copy([ key = val ", ...])"
1284 Return a separate copy of a construction environment.
1285 If there are any keyword arguments specified,
1286 they are added to the returned copy,
1287 overwriting any existing values
1292 env3 = env.Copy(CCFLAGS = '-g')
1296 .RI Depends( target ", " dependency )
1297 Specifies an explicit dependency;
1298 the target file(s) will be rebuilt
1299 whenever the dependency file(s) has changed.
1300 This should only be necessary
1301 for cases where the dependency
1302 is not caught by a Scanner
1306 env.Depends('foo', 'other-input-file-for-foo')
1310 .RI Dictionary([ vars ])
1311 Returns a dictionary object
1312 containing copies of all of the
1313 construction variables in the environment.
1314 If there are any variable names specified,
1315 only the specified construction
1316 variables are returned in the dictionary.
1319 dict = env.Dictionary()
1320 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
1324 .RI Ignore( target ", " dependency )
1325 The specified dependency file(s)
1326 will be ignored when deciding if
1327 the target file(s) need to be rebuilt.
1330 env.Ignore('foo', 'foo.c')
1331 env.Ignore('bar', ['bar1.h', 'bar2.h'])
1335 .RI Install( dir ", " source )
1336 Installs one or more files in a destination directory.
1337 The file names remain the same.
1340 env.Install(dir = '/usr/local/bin', source = 'foo bar')
1344 .RI InstallAs( target ", " source )
1345 Installs one or more files as specific file names,
1346 allowing changing a file name as part of the
1348 It is an error if the target and source
1349 list different numbers of files.
1352 env.InstallAs(target = '/usr/local/bin/foo',
1353 source = 'foo_debug')
1354 env.InstallAs(target = '../lib/libfoo.a ../lib/libbar.a',
1355 source = 'libFOO.a libBAR.a')
1359 .RI Precious( target ", ...)"
1362 as precious so it is not deleted before it is rebuilt. Normally
1364 deletes a target before building it.
1365 Multiple targets can be passed in to a single call to
1369 .RI Prepend( key = val ", [...])"
1370 Appends the specified keyword arguments
1371 to the beginning of construction variables in the environment.
1372 If the Environment does not have
1373 the specified construction variable,
1374 it is simply added to the environment.
1375 If the values of the construction variable
1376 and the keyword argument are the same type,
1377 then the two values will be simply added together.
1378 Otherwise, the construction variable
1379 and the value of the keyword argument
1380 are both coerced to lists,
1381 and the lists are added together.
1382 (See also the Append method, above.)
1385 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
1389 .RI Replace( key = val ", [...])"
1390 Replaces construction variables in the Environment
1391 with the specified keyword arguments.
1392 (Note: "Update()" is a deprecated synonym for this method.)
1395 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
1399 .RI SideEffect( side_effect , target )
1402 as a side effect of building
1408 can be a list, a file name, or a node.
1409 A side effect is a target that is created
1410 as a side effect of building other targets.
1411 For example, a Windows PDB
1412 file is created as a side effect of building the .obj
1413 files for a static library.
1414 If a target is a side effect of multiple build commands,
1416 will ensure that only one set of commands
1417 is executed at a time.
1418 Consequently, you only need to use this method
1419 for side-effect targets that are built as a result of
1420 multiple build commands.
1422 .SS Construction Variables
1423 .\" XXX From Gary Ruben, 23 April 2002:
1424 .\" I think it would be good to have an example with each construction
1425 .\" variable description in the documentation.
1427 .\" CC The C compiler
1428 .\" Example: env["CC"] = "c68x"
1429 .\" Default: env["CC"] = "cc"
1431 .\" CCCOM The command line ...
1433 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
1434 .\" env["CC"] = "c68x"
1435 .\" env["CFLAGS"] = "-ps -qq -mr"
1436 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
1438 .\" (I dunno what this is ;-)
1439 A construction environment has an associated dictionary of construction
1440 variables that are used by built-in or user-supplied build rules. A number
1441 of useful construction variables are automatically defined by scons for
1442 each supported platform, and additional construction variables can be defined
1443 by the user. The following is a list of the automatically defined construction
1447 The static library archiver.
1450 The command line used to generate a static library from object files.
1453 General options passed to the static library archiver.
1459 The command line used to generate an object file
1460 from an assembly-language source file.
1463 General options passed to the assembler.
1466 The command line used to assemble an assembly-language
1467 source file into an object file
1468 after first running the file through the C preprocessor.
1469 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
1470 are included on this command line.
1473 A dictionary mapping the names of the builders
1474 available through this environment
1475 to underlying Builder objects.
1477 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
1478 are available by default.
1484 The command line used to compile a C source file to a (static) object file.
1485 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
1486 are included on this command line.
1489 General options that are passed to the C compiler.
1492 The suffix for C source files.
1493 This is used by the internal CFile builder
1494 when generating C files from Lex (.l) or YACC (.y) input files.
1495 The default suffix, of course, is
1498 On case-insensitive systems (like Win32),
1505 A function used to produce variables like $_CPPINCFLAGS. It takes six
1506 arguments: a prefix to concatenate onto each element, a list of elements, a
1507 suffix to concatenate onto each element, a dictionary of global variables
1508 for variable interpolation, a list of local variables for variable
1509 interpolation, and an optional function that will be called to transform the list
1510 before concatenation.
1513 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, locals(), globals(), RDirs)} $)',
1518 C preprocessor options.
1519 These will be included in any command that uses the C preprocessor,
1520 including not just compilation of C and C++ source files
1521 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
1522 but also the $F77PPCOM command line
1523 used to compile a Fortran source file,
1524 and the $ASPPCOM command line
1525 used to assemble an assembly language source file,
1526 after first running each file through the C preprocessor.
1529 An automatically-generated construction variable
1530 containing the C preprocessor command-line options
1531 for specifying directories to be searched for include files.
1532 The value of $_CPPINCFLAGS is created
1533 by appending $INCPREFIX and $INCSUFFIX
1534 to the beginning and end
1535 of each directory in $CPPPATH.
1538 The list of directories that the C preprocessor will search for include
1539 directories. The C/C++ implicit dependency scanner will search these
1540 directories for include files. Don't explicitly put include directory
1541 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
1542 and the directories will not be searched by the dependency scanner. Note:
1543 directory names in CPPPATH will be looked-up relative to the SConscript
1544 directory when they are used in a command. To force
1546 to look-up a directory relative to the root of the source tree use #:
1549 env = Environment(CPPPATH='#/include')
1553 The directory look-up can also be forced using the
1558 include = Dir('include')
1559 env = Environment(CPPPATH=include)
1563 The directory list will be added to command lines
1564 through the automatically-generated
1566 construction variable,
1567 which is constructed by
1568 appending the values of the
1569 $INCPREFIX and $INCSUFFIX
1570 construction variables
1571 to the beginning and end
1572 of each directory in $CPPPATH.
1573 Any command lines you define that need
1574 the CPPPATH directory list should
1575 include $_CPPINCFLAGS:
1578 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
1585 The suffix for C++ source files.
1586 This is used by the internal CXXFile builder
1587 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
1588 The default suffix is
1590 SCons also treats files with the suffixes
1597 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
1604 The command line used to compile a C++ source file to an object file.
1605 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
1606 are included on this command line.
1609 General options that are passed to the C++ compiler.
1612 A function that converts a file name into a Dir instance relative to the
1616 The TeX DVI file to PDF file converter.
1619 General options passed to the TeX DVI file to PDF file converter.
1622 The TeX DVI file to PostScript converter.
1625 General options passed to the TeX DVI file to PostScript converter.
1628 A dictionary of environment variables
1629 to use when invoking commands.
1630 Note that, by default,
1634 propagate the environment in force when you
1637 to the commands used to build target files.
1638 This is so that builds will be guaranteed
1639 repeatable regardless of the environment
1640 variables set at the time
1644 If you want to propagate your
1645 environment variables
1646 to the commands executed
1647 to build target files,
1648 you must do so explicitly:
1652 env = Environment(ENV = os.environ)
1656 Note that you can choose only to propagate
1657 certain environment variables.
1661 environment variable,
1664 uses the same utilities
1665 as the invoking shell (or other process):
1670 env = Environment(ENV = {'PATH' : os.environ['PATH']})
1674 A function that will be called to escape shell special characters in
1675 command lines. The function should take one argument: the command line
1676 string to escape; and should return the escaped command line.
1679 The Fortran compiler.
1682 The command line used to compile a Fortran source file to an object file.
1685 General options that are passed to the Fortran compiler.
1688 An automatically-generated construction variable
1689 containing the Fortran compiler command-line options
1690 for specifying directories to be searched for include files.
1691 The value of $_F77INCFLAGS is created
1692 by appending $INCPREFIX and $INCSUFFIX
1693 to the beginning and end
1694 of each directory in $F77PATH.
1697 The list of directories that the Fortran compiler will search for include
1698 directories. The Fortran implicit dependency scanner will search these
1699 directories for include files. Don't explicitly put include directory
1700 arguments in F77FLAGS because the result will be non-portable
1701 and the directories will not be searched by the dependency scanner. Note:
1702 directory names in F77PATH will be looked-up relative to the SConscript
1703 directory when they are used in a command. To force
1705 to look-up a directory relative to the root of the source tree use #:
1708 env = Environment(F77PATH='#/include')
1712 The directory look-up can also be forced using the
1717 include = Dir('include')
1718 env = Environment(F77PATH=include)
1722 The directory list will be added to command lines
1723 through the automatically-generated
1725 construction variable,
1726 which is constructed by
1727 appending the values of the
1728 $INCPREFIX and $INCSUFFIX
1729 construction variables
1730 to the beginning and end
1731 of each directory in $F77PATH.
1732 Any command lines you define that need
1733 the F77PATH directory list should
1734 include $_F77INCFLAGS:
1737 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
1741 The command line used to compile a Fortran source file to an object file
1742 after first running the file through the C preprocessor.
1743 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
1744 are included on this command line.
1747 A function that converts a file name into a File instance relative to the
1751 The prefix used to specify an include directory on the C compiler command
1753 This will be appended to the beginning of each directory
1754 in the $CPPPATH and $F77PATH construction variables
1755 when the $_CPPINCFLAGS and $_F77INCFLAGS
1756 variables are automatically generated.
1759 The suffix used to specify an include directory on the C compiler command
1761 This will be appended to the end of each directory
1762 in the $CPPPATH and $F77PATH construction variables
1763 when the $_CPPINCFLAGS and $_F77INCFLAGS
1764 variables are automatically generated.
1767 The LaTeX structured formatter and typesetter.
1770 The command line used to call the LaTeX structured formatter and typesetter.
1773 General options passed to the LaTeX structured formatter and typesetter.
1776 The lexical analyzer generator.
1779 General options passed to the lexical analyzer generator.
1782 The command line used to call the lexical analyzer generator
1783 to generate a source file.
1786 An automatically-generated construction variable
1787 containing the linker command-line options
1788 for specifying directories to be searched for library.
1789 The value of $_LIBDIRFLAGS is created
1790 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
1791 to the beginning and end
1792 of each directory in $LIBPATH.
1795 The prefix used to specify a library directory on the linker command line.
1796 This will be appended to the beginning of each directory
1797 in the $LIBPATH construction variable
1798 when the $_LIBDIRFLAGS variable is automatically generated.
1801 The suffix used to specify a library directory on the linker command line.
1802 This will be appended to the end of each directory
1803 in the $LIBPATH construction variable
1804 when the $_LIBDIRFLAGS variable is automatically generated.
1807 An automatically-generated construction variable
1808 containing the linker command-line options
1809 for specifying libraries to be linked with the resulting target.
1810 The value of $_LIBFLAGS is created
1811 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
1812 to the beginning and end
1813 of each directory in $LIBS.
1816 The prefix used to specify a library to link on the linker command line.
1817 This will be appended to the beginning of each library
1818 in the $LIBS construction variable
1819 when the $_LIBFLAGS variable is automatically generated.
1822 The suffix used to specify a library to link on the linker command line.
1823 This will be appended to the end of each library
1824 in the $LIBS construction variable
1825 when the $_LIBFLAGS variable is automatically generated.
1828 The list of directories that will be searched for libraries.
1829 The implicit dependency scanner will search these
1830 directories for include files. Don't explicitly put include directory
1831 arguments in LINKFLAGS because the result will be non-portable
1832 and the directories will not be searched by the dependency scanner. Note:
1833 directory names in LIBPATH will be looked-up relative to the SConscript
1834 directory when they are used in a command. To force
1836 to look-up a directory relative to the root of the source tree use #:
1839 env = Environment(LIBPATH='#/libs')
1843 The directory look-up can also be forced using the
1849 env = Environment(LIBPATH=libs)
1853 The directory list will be added to command lines
1854 through the automatically-generated
1856 construction variable,
1857 which is constructed by
1858 appending the values of the
1859 $LIBDIRPREFIX and $LIBDIRSUFFIX
1860 construction variables
1861 to the beginning and end
1862 of each directory in $LIBPATH.
1863 Any command lines you define that need
1864 the LIBPATH directory list should
1865 include $_LIBDIRFLAGS:
1868 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
1872 The prefix used for (static) library file names.
1875 An array of legal prefixes for library file names.
1878 A list of one or more libraries
1879 that will be linked with
1880 any executable programs
1881 created by this environment.
1884 The library list will be added to command lines
1885 through the automatically-generated
1887 construction variable,
1888 which is constructed by
1889 appending the values of the
1890 $LIBLINKPREFIX and $LIBLINKSUFFIX
1891 construction variables
1892 to the beginning and end
1893 of each directory in $LIBS.
1894 Any command lines you define that need
1895 the LIBS library list should
1899 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
1903 The suffix used for (static) library file names.
1906 An array of legal suffixes for library file names.
1912 General options passed to the linker.
1915 The command line used to link object files into an executable.
1918 The prefix used for (static) object file names.
1921 The suffix used for (static) object file names.
1924 The Microsoft Visual C++ precompiled header that will be used when compiling
1925 object files. This variable is ignored by tools other than Microsoft Visual C++.
1926 When this variable is
1927 defined SCons will add options to the compiler command line to
1928 cause it to use the precompiled header, and will also set up the
1929 dependencies for the PCH file. Example:
1932 env['PCH'] = 'StdAfx.pch'
1936 This variable specifies how much of a source file is precompiled. This
1937 variable is ignored by tools other than Microsoft Visual C++, or when
1938 the PCH variable is not being used. When this variable is define it
1939 must be a string that is the name of the header that
1940 is included at the end of the precompiled portion of the source files, or
1941 the empty string if the "#pragma hrdstop" construct is being used:
1944 env['PCHSTOP'] = 'StdAfx.h'
1948 The Microsoft Visual C++ PDB file that will store debugging information for
1949 object files, shared libraries, and programs. This variable is ignored by
1950 tools other than Microsoft Visual C++.
1951 When this variable is
1952 defined SCons will add options to the compiler and linker command line to
1953 cause them to generate external debugging information, and will also set up the
1954 dependencies for the PDB file. Example:
1957 env['PDB'] = 'hello.pdb'
1961 The command line used to convert TeX DVI files into a PDF file.
1964 The prefix used for PDF file names.
1967 The suffix used for PDF file names.
1970 The prefix used for executable file names.
1973 The suffix used for executable file names.
1976 The command line used to convert TeX DVI files into a PostScript file.
1979 The prefix used for PostScript file names.
1982 The prefix used for PostScript file names.
1985 The archive indexer.
1988 General options passed to the archive indexer.
1991 The resource compiler used by the RES builder.
1994 The command line used by the RES builder.
1997 The flags passed to the resource compiler by the RES builder.
2000 A function that converts a file name into a list of Dir instances by
2001 searching the repositories.
2004 A list of the available implicit dependency scanners. [CScan] by default.
2007 The C compiler used for generating shared-library objects.
2010 The command line used to compile a C source file
2011 to a shared-library object file.
2012 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
2013 are included on this command line.
2016 Options that are passed to the C compiler
2017 to generate shared-library objects.
2020 The C++ compiler used for generating shared-library objects.
2023 The command line used to compile a C++ source file
2024 to a shared-library object file.
2025 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
2026 are included on this command line.
2029 Options that are passed to the C++ compiler
2030 to generate shared-library objects.
2033 A string naming the shell program that will be passed to the
2038 construction variable for more information.
2041 The Fortran compiler used for generating shared-library objects.
2044 The command line used to compile a Fortran source file
2045 to a shared-library object file.
2048 Options that are passed to the Fortran compiler
2049 to generated shared-library objects.
2052 The command line used to compile a Fortran source file to a
2053 shared-library object file
2054 after first running the file through the C preprocessor.
2055 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
2056 are included on this command line.
2059 The prefix used for shared library file names.
2062 The suffix used for shared library file names.
2065 The linker for programs that use shared libraries.
2068 General options passed to the linker for programs using shared libraries.
2071 The prefix used for shared object file names.
2074 The suffix used for shared object file names.
2077 A command interpreter function that will be called to execute command line
2078 strings. The function must expect 4 arguments:
2081 def spawn(shell, escape, cmd, args, env):
2085 is a string naming the shell program to use.
2087 is a function that can be called to escape shell special characters in
2090 is the path to the command to be executed.
2092 is that arguments to the command.
2094 is a dictionary of the environment variables
2095 in which the command should be executed.
2101 The command line used to call the tar archiver.
2104 General options passed to the tar archiver.
2107 The suffix used for tar file names.
2110 The TeX formatter and typesetter.
2113 The command line used to call the TeX formatter and typesetter.
2116 General options passed to the TeX formatter and typesetter.
2118 .IP WIN32_INSERT_DEF
2119 When this is set to true,
2120 a library build of a WIN32 shared library (.dll file)
2121 will also build a corresponding .def file at the same time,
2122 if a .def file is not already listed as a build target.
2123 The default is 0 (do not build a .def file).
2126 The prefix used to build WIN32 .def files.
2129 The suffix used for WIN32 .def file names.
2132 The prefix used to build WIN32 shared libraries (.dll files).
2134 .IP WIN32IMPLIBPREFIX
2135 The prefix used to build WIN32 import libraries.
2138 The parser generator.
2141 The command line used to call the parser generator
2142 to generate a source file.
2145 General options passed to the parser generator.
2148 Construction variables can be retrieved and set using the
2150 method of the construction environment:
2153 dict = env.Dictionary()
2157 or using the [] operator:
2163 Construction variables can also be passed to the construction environment
2167 env = Environment(CC="cc")
2170 or when copying a construction environment using the
2175 env2 = env.Copy(CC="cl.exe")
2178 .SS Costruction Variable Options
2180 Often when building software, various options need to be specified at build
2181 time that are not known when the SConstruct/SConscript files are
2182 written. For example, libraries needed for the build may be in non-standard
2183 locations, or site-specific compiler options may need to be passed to the
2186 provides a mechanism for overridding construction variables from the
2187 command line or a text-based SConscript file through an Options
2188 object. To create an Options object, call the Options() function:
2191 .RI Options([ file ])
2192 This creates an Options object that will read construction variables from
2193 the filename based in the
2195 argument. If no filename is given, then no file will be read. Example:
2198 opts = Options('custom.py')
2201 Options objects have the following methods:
2204 .RI Add( key ", [" help ", " default ", " validater ", " converter ])
2205 This adds a customizable construction variable to the Options object.
2207 is the name of the variable.
2209 is the help text for the variable.
2211 is the default value of the variable.
2213 is called to validate the value of the variable, and should take two
2214 arguments: key and value.
2216 is called to convert the value before putting it in the environment, and
2217 should take a single argument: value. Example:
2220 opts.Add('CC', 'The C compiler')
2225 This updates a construction environment
2227 with the customized construction variables. Normally this method is not
2228 called directly, but is called indirectly by passing the Options object to
2229 the Environment() function:
2232 env = Environment(options=opts)
2236 .RI GenerateHelpText( env )
2237 This generates help text documenting the customizable construction
2238 variables suitable to passing in to the Help() function.
2240 is the construction environment that will be used to get the actual values
2241 of customizable variables. Example:
2244 Help(opts.GenerateHelpText(env))
2247 The text based SConscript file is executed as a Python script, and the
2248 global variables are queried for customizable construction
2258 also provides various additional functions,
2259 not associated with a construction environment,
2260 that SConscript files can use:
2263 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2264 This specifies a build directory to use for all derived files.
2266 specifies the build directory to be used for all derived files that would
2267 normally be built under
2269 Multiple build directories can be set up for multiple build variants, for
2272 must be underneath the SConstruct file's directory,
2275 may not be underneath the
2279 will link or copy (depending on the platform) all the source files into the
2282 is set to 1 (the default). If
2286 will not copy or link any source files, which may cause build problems in
2287 certain situations (e.g. C source files that are generated by the
2290 is usually safe, and is always more efficient than
2294 .RI Clean ( target, files_or_dirs )
2295 This specifies a list of files or directories which should be removed
2296 whenever the target is specified with the
2298 command line option.
2302 and create a new target or add files and directories to the
2303 clean list for the specified target.
2305 Multiple files or directories should be specified
2306 either as separate arguments to the
2308 method, or as a list.
2310 will also accept the return value of any of the construction environment
2315 Clean('foo', ['bar', 'baz'])
2316 Clean('dist', env.Program('hello', 'hello.c'))
2320 .RI Default( targets )
2321 This specifies a list of default targets,
2322 which will be built by
2324 if no explicit targets are given on the command line.
2328 and add to the list of default targets.
2330 Multiple targets should be specified as
2331 separate arguments to the
2333 method or as a list.
2335 will also accept the return value of any of the construction environment
2340 Default('foo', 'bar', 'baz')
2341 Default(['a', 'b', 'c'])
2342 Default(env.Program('hello', 'hello.c'))
2346 .RI Dir( name ", [" directory ])
2347 This returns an object that represents a given directory
2350 can be a relative or absolute path.
2352 is an optional directory that will be used as the parent directory.
2355 .RI EnsurePythonVersion( major ", " minor )
2356 Ensure that the Python version is at least
2359 print out an error message and exit SCons with a non-zero exit code if the
2360 actual Python version is not late enough.
2363 EnsurePythonVersion(2,2)
2367 .RI EnsureSConsVersion( major ", " minor )
2368 Ensure that the SCons version is at least
2371 print out an error message and exit SCons with a non-zero exit code if the
2372 actual SCons version is not late enough.
2375 EnsureSConsVersion(0,9)
2382 to export a list of variables from the current
2383 SConscript file to all other SConscript files. The exported variables
2384 are kept in a global collection, so subsequent exports
2385 will over-write previous exports that have the same name.
2386 Multiple variable names should be passed to
2388 as separate arguments. Examples:
2392 Export("env", "variable")
2396 .RI File( name ", [" directory ])
2397 This returns an object that represents a given file
2400 can be a relative or absolute path.
2402 is an optional directory that will be used as the parent directory.
2405 .RI FindFile( file ", " dirs )
2408 in the path specified by
2411 may be a list of file names or a single file name. In addition to searching
2412 for files that exist in the filesytem, this function also searches for
2413 derived files that have not yet been built.
2416 foo = FindFile('foo', ['dir1', 'dir2'])
2420 .\".RI GetBuildPath( XXX )
2424 .\".RI GetLaunchDir( XXX )
2429 Get the number of jobs (commands) that will be run simultaneously. See also
2436 This specifies help text to be printed if the
2438 argument is given to
2441 will exit after printing out the help text.
2447 to import a list of variables into the current SConscript file. This
2448 will import variables that were exported with
2454 Variables exported by
2457 Multiple variable names should be passed to
2459 as separate arguments.
2464 Import("env", "variable")
2468 .RI Literal( string )
2471 will be preserved as-is
2472 and not have construction variables expanded.
2475 .RI Local( targets )
2478 will have copies made in the local tree,
2479 even if an already up-to-date copy
2480 exists in a repository.
2483 .RI ParseConfig( env , command ", [" function ])
2486 to modify the specified environment
2488 as specified by the output of
2492 expects the output of a typical
2496 and parses the returned
2511 .RI Platform( string )
2512 Returns a callable object
2513 that can be used to initialize
2514 a construction environment using the
2515 platform keyword of the Environment() method.
2518 env = Environment(platform = Platform('win32'))
2522 .RI Repository( directory )
2525 is a repository to be searched for files.
2529 and each one adds to the list of
2530 repositories that will be searched.
2534 a repository is a copy of the source tree,
2535 from the top-level directory on down,
2537 both source files and derived files
2538 that can be used to build targets in
2539 the local source tree.
2540 The canonical example would be an
2541 official source tree maintained by an integrator.
2542 If the repository contains derived files,
2543 then the derived files should have been built using
2545 so that the repository contains the necessary
2546 signature information to allow
2548 to figure out when it is appropriate to
2549 use the repository copy of a derived file,
2550 instead of building one locally.
2552 Note that if an up-to-date derived file
2553 already exists in a repository,
2557 make a copy in the local directory tree.
2558 In order to guarantee that a local copy
2568 what variable(s) to use as the return value(s) of the current SConscript
2569 file. These variables will be returned to the "calling" SConscript file
2570 as the return value(s) of
2572 Multiple variable names should be passed to
2578 Return(["foo", "bar"])
2582 .RI SConscript( script ", [" exports ])
2587 as a SConscript (configuration) file. The optional
2589 argument provides a list of variable names to export to
2594 function to import the variables. Any variables returned by
2598 will be returned by the call to
2603 SConscript('dir/SConscript')
2604 foo = SConscript('subdir/SConscript', "env")
2608 .RI SConscriptChdir( value )
2614 to change its working directory (chdir)
2615 to the directory in which each subsidiary
2616 SConscript file lives.
2617 Note that you may enable and disable
2618 this ability by calling
2624 SConscript('foo/SConscript') # will chdir to foo
2626 SConscript('bar/SConscript') # will not chdir to bar
2630 .RI SetBuildSignatureType( type )
2632 This function tells SCons what type of build signature to use: "build" or
2633 "content". "build" means to concatenate the signatures of all source files
2634 of a derived file to make its signature, and "content" means to use
2635 the derived files content signature as its signature. "build" signatures
2636 are usually faster to compute, but "content" signatures can prevent
2637 redundant rebuilds. The default is "build".
2640 .RI SetContentSignatureType( type )
2642 This function tells SCons what type of content signature to use: "MD5" or
2643 "timestamp". "MD5" means to use the MD5 checksum of a files contents as
2644 its signature, and "timestamp" means to use a files timestamp as its
2645 signature. When using "timestamp" signatures, changes in the
2646 command line will not cause files to be rebuilt. "MD5" signatures take
2647 longer to compute, but "timestamp" signatures are less accurate. The
2652 Specifies the number of jobs (commands) to run simultaneously.
2654 overrides this function. See also
2661 Returns a list of file names or other objects.
2663 it will be split on strings of white-space characters
2665 making it easier to write long lists of file names.
2666 If arg is already a list,
2667 the list will be returned untouched.
2668 If arg is any other type of object,
2669 it will be returned as a list
2670 containing just the object.
2673 files = Split("f1.c f2.c f3.c")
2683 Returns a callable object
2684 that can be used to initialize
2685 a construction environment using the
2686 tools keyword of the Environment() method.
2689 env = Environment(tools = [ Tool('msvc') ])
2693 .RI WhereIs( program ", [" path ", [" pathext ]])
2695 Searches for the specified executable
2697 returning the full path name to the program
2699 and returning None if not.
2700 Searches the specified
2702 or the user's current PATH
2703 (os.environ['PATH'])
2705 On Win32 systems, searches for executable
2706 programs with any of the file extensions
2707 listed in the specified
2709 or the user's current PATHEXT
2710 (os.environ['PATHEXT'])
2716 can be extended by adding new builders to a construction
2717 environment using the
2722 function accepts the following arguments:
2725 The name of the builder. This will be the
2726 name of the construction environment method
2727 used to create an instance of the builder.
2730 The command line string used to build the target from the source.
2733 a list of strings representing the command
2734 to be executed and its arguments
2735 (suitable for enclosing white space in an argument),
2737 mapping source file name suffixes to
2738 any combination of command line strings
2739 (if the builder should accept multiple source file extensions),
2742 (see the next section);
2743 or a list of any of the above.
2746 takes three arguments:
2748 - a list of source nodes,
2750 - a list of target nodes,
2752 - the construction environment.
2755 Specifies whether this builder is allowed to be called multiple times for
2756 the same target file(s). The default is 0, which means the builder
2757 can not be called multiple times for the same target file(s). Calling a
2758 builder multiple times for the same target simply adds additional source
2759 files to the target; it is not allowed to change the environment associated
2760 with the target, specify addition environment overrides, or associate a different
2761 builder with the target.
2764 The prefix that will be prepended to the target file name.
2767 The suffix that will be appended to the target file name.
2770 The expected source file name suffix.
2773 Specifies a builder to use when a source file name suffix does not match
2774 any of the suffixes of the builder. Using this argument produces a
2775 multi-stage builder.
2778 A function that is passed the target, source, and environment,
2779 and which returns a tuple containing two lists,
2780 the list of targets to be built by this builder,
2781 and the list of sources for this builder.
2782 This allows the target and source lists to
2783 be manipulated before the target(s) are actually built.
2785 The emitter function
2786 takes three arguments:
2788 - a list of source nodes,
2790 - a list of target nodes,
2792 - the construction environment.
2797 def e(target, source, env):
2798 return (target + ['foo.foo'], source + ['foo.src'])
2800 b = Builder(emitter=e)
2804 A function that returns a list of actions that will be executed to build
2805 the target(s) from the source(s).
2806 The returned action(s) may be
2807 an Action object, or anything that
2808 can be converted into an Action object
2809 (see the next section).
2811 The generator function
2812 takes four arguments:
2814 - a list of source nodes,
2816 - a list of target nodes,
2818 - the construction environment.
2820 - a Boolean value that specifies
2821 whether the generator is being called
2822 for generating a build signature
2823 (as opposed to actually executing the command).
2827 def g(source, target, env, for_signature):
2828 return [["gcc", "-c", "-o"] + target + source]
2830 b = Builder(generator=g)
2837 arguments must not both be used for the same Builder.
2839 Any additional keyword arguments supplied
2840 when a Builder object is called
2841 will be associated with the target
2842 (and any other files built as a
2843 result of the call).
2846 b = Builder(action="build < $SOURCE > $TARGET")
2847 env = Environment(BUILDERS = {'MyBuild' : b})
2848 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
2851 These extra keyword arguments are passed to the
2852 following functions:
2853 command generator functions,
2855 and emitter functions.
2859 The Builder function will turn its
2861 keyword argument into an appropriate
2862 internal Action object.
2863 Occasionally, it may be more efficient
2864 to create an explicit Action object
2865 and use it to initialize multiple
2867 rather than let each separate Builder object
2868 create a separate Action.
2870 The Action method takes one or two arguments
2871 and returns an appropriate object for the action
2872 represented by the type of the first argument:
2875 If the first argument is already an Action object,
2876 the object is simply returned.
2879 If the first argument is a string,
2880 a command-line Action is returned.
2883 Action('$CC -c -o $TARGET $SOURCES')
2886 .\" XXX From Gary Ruben, 23 April 2002:
2887 .\" What would be useful is a discussion of how you execute command
2888 .\" shell commands ie. what is the process used to spawn the shell, pass
2889 .\" environment variables to it etc., whether there is one shell per
2890 .\" environment or one per command etc. It might help to look at the Gnu
2891 .\" make documentation to see what they think is important to discuss about
2892 .\" a build system. I'm sure you can do a better job of organising the
2893 .\" documentation than they have :-)
2897 If the first argument is a list,
2898 then a list of Action objects is returned.
2899 An Action object is created as necessary
2900 for each element in the list.
2903 the list is itself a list,
2904 the internal list is the
2905 command and arguments to be executed via
2907 This allows white space to be enclosed
2908 in an argument by defining
2909 a command in a list within a list:
2911 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
2915 If the first argument is a Python function,
2916 a function Action is returned.
2917 The Python function takes three keyword arguments,
2919 (a Node object representing the target file),
2921 (a Node object representing the source file)
2924 (the construction environment
2925 used for building the target file).
2930 arguments may be lists of Node objects if there is
2931 more than one target file or source file.
2932 The actual target and source file name(s) may
2933 be retrieved from their Node objects
2934 via the built-in Python str() function:
2936 target_file_name = str(target)
2937 source_file_names = map(lambda x: str(x), source)
2940 The function should return
2944 to indicate a successful build of the target file(s).
2945 The function may raise an exception
2946 or return a non-zero exit status
2947 to indicate an unsuccessful build.
2950 def build_it(target = None, source = None, env = None):
2951 # build the target from the source
2954 a = Action(build_it)
2957 The second, optional argument
2958 is a Python function that returns
2959 a string to be printed describing the action being executed.
2960 This function takes two arguments,
2961 an array of targets to be created by the function action,
2962 and an array of sources used to create the target(s):
2964 def build_it(target, source, env):
2965 # build the target from the source
2968 def string_it(target, source):
2969 return "building '%s' from '%s'" % (target[0], source[0])
2971 a = Action(build_it, string_it)
2973 If the action argument is not one of the above,
2976 .SS Variable Substitution
2978 Before executing a command,
2980 performs construction variable interpolation on the strings that make up
2981 the command line of builders.
2982 Variables are introduced by a
2985 Besides construction variables, scons provides the following
2986 variables for each command execution:
2989 The file name of the target being built, or the file name of the first
2990 target if multiple targets are being built.
2993 The file names of all targets being built.
2996 The file name of the source of the build command, or the file name of the
2997 first source if multiple sources are being built.
3000 The file names of the sources of the build command.
3003 For example, given the construction variable CC='cc', targets=['foo'], and
3004 sources=['foo.c', 'bar.c']:
3007 action='$CC -c -o $TARGET $SOURCES'
3010 would produce the command line:
3013 cc -c -o foo foo.c bar.c
3016 Variable names may be surrounded by curly braces ({})
3017 to separate the name from the trailing characters.
3018 Within the curly braces, a variable name may have
3019 a Python slice subscript appended to select one
3020 or more items from a list.
3021 In the previous example, the string:
3033 Additionally, a variable name may
3034 have the following special
3035 modifiers appended within the enclosing curly braces
3036 to modify the interpolated string:
3039 The base path of the file name,
3040 including the directory path
3041 but excluding any suffix.
3044 The name of the directory in which the file exists.
3048 minus any directory portion.
3051 Just the basename of the file,
3053 and minus the directory.
3056 Just the file suffix.
3059 The absolute path name of the file.
3062 For example, the specified target will
3063 expand as follows for the corresponding modifiers:
3066 $TARGET => sub/dir/file.x
3067 ${TARGET.base} => sub/dir/file
3068 ${TARGET.dir} => sub/dir
3069 ${TARGET.file} => file.x
3070 ${TARGET.filebase} => file
3071 ${TARGET.suffix} => .x
3072 ${TARGET.abspath} => /top/dir/sub/dir/file.x
3076 The special pseudo-variables
3080 may be used to surround parts of a command line
3083 causing a rebuild--that is,
3084 which are not included in the signature
3085 of target files built with this command.
3090 will be removed from the command line
3091 before it is added to file signatures,
3096 will be removed before the command is executed.
3097 For example, the command line:
3100 echo Last build occurred $( $TODAY $). > $TARGET
3104 would execute the command:
3107 echo Last build occurred $TODAY. > $TARGET
3111 but the command signature added to any target files would be:
3114 echo Last build occurred . > $TARGET
3117 SCons uses the following rules when converting construction variables into
3121 When the value is a string it is interpreted as a space delimited list of
3122 command line arguments.
3125 When the value is a list it is interpreted as a list of command line
3126 arguments. Each element of the list is converted to a string.
3129 Anything that is not a list or string is converted to a string and
3130 interpreted as a single command line argument.
3133 Newline characters (\\n) delimit lines. The newline parsing is done after
3134 all other parsing, so it is not possible for arguments (e.g. file names) to
3135 contain embedded newline characters. This limitation will likely go away in
3136 a future version of SCons.
3144 new file types for implicit dependencies.
3145 Scanner accepts the following arguments:
3148 The name of the Scanner.
3150 to identify the Scanner internally.
3153 An optional argument that, if specified,
3154 will be passed to the scanner function.
3157 An optional list that can be used to
3158 determine which scanner should be used for
3160 In the usual case of scanning for file names,
3161 this array can be a list of suffixes
3162 for the different file types that this
3163 Scanner knows how to scan.
3166 A Python function that will process
3168 and return a list of strings (file names)
3169 representing the implicit
3170 dependencies found in the contents.
3171 The function takes three or four arguments:
3173 def scanner_function(node, env, target):
3175 def scanner_function(node, env, target, arg):
3179 argument is the internal
3180 SCons node representing the file.
3183 to fetch the name of the file, and
3184 .B node.get_contents()
3185 to fetch contents of the file.
3189 argument is the construction environment for the scan.
3190 Fetch values from it using the
3196 argument is the internal
3197 SCons node representing the target file.
3201 argument is the argument supplied
3202 when the scanner was created, if any.
3205 An optional Python function that takes a Node (file)
3206 as an argument and returns whether the
3207 Node should, in fact,
3208 be scanned for dependencies.
3209 This check can be used to eliminate unnecessary
3210 calls to the scanner function when,
3211 for example, the underlying file
3212 represented by a Node does not yet exist.
3214 .SH SYSTEM-SPECIFIC BEHAVIOR
3215 SCons and its configuration files are very portable,
3216 due largely to its implementation in Python.
3217 There are, however, a few portability
3218 issues waiting to trap the unwary.
3220 SCons handles the upper-case
3222 file suffix differently,
3223 depending on the capabilities of
3224 the underlying system.
3225 On a case-sensitive system
3226 such as Linux or UNIX,
3227 SCons treats a file with a
3229 suffix as a C++ source file.
3230 On a case-insensitive system
3232 SCons treats a file with a
3234 suffix as a C source file.
3236 SCons handles the upper-case
3238 file suffix differently,
3239 depending on the capabilities of
3240 the underlying system.
3241 On a case-sensitive system
3242 such as Linux or UNIX,
3243 SCons treats a file with a
3245 suffix as a Fortran source file
3246 that is to be first run through
3247 the standard C preprocessor.
3248 On a case-insensitive system
3250 SCons treats a file with a
3252 suffix as a Fortran source file that should
3254 be run through the C preprocessor.
3255 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
3256 Cygwin supplies a set of tools and utilities
3257 that let users work on a
3258 Windows system using a more POSIX-like environment.
3259 The Cygwin tools, including Cygwin Python,
3261 by sharing an ability to interpret UNIX-like path names.
3262 For example, the Cygwin tools
3263 will internally translate a Cygwin path name
3264 like /cygdrive/c/mydir
3265 to an equivalent Windows pathname
3266 of C:/mydir (equivalent to C:\\mydir).
3269 that are built for native Windows execution,
3270 such as the python.org and ActiveState versions,
3271 do not have the Cygwin path name semantics.
3272 This means that using a native Windows version of Python
3273 to build compiled programs using Cygwin tools
3274 (such as gcc, bison, and flex)
3275 may yield unpredictable results.
3276 "Mixing and matching" in this way
3277 can be made to work,
3278 but it requires careful attention to the use of path names
3279 in your SConscript files.
3281 In practice, users can sidestep
3282 the issue by adopting the following rules:
3284 use the Cygwin-supplied Python interpreter
3286 when using Microsoft Visual C/C++
3287 (or some other Windows compiler)
3288 use the python.org or ActiveState version of Python
3290 .SS WIN32: scons.bat file
3292 SCons is executed via a wrapper
3295 This has (at least) two ramifications:
3297 First, Windows command-line users
3298 that want to use variable assignment
3300 may have to put double quotes
3301 around the assignments:
3304 scons "FOO=BAR" "BAZ=BLEH"
3307 Second, the Cygwin shell does not
3308 recognize this file as being the same
3311 command issued at the command-line prompt.
3312 You can work around this either by
3315 from the Cygwin command line,
3316 or by creating a wrapper shell
3322 To help you get started using SCons,
3323 this section contains a brief overview of some common tasks.
3327 build all of its targets by default,
3328 like other build tools do.
3329 The canonical way to invoke SCons
3330 is with a target of '.' (dot)
3331 to represent all targets in and below the current directory:
3337 One or more default targets may be specified
3338 via the Default() method
3339 in the SConstruct file.
3341 .SS Basic Compilation From a Single Source File
3345 env.Program(target = 'foo', source = 'foo.c')
3348 Note: Build the file by specifying
3349 the target as an argument
3350 ("scons foo" or "scons foo.exe").
3351 or by specifying a dot ("scons .").
3353 .SS Basic Compilation From Multiple Source Files
3357 env.Program(target = 'foo', source = 'f1.c f2.c f3.c')
3360 .SS Setting a Compilation Flag
3363 env = Environment(CCFLAGS = '-g')
3364 env.Program(target = 'foo', source = 'foo.c')
3367 .SS Search The Local Directory For .h Files
3371 need to set CCFLAGS to specify -I options by hand.
3372 SCons will construct the right -I options from CPPPATH.
3375 env = Environment(CPPPATH = ['.'])
3376 env.Program(target = 'foo', source = 'foo.c')
3379 .SS Search Multiple Directories For .h Files
3382 env = Environment(CPPPATH = ['include1', 'include2'])
3383 env.Program(target = 'foo', source = 'foo.c')
3386 .SS Building a Static Library
3390 env.StaticLibrary(target = 'foo', source = 'l1.c l2.c')
3393 .SS Building a Shared Library
3397 env.SharedLibrary(target = 'foo', source = 'l3.c l4.c')
3400 .SS Linking a Local Library Into a Program
3403 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
3404 env.Library(target = 'mylib', source = 'l1.c l2.c')
3405 env.Program(target = 'prog', source = 'p1.c p2.c')
3408 .SS Defining Your Own Builder Object
3410 Notice that when you invoke the Builder,
3411 you can leave off the target file suffix,
3412 and SCons will add it automatically.
3415 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
3417 src_suffix = '.tex')
3418 env = Environment(BUILDERS = {'PDFBuilder' : bld})
3419 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
3421 # The following creates "bar.pdf" from "bar.tex"
3422 env.PDFBuilder(target = 'bar', source = 'bar')
3425 .SS Defining Your Own Scanner Object
3430 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
3432 def kfile_scan(node, env, target, arg):
3433 contents = node.get_contents()
3434 includes = include_re.findall(contents)
3437 kscan = Scanner(name = 'kfile',
3438 function = kfile_scan,
3441 scanners = Environment().Dictionary('SCANNERS')
3442 env = Environment(SCANNERS = scanners + [kscan])
3444 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
3446 bar_in = File('bar.in')
3447 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
3448 bar_in.target_scanner = kscan
3451 .SS Creating a Hierarchical Build
3453 Notice that the file names specified in a subdirectory's
3455 file are relative to that subdirectory.
3461 env.Program(target = 'foo', source = 'foo.c')
3463 SConscript('sub/SConscript')
3468 # Builds sub/foo from sub/foo.c
3469 env.Program(target = 'foo', source = 'foo.c')
3471 SConscript('dir/SConscript')
3476 # Builds sub/dir/foo from sub/dir/foo.c
3477 env.Program(target = 'foo', source = 'foo.c')
3480 .SS Sharing Variables Between SConscript Files
3482 You must explicitly Export() and Import() variables that
3483 you want to share between SConscript files.
3489 env.Program(target = 'foo', source = 'foo.c')
3492 SConscript('subdirectory/SConscript')
3494 subdirectory/SConscript:
3497 env.Program(target = 'foo', source = 'foo.c')
3500 .SS Building Multiple Variants From the Same Source
3502 Use the BuildDir() method to establish
3503 one or more separate build directories for
3504 a given source directory,
3505 then use the SConscript() method
3506 to specify the SConscript files
3507 in the build directories:
3514 BuildDir('foo', 'src')
3515 SConscript('foo/SConscript')
3519 BuildDir('bar', 'src')
3520 SConscript('bar/SConscript')
3525 env = Environment(CCFLAGS = ccflags)
3526 env.Program(target = 'src', source = 'src.c')
3529 Note the use of the Export() method
3530 to set the "ccflags" variable to a different
3531 value for each variant build.
3533 .SS Hierarchical Build of Two Libraries Linked With a Program
3538 env = Environment(LIBPATH = ['#libA', '#libB'])
3540 SConscript('libA/SConscript')
3541 SConscript('libB/SConscript')
3542 SConscript('Main/SConscript')
3547 env.Library('a', 'a1.c a2.c a3.c')
3552 env.Library('b', 'b1.c b2.c b3.c')
3557 e = env.Copy(LIBS = ['a', ','b'])
3558 e.Program('foo', 'm1.c m2.c m3.c')
3561 The '#' in the LIBPATH directories specify that they're relative to the
3562 top-level directory, so they don't turn into "Main/libA" when they're
3563 used in Main/SConscript.
3565 Specifying only 'a' and 'b' for the library names
3566 allows SCons to append the appropriate library
3567 prefix and suffix for the current platform
3568 (for example, 'liba.a' on POSIX systems,
3569 'a.lib' on Windows).
3571 .SS Customizing contruction variables from the command line.
3573 The following would allow the C compiler to be specified on the command
3574 line or in the file custom.py.
3577 opts = Options('custom.py')
3578 opts.Add('CC', 'The C compiler.')
3579 env = Environment(options=opts)
3580 Help(opts.GenerateHelpText(env))
3583 The user could specify the C compiler on the command line:
3589 or in the custom.py file:
3595 or get documentation on the options:
3606 .SS Using Microsoft Visual C++ precompiled headers
3608 Since windows.h includes everything and the kitchen sink, it can take quite
3609 some time to compile it over and over again for a bunch of object files, so
3610 Microsoft provides a mechanism to compile a set of headers once and then
3611 include the previously compiled headers in any object file. This
3612 technology is called precompiled headers. The general recipe is to create a
3613 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
3614 then include every header you want to precompile in "StdAfx.h", and finally
3615 include "StdAfx.h" as the first header in all the source files you are
3616 compiling to object files. For example:
3620 #include <windows.h>
3621 #include <my_big_header.h>
3640 /* do some other stuff */
3646 env['PCHSTOP'] = StdAfx.h
3647 env['PCH'] = env.PCH('StdAfx.cpp')[0]
3648 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
3651 For more information see the document for the PCH builder, and the PCH and
3652 PCHSTOP construction variables. To learn about the details of precompiled
3653 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
3655 .SS Using Microsoft Visual C++ external debugging information
3657 Since including debugging information in programs and shared libraries can
3658 cause their size to increase significantly, Microsoft provides a mechanism
3659 for including the debugging information in an external file called a PDB
3660 file. SCons supports PDB files through the PDB construction
3666 env['PDB'] = 'MyApp.pdb'
3667 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
3670 For more information see the document for the PDB construction variable.
3675 Specifies the directory that contains the SCons Python module directory
3676 (e.g. /home/aroach/scons-src-0.01/src/engine).
3679 A string of options that will be used by scons in addition to those passed
3680 on the command line.
3691 Steven Knight <knight@baldmt.com>
3693 Anthony Roach <aroach@electriceyeball.com>