be redetected.
SCons supports the following tool specifications out of the box:
-
.ES
386asm
aixc++
.B scons
supplies a
.B Split()
-global function
-and a same-named environment method
-that split a single string
+function that splits a single string
into a list, separated on
strings of white-space characters.
-(These are similar to the
+(This is similar to the
string.split() method
-from the standard Python library,
-but work even if the input isn't a string.)
+from the standard Python library.)
Like all Python arguments,
-the target and source arguments to a builder method
+the target and source arguments to a builder
can be specified either with or without
the "target" and "source" keywords.
When the keywords are omitted,
the target is first,
followed by the source.
-The following are equivalent examples of calling the Program builder method:
+The following are equivalent examples of calling the Program builder:
.ES
env.Program('bar', ['bar.c', 'foo.c'])
env.Program('bar', Split('bar.c foo.c'))
-env.Program('bar', env.Split('bar.c foo.c'))
env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
env.Program(target = 'bar', Split('bar.c foo.c'))
-env.Program(target = 'bar', env.Split('bar.c foo.c'))
env.Program('bar', source = string.split('bar.c foo.c'))
.EE
When the target shares the same base name
as the source and only the suffix varies,
-and if the builder method has a suffix defined for the target file type,
+and if the builder has a suffix defined for the target file type,
then the target argument may be omitted completely,
and
.B scons
.EE
It is possible to override or add construction variables when calling a
-builder method by passing additional keyword arguments.
-These overridden or added
+builder by passing additional keyword arguments. These overridden or added
variables will only be in effect when building the target, so they will not
affect other parts of the build. For example, if you want to add additional
libraries for just one program:
env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
.EE
-Although the builder methods defined by
-.B scons
-are, in fact,
-methods of a construction environment object,
-they may also be called without an explicit environment:
-
-.ES
-Program('hello', 'hello.c')
-SharedLibrary('word', 'word.cpp')
-.EE
-
-In this case,
-the methods are called internally using a default construction
-environment that consists of the tools and values that
-.B scons
-has determined are appropriate for the local system.
-
-All builder methods return a Node or a list of Nodes,
+All Builders return a Node or a list of Nodes,
representing the target or targets that will be built.
A list of Nodes is returned if there is more than one target,
and a single Node is returned if there is only one target.
The returned Node(s)
can be passed to other builder methods as source(s)
-or passed to any SCons function or method
+or passed into to any SCons function or method
where a filename would normally be accepted.
For example, if it were necessary
to add a specific
makes for a more portable build
by avoiding having to specify
a platform-specific object suffix
-when calling the Program() builder method.
+when calling the Program() builder.
The path name for a Node's file may be used
by passing the Node to the Python-builtin
.EE
.B scons
-provides the following builder methods:
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP CFile()
-.IP env.CFile()
-Builds a C source file given a lex (.l) or yacc (.y) input file.
-The suffix specified by the $CFILESUFFIX construction variable
-(.c by default)
-is automatically added to the target
-if it is not already present. Example:
-
-.ES
-# builds foo.c
-env.CFile(target = 'foo.c', source = 'foo.l')
-# builds bar.c
-env.CFile(target = 'bar', source = 'bar.y')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP CXXFile()
-.IP env.CXXFile()
-Builds a C++ source file given a lex (.ll), yacc (.yy)
-or uic (.ui) input file.
-The suffix specified by the $CXXFILESUFFIX construction variable
-(.cc by default)
-is automatically added to the target
-if it is not already present. Example:
-
-.ES
-# builds foo.cc
-env.CXXFile(target = 'foo.cc', source = 'foo.ll')
-# builds bar.cc
-env.CXXFile(target = 'bar', source = 'bar.yy')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP DVI()
-.IP env.DVI()
-Builds a .dvi file from a .tex, .ltx or .latex input file.
-If the source file suffix is .tex,
-.B scons
-will examine the contents of the file;
-if the string
-.B \\documentclass
-or
-.B \\documentstyle
-is found, the file is assumed to be a LaTeX file and
-the target is built by invoking the $LATEXCOM command line;
-otherwise, the $TEXCOM command line is used.
-If the file is a LaTeX file,
-the
-.B DVI
-builder method will also examine the contents
-of the
-.B .aux file
-and invoke the $BIBTEX command line
-if the string
-.B bibdata
-is found,
-and will examine the contents
-.B .log
-file and re-run the $LATEXCOM command
-if the log file says it is necessary.
-
-The suffix .dvi
-(hard-coded within TeX itself)
-is automatically added to the target
-if it is not already present. Examples:
+provides the following builders:
+.IP StaticObject
+Builds a static object file
+from one or more C, C++, or Fortran source files.
+Source files must have one of the following extensions:
.ES
-# builds from aaa.tex
-env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
-# builds bbb.dvi
-env.DVI(target = 'bbb', source = 'bbb.ltx')
-# builds from ccc.latex
-env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
+ .asm assembly language file
+ .ASM assembly language file
+ .c C file
+ .C WIN32: C file
+ POSIX: C++ file
+ .cc C++ file
+ .cpp C++ file
+ .cxx C++ file
+ .cxx C++ file
+ .c++ C++ file
+ .C++ C++ file
+ .f Fortran file
+ .F WIN32: Fortran file
+ POSIX: Fortran file + C pre-processor
+ .for Fortran file
+ .FOR Fortran file
+ .fpp Fortran file + C pre-processor
+ .FPP Fortran file + C pre-processor
+ .s assembly language file
+ .S WIN32: assembly language file
+ POSIX: assembly language file + C pre-processor
+ .spp assembly language file + C pre-processor
+ .SPP assembly language file + C pre-processor
.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Jar()
-.IP env.Jar()
-Builds a Java archive (.jar) file
-from a source tree of .class files.
-If the $JAVACHDIR value is set, the
-.B jar
-command will change to the specified directory using the
-.B \-C
-option.
-If the contents any of the source files begin with the string
-.BR Manifest-Version ,
-the file is assumed to be a manifest
-and is passed to the
-.B jar
-command with the
-.B m
-option set.
+.IP
+The target object file prefix
+(specified by the $OBJPREFIX construction variable; nothing by default)
+and suffix
+(specified by the $OBJSUFFIX construction variable;
+\.obj on Windows systems, .o on POSIX systems)
+are automatically added to the target if not already present.
+Examples:
.ES
-env.Jar(target = 'foo.jar', source = 'classes')
+env.StaticObject(target = 'aaa', source = 'aaa.c')
+env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
+env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Java()
-.IP env.Java()
-Builds one or more Java class files
-from a source tree of .java files.
-The class files will be placed underneath
-the specified target directory.
-SCons will parse each source .java file
-to find the classes
-(including inner classes)
-defined within that file,
-and from that figure out the
-target .class files that will be created.
-SCons will also search each Java file
-for the Java package name,
-which it assumes can be found on a line
-beginning with the string
-.B package
-in the first column;
-the resulting .class files
-will be placed in a directory reflecting
-the specified package name.
-For example,
-the file
-.I Foo.java
-defining a single public
-.I Foo
-class and
-containing a package name of
-.I sub.dir
-will generate a corresponding
-.IR sub/dir/Foo.class
-class file.
-
-Example:
+.IP SharedObject
+Builds an object file for
+inclusion in a shared library.
+Source files must have one of the same set of extensions
+specified above for the
+.B StaticObject
+builder. On some platforms building a shared object requires additional
+compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
+normal (static) object, but on some platforms there is no difference between a
+shared object and a normal (static) one. When there is a difference, SCons
+will only allow shared objects to be linked into a shared library, and will
+use a different suffix for shared objects. On platforms where there is no
+difference, SCons will allow both normal (static)
+and shared objects to be linked into a
+shared library, and will use the same suffix for shared and normal
+(static) objects.
+The target object file prefix
+(specified by the $SHOBJPREFIX construction variable;
+by default, the same as $OBJPREFIX)
+and suffix
+(specified by the $SHOBJSUFFIX construction variable)
+are automatically added to the target if not already present.
+Examples:
.ES
-env.Java(target = 'classes', source = 'src')
+env.SharedObject(target = 'ddd', source = 'ddd.c')
+env.SharedObject(target = 'eee.o', source = 'eee.cpp')
+env.SharedObject(target = 'fff.obj', source = 'fff.for')
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP JavaH()
-.IP env.JavaH()
-Builds C header and source files for
-implementing Java native methods.
-The target can be either a directory
-in which the header files will be written,
-or a header file name which
-will contain all of the definitions.
-The source can be either the names of .class files,
-or the objects returned from the
-.B Java
-builder method.
-
-If the construction variable
-.B JAVACLASSDIR
-is set, either in the environment
-or in the call to the
-.B JavaH
-builder method itself,
-then the value of the variable
-will be stripped from the
-beginning of any .class file names.
+.IP Object
+A synonym for the
+.B StaticObject
+builder.
-Examples:
+.IP PCH
+Builds a Microsoft Visual C++ precompiled header. Calling this builder
+returns a list of two targets: the PCH as the first element, and the object
+file as the second element. Normally the object file is ignored. This builder is only
+provided when Microsoft Visual C++ is being used as the compiler.
+The PCH builder is generally used in
+conjuction with the PCH construction variable to force object files to use
+the precompiled header:
.ES
-# builds java_native.h
-classes = env.Java(target = 'classdir', source = 'src')
-env.JavaH(target = 'java_native.h', source = classes)
-
-# builds include/package_foo.h and include/package_bar.h
-env.JavaH(target = 'include',
- source = ['package/foo.class', 'package/bar.class'])
-
-# builds export/foo.h and export/bar.h
-env.JavaH(target = 'export',
- source = ['classes/foo.class', 'classes/bar.class'],
- JAVACLASSDIR = 'classes')
+env['PCH'] = env.PCH('StdAfx.cpp')[0]
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Library()
-.IP env.Library()
-A synonym for the
-.B StaticLibrary
-builder method.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP M4()
-.IP env.M4()
-Builds an output file from an M4 input file.
-This uses a default $M4FLAGS value of
-.BR -E ,
-which considers all warnings to be fatal
-and stops on the first warning
-when using the GNU version of m4.
+.IP Program
+Builds an executable given one or more object files or C, C++
+or Fortran source files.
+If any C, C++ or Fortran source files are specified,
+then they will be automatically
+compiled to object files using the
+.B Object
+builder;
+see that builder's description for
+a list of legal source file suffixes
+and how they are interpreted.
+The target executable file prefix
+(specified by the $PROGPREFIX construction variable; nothing by default)
+and suffix
+(specified by the $PROGSUFFIX construction variable;
+by default, .exe on Windows systems, nothing on POSIX systems)
+are automatically added to the target if not already present.
Example:
.ES
-env.M4(target = 'foo.c', source = 'foo.c.m4')
+env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP MSVSProject()
-.IP env.MSVSProject()
+.IP MSVSProject
Builds Microsoft Visual Studio project files.
This builds a Visual Studio project file, based on the version of
Visual Studio that is configured (either the latest installed version,
variant = 'Release')
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Object()
-.IP env.Object()
-A synonym for the
-.B StaticObject
-builder method.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP PCH()
-.IP env.PCH()
-Builds a Microsoft Visual C++ precompiled header.
-Calling this builder method
-returns a list of two targets: the PCH as the first element, and the object
-file as the second element. Normally the object file is ignored.
-This builder method is only
-provided when Microsoft Visual C++ is being used as the compiler.
-The PCH builder method is generally used in
-conjuction with the PCH construction variable to force object files to use
-the precompiled header:
+.IP RES
+Builds a Microsoft Visual C++ resource file.
+This builder is only provided
+when Microsoft Visual C++ or MinGW is being used as the compiler. The
+.I .res
+(or
+.I .o
+for MinGW) suffix is added to the target name if no other suffix is given. The source
+file is scanned for implicit dependencies as though it were a C file. Example:
.ES
-env['PCH'] = env.PCH('StdAfx.cpp')[0]
+env.RES('resource.rc')
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP PDF()
-.IP env.PDF()
-Builds a .pdf file from a .dvi input file
-(or, by extension, a .tex, .ltx, or .latex input file).
-The suffix specified by the $PDFSUFFIX construction variable
-(.pdf by default)
-is added automatically to the target
-if it is not already present. Example:
+.IP StaticLibrary
+Builds a static library given one or more object files
+or C, C++ or Fortran source files.
+If any source files are given,
+then they will be automatically
+compiled to object files.
+The static library prefix and suffix (if any)
+are automatically added to the target.
+The target library file prefix
+(specified by the $LIBPREFIX construction variable;
+by default, lib on POSIX systems, nothing on Windows systems)
+and suffix
+(specified by the $LIBSUFFIX construction variable;
+by default, .lib on Windows systems, .a on POSIX systems)
+are automatically added to the target if not already present.
+Example:
.ES
-# builds from aaa.tex
-env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
-# builds bbb.pdf from bbb.dvi
-env.PDF(target = 'bbb', source = 'bbb.dvi')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP PostScript()
-.IP env.PostScript()
-Builds a .ps file from a .dvi input file
-(or, by extension, a .tex, .ltx, or .latex input file).
-The suffix specified by the $PSSUFFIX construction variable
-(.ps by default)
-is added automatically to the target
-if it is not already present. Example:
-
-.ES
-# builds from aaa.tex
-env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
-# builds bbb.ps from bbb.dvi
-env.PostScript(target = 'bbb', source = 'bbb.dvi')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Program()
-.IP env.Program()
-Builds an executable given one or more object files or C, C++
-or Fortran source files.
-If any C, C++ or Fortran source files are specified,
-then they will be automatically
-compiled to object files using the
-.B Object
-builder method;
-see that builder method's description for
-a list of legal source file suffixes
-and how they are interpreted.
-The target executable file prefix
-(specified by the $PROGPREFIX construction variable; nothing by default)
-and suffix
-(specified by the $PROGSUFFIX construction variable;
-by default, .exe on Windows systems, nothing on POSIX systems)
-are automatically added to the target if not already present.
-Example:
-
-.ES
-env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP RES()
-.IP env.RES()
-Builds a Microsoft Visual C++ resource file.
-This builder method is only provided
-when Microsoft Visual C++ or MinGW is being used as the compiler. The
-.I .res
-(or
-.I .o
-for MinGW) suffix is added to the target name if no other suffix is given. The source
-file is scanned for implicit dependencies as though it were a C file. Example:
-
-.ES
-env.RES('resource.rc')
+env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP RMIC()
-.IP env.RMIC()
-Builds stub and skeleton class files
-for remote objects
-from Java .class files.
-The target is a directory
-relative to which the stub
-and skeleton class files will be written.
-The source can be the names of .class files,
-or the objects return from the
-.B Java
-builder method.
-
-If the construction variable
-.B JAVACLASSDIR
-is set, either in the environment
-or in the call to the
-.B RMIC
-builder method itself,
-then the value of the variable
-will be stripped from the
-beginning of any .class file names.
-
-.ES
-classes = env.Java(target = 'classdir', source = 'src')
-env.RMIC(target = 'outdir1', source = classes)
-
-env.RMIC(target = 'outdir2',
- source = ['package/foo.class', 'package/bar.class'])
-
-env.RMIC(target = 'outdir3',
- source = ['classes/foo.class', 'classes/bar.class'],
- JAVACLASSDIR = 'classes')
-.EE
+.IP
+Any object files listed in the
+.B source
+must have been built for a static library
+(that is, using the
+.B StaticObject
+builder).
+.B scons
+will raise an error if there is any mismatch.
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP SharedLibrary()
-.IP env.SharedLibrary()
+.IP SharedLibrary
Builds a shared library
(.so on a POSIX system, .dll on WIN32)
given one or more object files
.IP
On WIN32 systems, the
.B SharedLibrary
-builder method will always build an import (.lib) library
+builder will always build an import (.lib) library
in addition to the shared (.dll) library,
adding a .lib library with the same basename
if there is not already a .lib file explicitly
must have been built for a shared library
(that is, using the
.B SharedObject
-builder method).
+builder).
.B scons
will raise an error if there is any mismatch.
.IP
.IP
will register "bar.dll" as a COM object when it is done linking it.
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP SharedObject()
-.IP env.SharedObject()
-Builds an object file for
-inclusion in a shared library.
-Source files must have one of the same set of extensions
-specified above for the
-.B StaticObject
-builder method.
-On some platforms building a shared object requires additional
-compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
-normal (static) object, but on some platforms there is no difference between a
-shared object and a normal (static) one. When there is a difference, SCons
-will only allow shared objects to be linked into a shared library, and will
-use a different suffix for shared objects. On platforms where there is no
-difference, SCons will allow both normal (static)
-and shared objects to be linked into a
-shared library, and will use the same suffix for shared and normal
-(static) objects.
-The target object file prefix
-(specified by the $SHOBJPREFIX construction variable;
-by default, the same as $OBJPREFIX)
-and suffix
-(specified by the $SHOBJSUFFIX construction variable)
-are automatically added to the target if not already present.
-Examples:
+.IP Library
+A synonym for the
+.B StaticLibrary
+builder.
+
+.IP CFile
+Builds a C source file given a lex (.l) or yacc (.y) input file.
+The suffix specified by the $CFILESUFFIX construction variable
+(.c by default)
+is automatically added to the target
+if it is not already present. Example:
.ES
-env.SharedObject(target = 'ddd', source = 'ddd.c')
-env.SharedObject(target = 'eee.o', source = 'eee.cpp')
-env.SharedObject(target = 'fff.obj', source = 'fff.for')
+# builds foo.c
+env.CFile(target = 'foo.c', source = 'foo.l')
+# builds bar.c
+env.CFile(target = 'bar', source = 'bar.y')
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP StaticLibrary()
-.IP env.StaticLibrary()
-Builds a static library given one or more object files
-or C, C++ or Fortran source files.
-If any source files are given,
-then they will be automatically
-compiled to object files.
-The static library prefix and suffix (if any)
-are automatically added to the target.
-The target library file prefix
-(specified by the $LIBPREFIX construction variable;
-by default, lib on POSIX systems, nothing on Windows systems)
-and suffix
-(specified by the $LIBSUFFIX construction variable;
-by default, .lib on Windows systems, .a on POSIX systems)
-are automatically added to the target if not already present.
-Example:
+.IP CXXFile
+Builds a C++ source file given a lex (.ll), yacc (.yy)
+or uic (.ui) input file.
+The suffix specified by the $CXXFILESUFFIX construction variable
+(.cc by default)
+is automatically added to the target
+if it is not already present. Example:
.ES
-env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
+# builds foo.cc
+env.CXXFile(target = 'foo.cc', source = 'foo.ll')
+# builds bar.cc
+env.CXXFile(target = 'bar', source = 'bar.yy')
.EE
-.IP
-Any object files listed in the
-.B source
-must have been built for a static library
-(that is, using the
-.B StaticObject
-builder method).
-.B scons
-will raise an error if there is any mismatch.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP StaticObject()
-.IP env.StaticObject()
-Builds a static object file
-from one or more C, C++, or Fortran source files.
-Source files must have one of the following extensions:
+.IP M4
+Builds an output file from an M4 input file.
+This uses a default $M4FLAGS value of
+.BR -E ,
+which considers all warnings to be fatal
+and stops on the first warning
+when using the GNU version of m4.
+Example:
.ES
- .asm assembly language file
- .ASM assembly language file
- .c C file
- .C WIN32: C file
- POSIX: C++ file
- .cc C++ file
- .cpp C++ file
- .cxx C++ file
- .cxx C++ file
- .c++ C++ file
- .C++ C++ file
- .f Fortran file
- .F WIN32: Fortran file
- POSIX: Fortran file + C pre-processor
- .for Fortran file
- .FOR Fortran file
- .fpp Fortran file + C pre-processor
- .FPP Fortran file + C pre-processor
- .s assembly language file
- .S WIN32: assembly language file
- POSIX: assembly language file + C pre-processor
- .spp assembly language file + C pre-processor
- .SPP assembly language file + C pre-processor
+env.M4(target = 'foo.c', source = 'foo.c.m4')
.EE
-.IP
-The target object file prefix
-(specified by the $OBJPREFIX construction variable; nothing by default)
-and suffix
-(specified by the $OBJSUFFIX construction variable;
-\.obj on Windows systems, .o on POSIX systems)
-are automatically added to the target if not already present.
-Examples:
+.IP Jar
+Builds a Java archive (.jar) file
+from a source tree of .class files.
.ES
-env.StaticObject(target = 'aaa', source = 'aaa.c')
-env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
-env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
+env.Jar(target = 'foo.jar', source = 'classes')
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Tar()
-.IP env.Tar()
-Builds a tar archive of the specified files
-and/or directories.
-Unlike most builder methods,
-the
-.B Tar
-builder method may be called multiple times
-for a given target;
-each additional call
-adds to the list of entries
-that will be built into the archive.
+.IP Java
+Builds one or more Java class files
+from a source tree of .java files.
+The class files will be placed underneath
+the specified target directory.
+SCons will parse each source .java file
+to find the classes
+(including inner classes)
+defined within that file,
+and from that figure out the
+target .class files that will be created.
+SCons will also search each Java file
+for the Java package name,
+which it assumes can be found on a line
+beginning with the string
+.B package
+in the first column;
+the resulting .class files
+will be placed in a directory reflecting
+the specified package name.
+For example,
+the file
+.I Foo.java
+defining a single public
+.I Foo
+class and
+containing a package name of
+.I sub.dir
+will generate a corresponding
+.IR sub/dir/Foo.class
+class file.
-.ES
-env.Tar('src.tar', 'src')
+Example:
-# Create the stuff.tar file.
-env.Tar('stuff', ['subdir1', 'subdir2'])
-# Also add "another" to the stuff.tar file.
-env.Tar('stuff', 'another')
+.ES
+env.Java(target = 'classes', source = 'src')
+.EE
-# Set TARFLAGS to create a gzip-filtered archive.
-env = Environment(TARFLAGS = '-c -z')
-env.Tar('foo.tar.gz', 'foo')
+.IP JavaH
+Builds C header and source files for
+implementing Java native methods.
+The target can be either a directory
+in which the header files will be written,
+or a header file name which
+will contain all of the definitions.
+The source can be either the names of .class files,
+or the objects returned from the
+.B Java
+builder.
-# Also set the suffix to .tgz.
-env = Environment(TARFLAGS = '-c -z',
- TARSUFFIX = '.tgz')
-env.Tar('foo')
+If the construction variable
+.B JAVACLASSDIR
+is set, either in the environment
+or in the call to the
+.B JavaH
+builder itself,
+then the value of the variable
+will be stripped from the
+beginning of any .class file names.
+
+Examples:
+
+.ES
+# builds java_native.h
+classes = env.Java(target = 'classdir', source = 'src')
+env.JavaH(target = 'java_native.h', source = classes)
+
+# builds include/package_foo.h and include/package_bar.h
+env.JavaH(target = 'include',
+ source = ['package/foo.class', 'package/bar.class'])
+
+# builds export/foo.h and export/bar.h
+env.JavaH(target = 'export',
+ source = ['classes/foo.class', 'classes/bar.class'],
+ JAVACLASSDIR = 'classes')
+.EE
+
+.IP RMIC
+Builds stub and skeleton class files
+for remote objects
+from Java .class files.
+The target is a directory
+relative to which the stub
+and skeleton class files will be written.
+The source can be the names of .class files,
+or the objects return from the
+.B Java
+builder.
+
+If the construction variable
+.B JAVACLASSDIR
+is set, either in the environment
+or in the call to the
+.B RMIC
+builder itself,
+then the value of the variable
+will be stripped from the
+beginning of any .class file names.
+
+.ES
+classes = env.Java(target = 'classdir', source = 'src')
+env.RMIC(target = 'outdir1', source = classes)
+
+env.RMIC(target = 'outdir2',
+ source = ['package/foo.class', 'package/bar.class'])
+
+env.RMIC(target = 'outdir3',
+ source = ['classes/foo.class', 'classes/bar.class'],
+ JAVACLASSDIR = 'classes')
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP TypeLibrary()
-.IP env.TypeLibrary()
+.IP TypeLibrary
Builds a Windows type library (.tlb) file from and input IDL file
(.idl). In addition, it will build the associated inteface stub and
proxy source files. It names them according to the base name of the .idl file.
.IP
Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.IP Zip()
-.IP env.Zip()
+.IP DVI
+Builds a .dvi file from a .tex, .ltx or .latex input file.
+The suffix .dvi
+(hard-coded within TeX itself)
+is automatically added to the target
+if it is not already present. Example:
+
+.ES
+# builds from aaa.tex
+env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
+# builds bbb.dvi
+env.DVI(target = 'bbb', source = 'bbb.ltx')
+# builds from ccc.latex
+env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
+.EE
+
+.IP PDF
+Builds a .pdf file from a .dvi input file
+(or, by extension, a .tex, .ltx, or .latex input file).
+The suffix specified by the $PDFSUFFIX construction variable
+(.pdf by default)
+is added automatically to the target
+if it is not already present. Example:
+
+.ES
+# builds from aaa.tex
+env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
+# builds bbb.pdf from bbb.dvi
+env.PDF(target = 'bbb', source = 'bbb.dvi')
+.EE
+
+.IP PostScript
+Builds a .ps file from a .dvi input file
+(or, by extension, a .tex, .ltx, or .latex input file).
+The suffix specified by the $PSSUFFIX construction variable
+(.ps by default)
+is added automatically to the target
+if it is not already present. Example:
+
+.ES
+# builds from aaa.tex
+env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
+# builds bbb.ps from bbb.dvi
+env.PostScript(target = 'bbb', source = 'bbb.dvi')
+.EE
+
+.IP Tar
+Builds a tar archive of the specified files
+and/or directories.
+Unlike most builders,
+the
+.B Tar
+builder may be called multiple times
+for a given target;
+each additional call
+adds to the list of entries
+that will be built into the archive.
+
+.ES
+env.Tar('src.tar', 'src')
+
+# Create the stuff.tar file.
+env.Tar('stuff', ['subdir1', 'subdir2'])
+# Also add "another" to the stuff.tar file.
+env.Tar('stuff', 'another')
+
+# Set TARFLAGS to create a gzip-filtered archive.
+env = Environment(TARFLAGS = '-c -z')
+env.Tar('foo.tar.gz', 'foo')
+
+# Also set the suffix to .tgz.
+env = Environment(TARFLAGS = '-c -z',
+ TARSUFFIX = '.tgz')
+env.Tar('foo')
+.EE
+
+.IP Zip
Builds a zip archive of the specified files
and/or directories.
-Unlike most builder methods,
+Unlike most builders,
the
.B Zip
-builder method may be called multiple times
+builder may be called multiple times
for a given target;
each additional call
adds to the list of entries
files extensions
for C preprocessor dependencies,
so the dependencies do not need to be specified explicitly.
-In addition, all
-targets of builder methods automatically depend on their sources.
+In addition, all builder
+targets automatically depend on their sources.
An explicit dependency can
be specified using the
.B Depends
method of a construction environment (see below).
-.SS Methods and Functions to Do Things
-In addition to Builder methods,
-.B scons
-provides a number of other construction environment methods
-and global functions to
-manipulate the build configuration.
-
-Usually, a construction environment method
-and global function with the same name both exist
-so that you don't have to remember whether
-to a specific bit of functionality
-must be called with or without a construction environment.
-In the following list,
-if you call something as a global function
-it looks like:
-.ES
-.RI Function( arguments )
-.EE
-and if you call something through a construction
-environment it looks like:
-.ES
-.RI env.Function( arguments )
-.EE
-If you can call the functionality in both ways,
-then both forms are listed.
-
-Except where otherwise noted,
-the same-named
-construction environment method
-and global function
-provide the exact same functionality.
-The only difference is that,
-where appropriate,
-calling the functionality through a construction environment will
-substitute construction variables into
-any supplied strings.
-For example:
-.ES
-env = Environment(FOO = 'foo')
-Default('$FOO')
-env.Default('$FOO')
-.EE
-the first call to the global
-.B Default()
-function will actually add a target named
-.B $FOO
-to the list of default targets,
-while the second call to the
-.B env.Default()
-construction environment method
-will expand the value
-and add a target named
-.B foo
-to the list of default targets.
-For more on construction variable expansion,
-see the next section on
-construction variables.
-
-Construction environment methods
-and global functions supported by
-.B scons
-include:
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Action( action ", [" strfunction ", " varlist ])
-.TP
-.RI env.Action( action ", [" strfunction ", " varlist ])
-Creates an Action object for
-the specified
-.IR action .
-See the section "Action Objects,"
-below, for a complete explanation of the arguments and behavior.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI AddPostAction( target ", " action )
-.TP
-.RI env.AddPostAction( target ", " action )
-Arranges for the specified
-.I action
-to be performed
-after the specified
-.I target
-has been built.
-The specified action(s) may be
-an Action object, or anything that
-can be converted into an Action object
-(see below).
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI AddPreAction( target ", " action )
-.TP
-.RI env.AddPreAction( target ", " action )
-Arranges for the specified
-.I action
-to be performed
-before the specified
-.I target
-is built.
-The specified action(s) may be
-an Action object, or anything that
-can be converted into an Action object
-(see below).
+.SS Other Construction Environment Methods
+Additional construction environment methods include:
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Alias( alias ", [" targets ])
.TP
-.RI env.Alias( alias ", [" targets ])
-Creates one or more phony targets that
-expand to one or more other targets.
+.RI Alias( alias ", " targets )
+Creates a phony target that
+expands to one or more other targets.
Returns the Node object representing the alias,
which exists outside of any file system.
This Node object, or the alias name,
may be used as a dependency of any other target,
-including another alias.
-.B Alias
-can be called multiple times for the same
-alias to add additional targets to the alias.
+including another alias. Alias can be called multiple times for the same
+alias to add additional targets to the alias. There is also an Alias
+global function for creating or referencing an alias independently of
+any construction environment.
.ES
-Alias('install')
-Alias('install', '/usr/bin')
-Alias(['install', 'install-lib'], '/usr/local/lib')
-
env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
env.Alias('install', ['/usr/local/man'])
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI AlwaysBuild( target ", ...)"
-.TP
-.RI env.AlwaysBuild( target ", ...)"
-Marks each given
-.I target
-so that it is always assumed to be out of date,
-and will always be rebuilt if needed.
-Note, however, that
-.BR AlwaysBuild ()
-does not add its target(s) to the default target list,
-so the targets will only be built
-if they are specified on the command line,
-or are a dependent of a target specified on the command line--but
-they will
-.I always
-be built if so specified.
-Multiple targets can be passed in to a single call to
-.BR AlwaysBuild ().
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.Append( key = val ", [...])"
+.RI Append( key = val ", [...])"
Appends the specified keyword arguments
to the end of construction variables in the environment.
If the Environment does not have
env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
+.RI PrependENVPath( name ", " newpath ", [" envname ", " sep ])
+This appends new path elements to the given path in the
+specified external environment
+.RB ( ENV
+by default).
+This will only add
+any particular path once (leaving the first one it encounters and
+ignoring the rest, to preserve path order),
+and to help assure this,
+will normalize all paths (using
+.B os.path.normpath
+and
+.BR os.path.normcase ).
+This can also handle the
+case where the given old path variable is a list instead of a
+string, in which case a list will be returned instead of a string.
+Example:
+
+.ES
+print 'before:',env['ENV']['INCLUDE']
+include_path = '/foo/bar:/foo'
+env.PrependENVPath('INCLUDE', include_path)
+print 'after:',env['ENV']['INCLUDE']
+
+yields:
+before: /biz:/foo
+after: /foo/bar:/foo:/biz
+.EE
+
+.TP
+.RI AppendENVPath( name ", " newpath ", [" envname ", " sep ])
This appends new path elements to the given path in the
specified external environment
.RB ( ENV
after: /biz:/foo/bar:/foo
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-env.BitKeeper()
+BitKeeper()
A factory function that
returns a Builder object
to be used to fetch source files
is intended to be passed to the
.B SourceCode
function.
-
.ES
env.SourceCode('.', env.BitKeeper())
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
.TP
-.RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
-This specifies a build directory
-.I build_dir
-in which to build all derived files
-that would normally be built under
-.IR src_dir .
-Multiple build directories can be set up for multiple build variants, for
-example.
-.I src_dir
-must be underneath the SConstruct file's directory,
-and
-.I build_dir
-may not be underneath the
-.I src_dir .
-
-The default behavior is for
-.B scons
-to duplicate all of the files in the tree underneath
-.I src_dir
-into
-.IR build_dir ,
-and then build the derived files within the copied tree.
-(The duplication is performed by
-linking or copying,
-depending on the platform.)
-This guarantees correct builds
-regardless of whether intermediate source files
-are generated during the build,
-where preprocessors or other scanners search
-for included files,
-or whether individual compilers or other invoked tools
-are hard-coded to put derived files in the same directory as source files.
-
-This behavior of making a complete copy of the source tree
-may be disabled by setting
-.I duplicate
-to 0.
-This will cause
-.B scons
-to invoke Builders using the
-path names of source files in
-.I src_dir
-and the path names of derived files within
-.IR build_dir .
-This is always more efficient than
-.IR duplicate =1,
-and is usually safe for most builds.
-Specifying
-.IR duplicate =0,
-however,
-may cause build problems
-if source files are generated during the build,
-if any invoked tools are hard-coded to
-put derived files in the same directory as the source files.
-
-Note that specifying a
-.B BuildDir
-works most naturally
-with a subsidiary SConscript file
-in the source directory.
-However,
-you would then call the subsidiary SConscript file
-not in the source directory,
-but in the
-.I build_dir ,
-as if
-.B scons
-had made a virtual copy of the source tree
-regardless of the value of
-.IR duplicate .
-This is how you tell
-.B scons
-which variant of a source tree to build.
-For example:
-
-.ES
-BuildDir('build-variant1', 'src')
-SConscript('build-variant1/SConscript')
-BuildDir('build-variant2', 'src')
-SConscript('build-variant2/SConscript')
-.EE
-
-.IP
-See also the
-.BR SConscript ()
-function, described below,
-for another way to
-specify a build directory
-in conjunction with calling a subsidiary
-SConscript file.)
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Builder( action ", [" multi ", " prefix ", " suffix ", " src_suffix ", " src_builder ", " emitter ])
-.TP
-.RI env.Builder( action ", [" multi ", " prefix ", " suffix ", " src_suffix ", " src_builder ", " emitter ])
-Creates a Builder object for
-the specified
-.IR action .
-See the section "Builder Objects,"
-below, for a complete explanation of the arguments and behavior.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI CacheDir( cache_dir )
-.TP
-.RI env.CacheDir( cache_dir )
-Specifies that
-.B scons
-will maintain a cache of derived files in
-.I cache_dir .
-The derived files in the cache will be shared
-among all the builds using the same
-.BR CacheDir ()
-call.
-
-When a
-.BR CacheDir ()
-is being used and
-.B scons
-finds a derived file that needs to be rebuilt,
-it will first look in the cache to see if a
-derived file has already been built
-from identical input files and an identical build action
-(as incorporated into the MD5 build signature).
-If so,
-.B scons
-will retrieve the file from the cache.
-If the derived file is not present in the cache,
-.B scons
-will rebuild it and
-then place a copy of the built file in the cache
-(identified by its MD5 build signature),
-so that it may be retrieved by other
-builds that need to build the same derived file
-from identical inputs.
-
-Use of a specified
-.BR CacheDir()
-may be disabled for any invocation
-by using the
-.B --cache-disable
-option.
-
-If the
-.B --cache-force
-option is used,
-.B scons
-will place a copy of
-.I all
-derived files in the cache,
-even if they already existed
-and were not built by this invocation.
-This is useful to populate a cache
-the first time
-.BR CacheDir ()
-is added to a build,
-or after using the
-.B --cache-disable
-option.
-
-When using
-.BR CacheDir (),
-.B scons
-will report,
-"Retrieved `file' from cache,"
-unless the
-.B --cache-show
-option is being used.
-When the
-.B --cache-show
-option is used,
-.B scons
-will print the action that
-.I would
-have been used to build the file,
-without any indication that
-the file was actually retrieved from the cache.
-This is useful to generate build logs
-that are equivalent regardless of whether
-a given derived file has been built in-place
-or retrieved from the cache.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Clean( target ", " files_or_dirs )
-.TP
-.RI env.Clean( target ", " files_or_dirs )
-This specifies a list of files or directories which should be removed
-whenever the target is specified with the
-.B -c
-command line option.
-Multiple calls to
-.BR Clean ()
-are legal,
-and create a new target or add files and directories to the
-clean list for the specified target.
-
-Multiple files or directories should be specified
-either as separate arguments to the
-.BR Clean ()
-method, or as a list.
-.BR Clean ()
-will also accept the return value of any of the construction environment
-Builder methods.
-Examples:
-
-.ES
-Clean('foo', ['bar', 'baz'])
-Clean('dist', env.Program('hello', 'hello.c'))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Command( target ", " source ", " commands )
-.TP
-.RI env.Command( target ", " source ", " commands )
-Executes a specific action
-(or list of actions)
-to build a target file or files.
-This is more convenient
-than defining a separate Builder object
-for a single special-case build.
+.RI Command( target ", " source ", " commands )
+Executes a specific action
+(or list of actions)
+to build a target file or files.
+This is more convenient
+than defining a separate Builder object
+for a single special-case build.
Note that an action can be an external command,
specified as a string,
rename ])
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ])
-.TP
-.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ])
-Creates a Configure object for integrated
-functionality similar to GNU autoconf.
-See the section "Configure Contexts,"
-below, for a complete explanation of the arguments and behavior.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.Copy([ key = val ", ...])"
+.RI Copy([ key = val ", ...])"
Return a separate copy of a construction environment.
If there are any keyword arguments specified,
they are added to the returned copy,
env2 = env.Copy()
env3 = env.Copy(CCFLAGS = '-g')
.EE
-.IP
+
Additionally, a list of tools may be specified, as in the Environment
constructor:
env4 = env.Copy(tools = ['msvc', MyTool])
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
.TP
-.RI env.CVS( repository ", " module )
+.RI CVS( repository ", " module )
A factory function that
returns a Builder object
to be used to fetch source files
env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Default( targets )
-.TP
-.RI env.Default( targets )
-This specifies a list of default targets,
-which will be built by
-.B scons
-if no explicit targets are given on the command line.
-Multiple calls to
-.BR Default ()
-are legal,
-and add to the list of default targets.
-
-Multiple targets should be specified as
-separate arguments to the
-.BR Default ()
-method, or as a list.
-.BR Default ()
-will also accept the Node returned by any
-of a construction environment's
-builder methods.
-Examples:
-
-.ES
-Default('foo', 'bar', 'baz')
-env.Default(['a', 'b', 'c'])
-hello = env.Program('hello', 'hello.c')
-env.Default(hello)
-.EE
-.IP
-An argument to
-.BR Default ()
-of
-.B None
-will clear all default targets.
-Later calls to
-.BR Default ()
-will add to the (now empty) default-target list
-like normal.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI DefaultEnvironment([ args ])
-Creates and returns a default construction environment object.
-This construction environment is used internally by SCons
-in order to execute many of the global functions in this list,
-and to fetch source files transparently
-from source code management systems.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI Depends( target ", " dependency )
-.TP
-.RI env.Depends( target ", " dependency )
Specifies an explicit dependency;
the target file(s) will be rebuilt
whenever the dependency file(s) has changed.
env.Depends('foo', 'other-input-file-for-foo')
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.Dictionary([ vars ])
+.RI Dictionary([ vars ])
Returns a dictionary object
containing copies of all of the
construction variables in the environment.
cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Dir( name ", [" directory ])
.TP
-.RI env.Dir( name ", [" directory ])
-This returns an object that represents a given directory
-.IR name .
-.I name
-can be a relative or absolute path.
-.I directory
-is an optional directory that will be used as the parent directory.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI EnsurePythonVersion( major ", " minor )
-.TP
-.RI env.EnsurePythonVersion( major ", " minor )
-Ensure that the Python version is at least
-.IR major . minor .
-This function will
-print out an error message and exit SCons with a non-zero exit code if the
-actual Python version is not late enough.
-
-.ES
-EnsurePythonVersion(2,2)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI EnsureSConsVersion( major ", " minor )
-.TP
-.RI env.EnsureSConsVersion( major ", " minor )
-Ensure that the SCons version is at least
-.IR major . minor .
-This function will
-print out an error message and exit SCons with a non-zero exit code if the
-actual SCons version is not late enough.
-
-.ES
-EnsureSConsVersion(0,9)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Environment([ key = value ", ...])"
-.TP
-.RI env.Environment([ key = value ", ...])"
-Return a new construction environment
-initialized with the specified
-.IR key = value
-pairs.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Exit([ value ])
-.TP
-.RI env.Exit([ value ])
-This tells
-.B scons
-to exit immediately
-with the specified
-.IR value .
-A default exit value of
-.B 0
-(zero)
-is used if no value is specified.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Export( vars )
-.TP
-.RI env.Export( vars )
-This tells
-.B scons
-to export a list of variables from the current
-SConscript file to all other SConscript files.
-The exported variables are kept in a global collection,
-so subsequent calls to
-.BR Export ()
-will over-write previous exports that have the same name.
-Multiple variable names can be passed to
-.BR Export ()
-as separate arguments or as a list. A dictionary can be used to map
-variables to a different name when exported. Both local variables and
-global variables can be exported.
-Examples:
-
-.ES
-env = Environment()
-# Make env available for all SConscript files to Import().
-Export("env")
-
-package = 'my_name'
-# Make env and package available for all SConscript files:.
-Export("env", "package")
-
-# Make env and package available for all SConscript files:
-Export(["env", "package"])
-
-# Make env available using the name debug:.
-Export({"debug":env})
-.EE
-
-.IP
-Note that the
-.BR SConscript ()
-function supports an
-.I exports
-argument that makes it easier to to export a variable or
-set of variables to a single SConscript file.
-See the description of the
-.BR SConscript ()
-function, below.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI File( name ", [" directory ])
-.TP
-.RI env.File( name ", [" directory ])
-This returns an object that represents a given file
-.IR name .
-.I name
-can be a relative or absolute path.
-.I directory
-is an optional directory that will be used as the parent directory.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI FindFile( file ", " dirs )
-.TP
-.RI env.FindFile( file ", " dirs )
-Search for
-.I file
-in the path specified by
-.IR dirs .
-.I file
-may be a list of file names or a single file name. In addition to searching
-for files that exist in the filesytem, this function also searches for
-derived files that have not yet been built.
-
-.ES
-foo = env.FindFile('foo', ['dir1', 'dir2'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI GetBuildPath( file ", [" ... ])
-.TP
-.RI env.GetBuildPath( file ", [" ... ])
-Returns the
-.B scons
-path name (or names) for the specified
-.I file
-(or files).
-The specified
-.I file
-or files
-may be
-.B scons
-Nodes or strings representing path names.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI GetLaunchDir()
-.TP
-.RI env.GetLaunchDir()
-Returns the absolute path name of the directory from which
-.B
-scons
-was initially invoked.
-This can be useful when using the
-.BR \-u ,
-.BR \-U
-or
-.BR \-D
-options, which internally
-change to the directory in which the
-.B SConstruct
-file is found.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI GetOption( name )
-.TP
-.RI env.GetOption( name )
-This function provides a way to query a select subset of the scons command line
-options from a SConscript file. See
-.IR SetOption ()
-for a description of the options available.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-'\".TP
-'\".RI GlobalBuilders( flag )
-'\"When
-'\".B flag
-'\"is non-zero,
-'\"adds the names of the default builders
-'\"(Program, Library, etc.)
-'\"to the global name space
-'\"so they can be called without an explicit construction environment.
-'\"(This is the default.)
-'\"When
-'\".B
-'\"flag is zero,
-'\"the names of the default builders are removed
-'\"from the global name space
-'\"so that an explicit construction environment is required
-'\"to call all builders.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Help( text )
-.TP
-.RI env.Help( text )
-This specifies help text to be printed if the
-.B -h
-argument is given to
-.BR scons .
-.B scons
-will exit after printing out the help text.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Ignore( target ", " dependency )
-.TP
-.RI env.Ignore( target ", " dependency )
-The specified dependency file(s)
-will be ignored when deciding if
-the target file(s) need to be rebuilt.
+.RI Ignore( target ", " dependency )
+The specified dependency file(s)
+will be ignored when deciding if
+the target file(s) need to be rebuilt.
.ES
env.Ignore('foo', 'foo.c')
env.Ignore('bar', ['bar1.h', 'bar2.h'])
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Import( vars )
-.TP
-.RI env.Import( vars )
-This tells
-.B scons
-to import a list of variables into the current SConscript file. This
-will import variables that were exported with
-.BR Export ()
-or in the
-.I exports
-argument to
-.BR SConscript ().
-Variables exported by
-.BR SConscript ()
-have precedence.
-Multiple variable names can be passed to
-.BR Import ()
-as separate arguments or as a list. The variable "*" can be used
-to import all variables.
-Examples:
-
-.ES
-Import("env")
-Import("env", "variable")
-Import(["env", "variable"])
-Import("*")
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI Install( dir ", " source )
-.TP
-.RI env.Install( dir ", " source )
Installs one or more files in a destination directory.
The file names remain the same.
env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI InstallAs( target ", " source )
-.TP
-.RI env.InstallAs( target ", " source )
Installs one or more files as specific file names,
allowing changing a file name as part of the
installation.
source = ['libFOO.a', 'libBAR.a'])
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Literal( string )
-.TP
-.RI env.Literal( string )
-The specified
-.I string
-will be preserved as-is
-and not have construction variables expanded.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Local( targets )
-.TP
-.RI env.Local( targets )
-The specified
-.I targets
-will have copies made in the local tree,
-even if an already up-to-date copy
-exists in a repository.
-Returns a list of the target Node or Nodes.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.ParseConfig( command ", [" function ])
-Calls the specified
-.I function
-to modify the environment as specified by the output of
-.I command .
-The default
-.I function
-expects the output of a typical
-.I *-config command
-(for example,
-.BR gtk-config )
-and parses the returned
-.BR -L ,
-.BR -l ,
-.B -I
-and other options
-into the
-.BR LIBPATH ,
-.BR LIBS ,
-.B CPPPATH
-and
-.B CCFLAGS
-variables,
-respectively.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-env.Perforce()
+Perforce()
A factory function that
returns a Builder object
to be used to fetch source files
is intended to be passed to the
.B SourceCode
function:
-
.ES
env.SourceCode('.', env.Perforce())
.EE
and
USERNAME.
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI Platform( string )
-Returns a callable object
-that can be used to initialize
-a construction environment using the
-platform keyword of the Environment() method:
+.RI AlwaysBuild( target ", ...)"
+Marks each given
+.I target
+so that it is always assumed to be out of date,
+and will always be rebuilt if needed.
+Note, however, that
+.BR AlwaysBuild ()
+does not add its target(s) to the default target list,
+so the targets will only be built
+if they are specified on the command line,
+or are a dependent of a target specified on the command line--but
+they will
+.I always
+be built if so specified.
+Multiple targets can be passed in to a single call to
+.BR AlwaysBuild ().
-.ES
-env = Environment(platform = Platform('win32'))
-.EE
.TP
-.RI env.Platform( string )
-Applies the callable object for the specified platform
-.I string
-to the environment through which the method was called.
+.RI Precious( target ", ...)"
+Marks each given
+.I target
+as precious so it is not deleted before it is rebuilt. Normally
+.B scons
+deletes a target before building it.
+Multiple targets can be passed in to a single call to
+.BR Precious ().
-.ES
-env.Platform('posix')
-.EE
-.IP
-Note that the
-.B win32
-platform adds the
-.B SYSTEMROOT
-variable from the user's external environment
-to the construction environment's
-.B ENV
-dictionary.
-This is so that any executed commands
-that use sockets to connect with other systems
-(such as fetching source files from
-external CVS repository specifications like
-.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
-will work on Win32 systems.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Precious( target ", ...)"
-.TP
-.RI env.Precious( target ", ...)"
-Marks each given
-.I target
-as precious so it is not deleted before it is rebuilt. Normally
-.B scons
-deletes a target before building it.
-Multiple targets can be passed in to a single call to
-.BR Precious ().
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.Prepend( key = val ", [...])"
+.RI Prepend( key = val ", [...])"
Appends the specified keyword arguments
to the beginning of construction variables in the environment.
If the Environment does not have
env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
-This appends new path elements to the given path in the
-specified external environment
-.RB ( ENV
-by default).
-This will only add
-any particular path once (leaving the first one it encounters and
-ignoring the rest, to preserve path order),
-and to help assure this,
-will normalize all paths (using
-.B os.path.normpath
-and
-.BR os.path.normcase ).
-This can also handle the
-case where the given old path variable is a list instead of a
-string, in which case a list will be returned instead of a string.
-Example:
-
-.ES
-print 'before:',env['ENV']['INCLUDE']
-include_path = '/foo/bar:/foo'
-env.PrependENVPath('INCLUDE', include_path)
-print 'after:',env['ENV']['INCLUDE']
-
-yields:
-before: /biz:/foo
-after: /foo/bar:/foo:/biz
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-env.RCS()
+RCS()
A factory function that
returns a Builder object
to be used to fetch source files
is intended to be passed to the
.B SourceCode
function:
-
.ES
env.SourceCode('.', env.RCS())
.EE
or if you need to explicitly specify RCS
for a specific subdirectory.
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI env.Replace( key = val ", [...])"
+.RI Replace( key = val ", [...])"
Replaces construction variables in the Environment
with the specified keyword arguments.
env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
.EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Repository( directory )
-.TP
-.RI env.Repository( directory )
-Specifies that
-.I directory
-is a repository to be searched for files.
-Multiple calls to
-.BR Repository ()
-are legal,
-and each one adds to the list of
-repositories that will be searched.
-
-To
-.BR scons ,
-a repository is a copy of the source tree,
-from the top-level directory on down,
-which may contain
-both source files and derived files
-that can be used to build targets in
-the local source tree.
-The canonical example would be an
-official source tree maintained by an integrator.
-If the repository contains derived files,
-then the derived files should have been built using
-.BR scons ,
-so that the repository contains the necessary
-signature information to allow
-.B scons
-to figure out when it is appropriate to
-use the repository copy of a derived file,
-instead of building one locally.
-
-Note that if an up-to-date derived file
-already exists in a repository,
-.B scons
-will
-.I not
-make a copy in the local directory tree.
-In order to guarantee that a local copy
-will be made,
-use the
-.B Local()
-method.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Return( vars )
-This tells
-.B scons
-what variable(s) to use as the return value(s) of the current SConscript
-file. These variables will be returned to the "calling" SConscript file
-as the return value(s) of
-.BR SConscript ().
-Multiple variable names should be passed to
-.BR Return ()
-as a list. Example:
-
-.ES
-Return("foo")
-Return(["foo", "bar"])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
-.TP
-.RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
-Creates a Scanner object for
-the specified
-.IR function .
-See the section "Scanner Objects,"
-below, for a complete explanation of the arguments and behavior.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-env.SCCS()
+SCCS()
A factory function that
returns a Builder object
to be used to fetch source files
is intended to be passed to the
.B SourceCode
function:
-
.ES
env.SourceCode('.', env.SCCS())
.EE
or if you need to explicitly specify SCCS
for a specific subdirectory.
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
.TP
-.RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
-.TP
-.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
-.TP
-.RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
-This tells
+.RI SideEffect( side_effect ", " target )
+Declares
+.I side_effect
+as a side effect of building
+.IR target .
+Both
+.I side_effect
+and
+.I target
+can be a list, a file name, or a node.
+A side effect is a target that is created
+as a side effect of building other targets.
+For example, a Windows PDB
+file is created as a side effect of building the .obj
+files for a static library.
+If a target is a side effect of multiple build commands,
.B scons
-to execute
-one or more subsidiary SConscript (configuration) files.
-There are two ways to call the
-.BR SConscript ()
-function.
+will ensure that only one set of commands
+is executed at a time.
+Consequently, you only need to use this method
+for side-effect targets that are built as a result of
+multiple build commands.
-The first way you can call
-.BR SConscript ()
-is to explicitly specify one or more
-.I scripts
-as the first argument.
-A single script may be specified as a string;
-multiple scripts must be specified as a list
-(either explicitly or as created by
-a function like
-.BR Split ()).
+.TP
+.RI SourceCode( entries ", " builder )
+Arrange for non-existent source files to
+be fetched from a source code management system
+using the specified
+.IR builder .
+The specified
+.I entries
+may be a Node, string or list of both,
+and may represent either individual
+source files or directories in which
+source files can be found.
+
+For any non-existent source files,
+.B scons
+will search up the directory tree
+and use the first
+.B SourceCode
+builder it finds.
+The specified
+.I builder
+may be
+.BR None ,
+in which case
+.B scons
+will not use a builder to fetch
+source files for the specified
+.IR entries ,
+even if a
+.B SourceCode
+builder has been specified
+for a directory higher up the tree.
-The second way you can call
-.BR SConscript ()
-is to specify a list of (sub)directory names
-as a
-.RI dirs= subdirs
-keyword argument.
-In this case,
.B scons
will, by default,
-execute a subsidiary configuration file named
-.B SConscript
-in each of the specified directories.
-You may specify a name other than
-.B SConscript
-by supplying an optional
-.RI name= script
-keyword argument.
+fetch files from SCCS or RCS subdirectories
+without explicit configuration.
+This takes some extra processing time
+to search for the necessary
+source code management files on disk.
+You can avoid these extra searches
+and speed up your build a little
+by disabling these searches as follows:
+.ES
+env.SourceCode('.', None)
+.EE
-The optional
-.I exports
-argument provides a list of variable names or a dictionary of
-named values to export to the
-.IR script(s) ". "
-These variables are locally exported only to the specified
-.IR script(s) ,
-and do not affect the
-global pool of variables used by
-the
-.BR Export ()
-function.
-'\"If multiple dirs are provided,
-'\"each script gets a fresh export.
-The subsidiary
-.I script(s)
-must use the
-.BR Import ()
-function to import the variables.
-
-The optional
-.I build_dir
-argument specifies that all of the target files
-(for example, object files and executables)
-that would normally be built in the subdirectory in which
-.I script
-resides should actually
-be built in
-.IR build_dir .
-
-The optional
-.I src_dir
-argument specifies that the
-source files from which
-the target files should be built
-can be found in
-.IR src_dir .
-
-By default,
-.B scons
-will link or copy (depending on the platform)
-all the source files into the build directory.
-This behavior may be disabled by
-setting the optional
-.I duplicate
-argument to 0
-(it is set to 1 by default),
-in which case
-.B scons
-will refer directly to
-the source files in their source directory
-when building target files.
-(Setting
-.IR duplicate =0
-is usually safe, and always more efficient
-than the default of
-.IR duplicate =1,
-but it may cause build problems in certain end-cases,
-such as compiling from source files that
-are generated by the build.)
-
-Any variables returned by
-.I script
-using
-.BR Return ()
-will be returned by the call to
-.BR SConscript ().
-
-Examples:
-
-.ES
-SConscript('subdir/SConscript')
-foo = SConscript('sub/SConscript', exports='env')
-SConscript('dir/SConscript', exports=['env', 'variable'])
-SConscript('src/SConscript', build_dir='build', duplicate=0)
-SConscript('bld/SConscript', src_dir='src', exports='env variable')
-SConscript(dirs=['sub1', 'sub2'])
-SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SConscriptChdir( value )
-.TP
-.RI env.SConscriptChdir( value )
-By default,
-.B scons
-changes its working directory
-to the directory in which each
-subsidiary SConscript file lives.
-This behavior may be disabled
-by specifying either:
-
-.ES
-SConscriptChdir(0)
-env.SConscriptChdir(0)
-.EE
-.IP
-in which case
-.B scons
-will stay in the top-level directory
-while reading all SConscript files.
-(This may be necessary when building from repositories,
-when all the directories in which SConscript files may be found
-don't necessarily exist locally.)
-
-You may enable and disable
-this ability by calling
-SConscriptChdir()
-multiple times:
-
-.ES
-env = Environment()
-SConscriptChdir(0)
-SConscript('foo/SConscript') # will not chdir to foo
-env.SConscriptChdir(1)
-SConscript('bar/SConscript') # will chdir to bar
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SConsignFile([ file ])
-.TP
-.RI env.SConsignFile([ file ])
-This tells
-.B scons
-to store all file signatures
-in the specified
-.IR file .
-If the
-.I file
-is omitted,
-.B .sconsign.dbm
-is used by default.
-If
-.I file
-is not an absolute path name,
-the file is placed in the same directory as the top-level
-.B SConstruct
-file.
-Examples:
-
-.ES
-# Stores signatures in ".sconsign.dbm"
-# in the top-level SConstruct directory.
-SConsignFile()
-
-# Stores signatures in the file "etc/scons-signatures"
-# relative to the top-level SConstruct directory.
-SConsignFile("etc/scons-signatures")
-
-# Stores signatures in the specified absolute file name.
-SConsignFile("/home/me/SCons/signatures")
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SetOption( name ", " value )
-.TP
-.RI env.SetOption( name ", " value )
-This function provides a way to set a select subset of the scons command
-line options from a SConscript file. The options supported are: clean which
-cooresponds to -c, --clean, and --remove; implicit_cache which corresponds
-to --implicit-cache; max_drift which corresponds to --max-drift; and
-num_jobs which corresponds to -j and --jobs. See the documentation for the
-corresponding command line object for information about each specific
-option. Example:
-
-.ES
-SetOption('max_drift', 1)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SideEffect( side_effect ", " target )
-.TP
-.RI env.SideEffect( side_effect ", " target )
-Declares
-.I side_effect
-as a side effect of building
-.IR target .
-Both
-.I side_effect
-and
-.I target
-can be a list, a file name, or a node.
-A side effect is a target that is created
-as a side effect of building other targets.
-For example, a Windows PDB
-file is created as a side effect of building the .obj
-files for a static library.
-If a target is a side effect of multiple build commands,
-.B scons
-will ensure that only one set of commands
-is executed at a time.
-Consequently, you only need to use this method
-for side-effect targets that are built as a result of
-multiple build commands.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SourceCode( entries ", " builder )
-.TP
-.RI env.SourceCode( entries ", " builder )
-Arrange for non-existent source files to
-be fetched from a source code management system
-using the specified
-.IR builder .
-The specified
-.I entries
-may be a Node, string or list of both,
-and may represent either individual
-source files or directories in which
-source files can be found.
-
-For any non-existent source files,
-.B scons
-will search up the directory tree
-and use the first
-.B SourceCode
-builder it finds.
-The specified
-.I builder
-may be
-.BR None ,
-in which case
-.B scons
-will not use a builder to fetch
-source files for the specified
-.IR entries ,
-even if a
-.B SourceCode
-builder has been specified
-for a directory higher up the tree.
-
-.B scons
-will, by default,
-fetch files from SCCS or RCS subdirectories
-without explicit configuration.
-This takes some extra processing time
-to search for the necessary
-source code management files on disk.
-You can avoid these extra searches
-and speed up your build a little
-by disabling these searches as follows:
-
-.ES
-env.SourceCode('.', None)
-.EE
-
-.IP
-Note that if the specified
-.I builder
-is one you create by hand,
-it must have an associated
-construction environment to use
-when fetching a source file.
+.IP
+Note that if the specified
+.I builder
+is one you create by hand,
+it must have an associated
+construction environment to use
+when fetching a source file.
.B scons
provides a set of canned factory
Builders for various popular
source code management systems.
Canonical examples of invocation include:
-
.ES
env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
.EE
'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
'\"
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
'\".TP
'\".RI Subversion( repository ", " module )
'\"A factory function that
'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
'\".EE
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SourceSignatures( type )
-.TP
-.RI env.SourceSignatures( type )
-This function tells SCons what type of signature to use for source files:
-.B "MD5"
-or
-.BR "timestamp" .
-If the environment method is used,
-the specified type of source signature
-is only used when deciding whether targets
-built with that environment are up-to-date or must be rebuilt.
-If the global function is used,
-the specified type of source signature becomes the default
-used for all decisions
-about whether targets are up-to-date.
-
-"MD5" means the signature of a source file
-is the MD5 checksum of its contents.
-"timestamp" means the signature of a source file
-is its timestamp (modification time).
-When using "timestamp" signatures,
-changes in the command line will not cause files to be rebuilt.
-"MD5" signatures take longer to compute,
-but are more accurate than "timestamp" signatures.
-The default is "MD5".
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Split( arg )
-.TP
-.RI env.Split( arg )
-Returns a list of file names or other objects.
-If arg is a string,
-it will be split on strings of white-space characters
-within the string,
-making it easier to write long lists of file names.
-If arg is already a list,
-the list will be returned untouched.
-If arg is any other type of object,
-it will be returned as a list
-containing just the object.
-
-.ES
-files = Split("f1.c f2.c f3.c")
-files = env.Split("f4.c f5.c f6.c")
-files = Split("""
- f7.c
- f8.c
- f9.c
-""")
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI TargetSignatures( type )
-.TP
-.RI env.TargetSignatures( type )
-This function tells SCons what type of signatures to use
-for target files:
-.B "build"
-or
-.BR "content" .
-If the environment method is used,
-the specified type of signature is only used
-for targets built with that environment.
-If the global function is used,
-the specified type of signature becomes the default
-used for all target files that
-don't have an explicit target signature type
-specified for their environments.
-
-"build" means the signature of a target file
-is made by concatenating all of the
-signatures of all its source files.
-"content" means the signature of a target
-file is an MD5 checksum of its contents.
-"build" signatures are usually faster to compute,
-but "content" signatures can prevent unnecessary rebuilds
-when a target file is rebuilt to the exact same contents
-as the previous build.
-The default is "build".
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Tool( string )
-Returns a callable object
-that can be used to initialize
-a construction environment using the
-tools keyword of the Environment() method.
-The object may be called with a construction
-environment as an argument,
-in which case the object will be
-add the necessary variables
-to the construction environment
-and the name of the tool will be added to the
-.B $TOOLS
-construction variable.
-
-.ES
-env = Environment(tools = [ Tool('msvc') ])
-
-env = Environment()
-t = Tool('msvc')
-t(env) # adds 'msvc' to the TOOLS variable
-.EE
-.TP
-.RI env.Tool( string )
-Applies the callable object for the specified tool
-.I string
-to the environment through which the method was called.
-
-.ES
-env.Tool('gcc')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Value( value )
-.TP
-.RI env.Value( value )
-Returns a Node object representing the specified Python value. Value
-nodes can be used as dependencies of targets. If the result of
-calling
-.BR str( value )
-changes between SCons runs, any targets depending on
-.BR Value( value )
-will be rebuilt. When using timestamp source signatures, Value nodes'
-timestamps are equal to the system time when the node is created.
-
-.ES
-def create(target, source, env):
- f = open(str(target[0]), 'wb')
- f.write('prefix=' + source[0].get_contents())
-
-prefix = ARGUMENTS.get('prefix', '/usr/local')
-env = Environment()
-env['BUILDERS']['Config'] = Builder(action = create)
-env.Config(target = 'package-config', source = Value(prefix))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI WhereIs( program ", [" path ", [" pathext ]])
-.TP
-.RI env.WhereIs( program ", [" path ", [" pathext ]])
-
-Searches for the specified executable
-.I program,
-returning the full path name to the program
-if it is found,
-and returning None if not.
-Searches the specified
-.I path,
-the value of the calling environment's PATH
-(env['ENV']['PATH']),
-or the user's current external PATH
-(os.environ['PATH'])
-by default.
-On Win32 systems, searches for executable
-programs with any of the file extensions
-listed in the specified
-.I pathext,
-the calling environment's PATHEXT
-(env['ENV']['PATHEXT'])
-or the user's current PATHEXT
-(os.environ['PATHEXT'])
-by default.
-
-.SS Construction Variables
-.\" XXX From Gary Ruben, 23 April 2002:
-.\" I think it would be good to have an example with each construction
-.\" variable description in the documentation.
-.\" eg.
-.\" CC The C compiler
-.\" Example: env["CC"] = "c68x"
-.\" Default: env["CC"] = "cc"
-.\"
-.\" CCCOM The command line ...
-.\" Example:
-.\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
-.\" env["CC"] = "c68x"
-.\" env["CFLAGS"] = "-ps -qq -mr"
-.\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
-.\" Default:
-.\" (I dunno what this is ;-)
-A construction environment has an associated dictionary of
-.I construction variables
-that are used by built-in or user-supplied build rules.
-Construction variables must follow the same rules for
-Python identifiers:
-the initial character must be an underscore or letter,
-followed by any number of underscores, letters, or digits.
+.SS Construction Variables
+.\" XXX From Gary Ruben, 23 April 2002:
+.\" I think it would be good to have an example with each construction
+.\" variable description in the documentation.
+.\" eg.
+.\" CC The C compiler
+.\" Example: env["CC"] = "c68x"
+.\" Default: env["CC"] = "cc"
+.\"
+.\" CCCOM The command line ...
+.\" Example:
+.\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
+.\" env["CC"] = "c68x"
+.\" env["CFLAGS"] = "-ps -qq -mr"
+.\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
+.\" Default:
+.\" (I dunno what this is ;-)
+A construction environment has an associated dictionary of
+.I construction variables
+that are used by built-in or user-supplied build rules.
+Construction variables must follow the same rules for
+Python identifiers:
+the initial character must be an underscore or letter,
+followed by any number of underscores, letters, or digits.
A number of useful construction variables are automatically defined by
scons for each supported platform, and additional construction variables
Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
are included on this command line.
-.IP BIBTEX
-The bibliography generator for the TeX formatter and typesetter and the
-LaTeX structured formatter and typesetter.
-
-.IP BIBTEXCOM
-The command line used to call the bibliography generator for the
-TeX formatter and typesetter and the LaTeX structured formatter and
-typesetter.
-
-.IP BIBTEXFLAGS
-General options passed to the bibliography generator for the TeX formatter
-and typesetter and the LaTeX structured formatter and typesetter.
-
.IP BITKEEPER
The BitKeeper executable.
are available by default.
If you initialize this variable when an
Environment is created:
-
.ES
env = Environment(BUILDERS = {'NewBuilder' : foo})
.EE
the default Builders will no longer be available.
To use a new Builder object in addition to the default Builders,
add your new Builder object like this:
-
.ES
env = Environment()
env.Append(BUILDERS = {'NewBuilder' : foo})
.EE
.IP
or this:
-
.ES
env = Environment()
env['BUILDERS]['NewBuilder'] = foo
.IP JAR
The Java archive tool.
-.IP JARCHDIR
-The directory to which the Java archive tool should change
-(using the
-.B \-C
-option).
-
.IP JARCOM
The command line used to call the Java archive tool.
variables CPPPATH, LIBPATH, LIBS, PROGEMITTER, SHLIBEMITTER and LIBEMITTER
are modified. Because the build-performance is affected when using this tool,
you have to explicitly specify it at Environment creation:
-
.ES
Environment(tools=['default','qt']).
.EE
env2 = env.Copy(CC="cl.exe")
.EE
-.SS Configure Contexts
+.SS Configure contexts
.B scons
supports
.TP
.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ])
-.TP
-.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ])
This creates a configure context, which can be used to perform checks.
.I env
specifies the environment for building the tests.
Checks if
.I header
is usable in the specified language.
-.I header
-may be a list,
-in which case the last item in the list
-is the header file to be checked,
-and the previous list items are
-header files whose
-.B #include
-lines should precede the
-header line being checked for.
The optional argument
.I include_quotes
must be
.B Configure.CheckHeader
which checks if
.I header
-is usable in the C language.
-.I header
-may be a list,
-in which case the last item in the list
-is the header file to be checked,
-and the previous list items are
-header files whose
-.B #include
-lines should precede the
-header line being checked for.
-The optional argument
+is usable in the C language. The optional argument
.I include_quotes
must be
a two character string, where the first character denotes the opening
.B Configure.CheckHeader
which checks if
.I header
-is usable in the C++ language.
-.I header
-may be a list,
-in which case the last item in the list
-is the header file to be checked,
-and the previous list items are
-header files whose
-.B #include
-lines should precede the
-header line being checked for.
-The optional argument
+is usable in the C++ language. The optional argument
.I include_quotes
must be
a two character string, where the first character denotes the opening
specifies the library to check.
.I header
specifies a header to check for.
-.I header
-may be a list,
-in which case the last item in the list
-is the header file to be checked,
-and the previous list items are
-header files whose
-.B #include
-lines should precede the
-header line being checked for.
.I language
may be one of 'C','c','CXX','cxx','C++' and 'c++'.
.I call
is set to the build target node, if the build was successful.
.EE
-Example for implementing and using custom tests:
+Example for implementing and using custom tests:
+
+.ES
+def CheckQt(context, qtdir):
+ context.Message( 'Checking for qt ...' )
+ lastLIBS = context.env['LIBS']
+ lastLIBPATH = context.env['LIBPATH']
+ lastCPPPATH= context.env['CPPPATH']
+ context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
+ ret = context.TryLink("""
+#include <qapp.h>
+int main(int argc, char **argv) {
+ QApplication qapp(argc, argv);
+ return 0;
+}
+""")
+ if not ret:
+ context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
+ context.Result( ret )
+ return ret
+
+env = Environment()
+conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
+if not conf.CheckQt('/usr/lib/qt'):
+ print 'We really need qt!'
+ Exit(1)
+env = conf.Finish()
+.EE
+
+.SS Construction Variable Options
+
+Often when building software, various options need to be specified at build
+time that are not known when the SConstruct/SConscript files are
+written. For example, libraries needed for the build may be in non-standard
+locations, or site-specific compiler options may need to be passed to the
+compiler.
+.B scons
+provides a mechanism for overridding construction variables from the
+command line or a text-based SConscript file through an Options
+object. To create an Options object, call the Options() function:
+
+.TP
+.RI Options([ files "], [" args ])
+This creates an Options object that will read construction variables from
+the file or list of filenames specified in
+.IR files .
+If no files are specified,
+or the
+.I files
+argument is
+.BR None ,
+then no files will be read.
+The optional argument
+.I args
+is a dictionary of
+values that will override anything read from the specified files;
+it is primarily intended to be passed the
+.B ARGUMENTS
+dictionary that holds variables
+specified on the command line.
+Example:
+
+.ES
+opts = Options('custom.py')
+opts = Options('overrides.py', ARGUMENTS)
+opts = Options(None, {FOO:'expansion', BAR:7})
+.EE
+
+Options objects have the following methods:
+
+.TP
+.RI Add( key ", [" help ", " default ", " validator ", " converter ])
+This adds a customizable construction variable to the Options object.
+.I key
+is the name of the variable.
+.I help
+is the help text for the variable.
+.I default
+is the default value of the variable.
+.I validator
+is called to validate the value of the variable, and should take three
+arguments: key, value, and environment
+.I converter
+is called to convert the value before putting it in the environment, and
+should take a single argument: value. Example:
+
+.ES
+opts.Add('CC', 'The C compiler')
+.EE
+
+.TP
+.RI Update( env ", [" args ])
+This updates a construction environment
+.I env
+with the customized construction variables. Normally this method is not
+called directly, but is called indirectly by passing the Options object to
+the Environment() function:
+
+.ES
+env = Environment(options=opts)
+.EE
+
+.TP
+.RI Save( filename ", " env )
+This saves the currently set options into a script file named
+.I filename
+that can be used on the next invocation to automatically load the current
+settings. This method combined with the Options method can be used to
+support caching of options between runs.
+
+.ES
+env = Environment()
+opts = Options(['options.cache', 'custom.py'])
+opts.Add(...)
+opts.Update(env)
+opts.Save('options.cache', env)
+.EE
+
+.TP
+.RI GenerateHelpText( env ", [" sort ])
+This generates help text documenting the customizable construction
+variables suitable to passing in to the Help() function.
+.I env
+is the construction environment that will be used to get the actual values
+of customizable variables. Calling with
+an optional
+.I sort
+function
+will cause the output to be sorted
+by the specified argument.
+The specific
+.I sort
+function
+should take two arguments
+and return
+-1, 0 or 1
+(like the standard Python
+.I cmp
+function).
+
+.ES
+Help(opts.GenerateHelpText(env))
+Help(opts.GenerateHelpText(env, sort=cmp))
+.EE
+
+The text based SConscript file is executed as a Python script, and the
+global variables are queried for customizable construction
+variables. Example:
+
+.ES
+CC = 'my_cc'
+.EE
+
+.SS Other Functions
+
+.B scons
+also provides various additional functions,
+not associated with a construction environment,
+that SConscript files can use:
+
+.TP
+.RI AddPostAction( target ", " action )
+Arranges for the specified
+.I action
+to be performed
+after the specified
+.I target
+has been built.
+The specified action(s) may be
+an Action object, or anything that
+can be converted into an Action object
+(see below).
+
+.TP
+.RI AddPreAction( target ", " action )
+Arranges for the specified
+.I action
+to be performed
+before the specified
+.I target
+is built.
+The specified action(s) may be
+an Action object, or anything that
+can be converted into an Action object
+(see below).
+
+.TP
+.RI Alias( name )
+Creates or references an alias independent of the construction environment.
+
+.ES
+Alias('install')
+.EE
+
+.TP
+.RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
+This specifies a build directory
+.I build_dir
+in which to build all derived files
+that would normally be built under
+.IR src_dir .
+Multiple build directories can be set up for multiple build variants, for
+example.
+.I src_dir
+must be underneath the SConstruct file's directory,
+and
+.I build_dir
+may not be underneath the
+.I src_dir .
+
+The default behavior is for
+.B scons
+to duplicate all of the files in the tree underneath
+.I src_dir
+into
+.IR build_dir ,
+and then build the derived files within the copied tree.
+(The duplication is performed by
+linking or copying,
+depending on the platform.)
+This guarantees correct builds
+regardless of whether intermediate source files
+are generated during the build,
+where preprocessors or other scanners search
+for included files,
+or whether individual compilers or other invoked tools
+are hard-coded to put derived files in the same directory as source files.
+
+This behavior of making a complete copy of the source tree
+may be disabled by setting
+.I duplicate
+to 0.
+This will cause
+.B scons
+to invoke Builders using the
+path names of source files in
+.I src_dir
+and the path names of derived files within
+.IR build_dir .
+This is always more efficient than
+.IR duplicate =1,
+and is usually safe for most builds.
+Specifying
+.IR duplicate =0,
+however,
+may cause build problems
+if source files are generated during the build,
+if any invoked tools are hard-coded to
+put derived files in the same directory as the source files.
+
+Note that specifying a
+.B BuildDir
+works most naturally
+with a subsidiary SConscript file
+in the source directory.
+However,
+you would then call the subsidiary SConscript file
+not in the source directory,
+but in the
+.I build_dir ,
+as if
+.B scons
+had made a virtual copy of the source tree
+regardless of the value of
+.IR duplicate .
+This is how you tell
+.B scons
+which variant of a source tree to build.
+For example:
+
+.ES
+BuildDir('build-variant1', 'src')
+SConscript('build-variant1/SConscript')
+BuildDir('build-variant2', 'src')
+SConscript('build-variant2/SConscript')
+.EE
+
+.IP
+See also the
+.BR SConscript ()
+function, described below,
+for another way to
+specify a build directory
+in conjunction with calling a subsidiary
+SConscript file.)
+
+.TP
+.RI CacheDir( cache_dir )
+Specifies that
+.B scons
+will maintain a cache of derived files in
+.I cache_dir .
+The derived files in the cache will be shared
+among all the builds using the same
+.BR CacheDir ()
+call.
+
+When a
+.BR CacheDir ()
+is being used and
+.B scons
+finds a derived file that needs to be rebuilt,
+it will first look in the cache to see if a
+derived file has already been built
+from identical input files and an identical build action
+(as incorporated into the MD5 build signature).
+If so,
+.B scons
+will retrieve the file from the cache.
+If the derived file is not present in the cache,
+.B scons
+will rebuild it and
+then place a copy of the built file in the cache
+(identified by its MD5 build signature),
+so that it may be retrieved by other
+builds that need to build the same derived file
+from identical inputs.
+
+Use of a specified
+.BR CacheDir()
+may be disabled for any invocation
+by using the
+.B --cache-disable
+option.
+
+If the
+.B --cache-force
+option is used,
+.B scons
+will place a copy of
+.I all
+derived files in the cache,
+even if they already existed
+and were not built by this invocation.
+This is useful to populate a cache
+the first time
+.BR CacheDir ()
+is added to a build,
+or after using the
+.B --cache-disable
+option.
+
+When using
+.BR CacheDir (),
+.B scons
+will report,
+"Retrieved `file' from cache,"
+unless the
+.B --cache-show
+option is being used.
+When the
+.B --cache-show
+option is used,
+.B scons
+will print the action that
+.I would
+have been used to build the file,
+without any indication that
+the file was actually retrieved from the cache.
+This is useful to generate build logs
+that are equivalent regardless of whether
+a given derived file has been built in-place
+or retrieved from the cache.
+
+.TP
+.RI Clean( target ", " files_or_dirs )
+This specifies a list of files or directories which should be removed
+whenever the target is specified with the
+.B -c
+command line option.
+Multiple calls to
+.BR Clean ()
+are legal,
+and create a new target or add files and directories to the
+clean list for the specified target.
+
+Multiple files or directories should be specified
+either as separate arguments to the
+.BR Clean ()
+method, or as a list.
+.BR Clean ()
+will also accept the return value of any of the construction environment
+Builder methods.
+Examples:
+
+.ES
+Clean('foo', ['bar', 'baz'])
+Clean('dist', env.Program('hello', 'hello.c'))
+.EE
+
+.TP
+.RI Default( targets )
+This specifies a list of default targets,
+which will be built by
+.B scons
+if no explicit targets are given on the command line.
+Multiple calls to
+.BR Default ()
+are legal,
+and add to the list of default targets.
+
+Multiple targets should be specified as
+separate arguments to the
+.BR Default ()
+method, or as a list.
+.BR Default ()
+will also accept the Node returned by any
+of a construction environment's
+builder methods.
+Examples:
+
+.ES
+Default('foo', 'bar', 'baz')
+Default(['a', 'b', 'c'])
+hello = env.Program('hello', 'hello.c')
+Default(hello)
+.EE
+.IP
+An argument to
+.BR Default ()
+of
+.B None
+will clear all default targets.
+Later calls to
+.BR Default ()
+will add to the (now empty) default-target list
+like normal.
+
+.TP
+.RI DefaultEnvironment([ args ])
+Creates and returns a default construction environment object.
+This construction environment is used internally by SCons
+in order to fetch source files transparently
+from source code management systems.
+
+.TP
+.RI Dir( name ", [" directory ])
+This returns an object that represents a given directory
+.IR name .
+.I name
+can be a relative or absolute path.
+.I directory
+is an optional directory that will be used as the parent directory.
+
+.TP
+.RI EnsurePythonVersion( major ", " minor )
+Ensure that the Python version is at least
+.IR major . minor .
+This function will
+print out an error message and exit SCons with a non-zero exit code if the
+actual Python version is not late enough.
+
+.ES
+EnsurePythonVersion(2,2)
+.EE
+
+.TP
+.RI EnsureSConsVersion( major ", " minor )
+Ensure that the SCons version is at least
+.IR major . minor .
+This function will
+print out an error message and exit SCons with a non-zero exit code if the
+actual SCons version is not late enough.
+
+.ES
+EnsureSConsVersion(0,9)
+.EE
+
+.TP
+.RI Exit([ value ])
+This tells
+.B scons
+to exit immediately
+with the specified
+.IR value .
+A default exit value of
+.B 0
+(zero)
+is used if no value is specified.
+
+.TP
+.RI Export( vars )
+This tells
+.B scons
+to export a list of variables from the current
+SConscript file to all other SConscript files.
+The exported variables are kept in a global collection,
+so subsequent calls to
+.BR Export ()
+will over-write previous exports that have the same name.
+Multiple variable names can be passed to
+.BR Export ()
+as separate arguments or as a list. A dictionary can be used to map
+variables to a different name when exported. Both local variables and
+global variables can be exported.
+Examples:
+
+.ES
+env = Environment()
+# Make env available for all SConscript files to Import().
+Export("env")
+
+package = 'my_name'
+# Make env and package available for all SConscript files:.
+Export("env", "package")
+
+# Make env and package available for all SConscript files:
+Export(["env", "package"])
+
+# Make env available using the name debug:.
+Export({"debug":env})
+.EE
+
+.IP
+Note that the
+.BR SConscript ()
+function supports an
+.I exports
+argument that makes it easier to to export a variable or
+set of variables to a single SConscript file.
+See the description of the
+.BR SConscript ()
+function, below.
+
+.TP
+.RI File( name ", [" directory ])
+This returns an object that represents a given file
+.IR name .
+.I name
+can be a relative or absolute path.
+.I directory
+is an optional directory that will be used as the parent directory.
+
+.TP
+.RI FindFile( file ", " dirs )
+Search for
+.I file
+in the path specified by
+.IR dirs .
+.I file
+may be a list of file names or a single file name. In addition to searching
+for files that exist in the filesytem, this function also searches for
+derived files that have not yet been built.
+
+.ES
+foo = FindFile('foo', ['dir1', 'dir2'])
+.EE
+.\"
+.\".TP
+.\".RI GetBuildPath( XXX )
+.\"XXX
+.\"
+.\".TP
+.\".RI GetLaunchDir( XXX )
+.\"XXX
+
+.TP
+.RI GetOption( name )
+This function provides a way to query a select subset of the scons command line
+options from a SConscript file. See
+.IR SetOption ()
+for a description of the options available.
+
+.TP
+.RI Help( text )
+This specifies help text to be printed if the
+.B -h
+argument is given to
+.BR scons .
+.B scons
+will exit after printing out the help text.
+
+.TP
+.RI Import( vars )
+This tells
+.B scons
+to import a list of variables into the current SConscript file. This
+will import variables that were exported with
+.BR Export ()
+or in the
+.I exports
+argument to
+.BR SConscript ().
+Variables exported by
+.BR SConscript ()
+have precedence.
+Multiple variable names can be passed to
+.BR Import ()
+as separate arguments or as a list. The variable "*" can be used
+to import all variables.
+Examples:
+
+.ES
+Import("env")
+Import("env", "variable")
+Import(["env", "variable"])
+Import("*")
+.EE
+
+.TP
+.RI Literal( string )
+The specified
+.I string
+will be preserved as-is
+and not have construction variables expanded.
+
+.TP
+.RI Local( targets )
+The specified
+.I targets
+will have copies made in the local tree,
+even if an already up-to-date copy
+exists in a repository.
+
+.TP
+.RI ParseConfig( env ", " command ", [" function ])
+Calls the specified
+.I function
+to modify the specified environment
+.I env
+as specified by the output of
+.I command .
+The default
+.I function
+expects the output of a typical
+.I *-config command
+(for example,
+.BR gtk-config )
+and parses the returned
+.BR -L ,
+.BR -l ,
+.B -I
+and other options
+into the
+.BR LIBPATH ,
+.BR LIBS ,
+.B CPPPATH
+and
+.B CCFLAGS
+variables,
+respectively.
+
+.TP
+.RI Platform( string )
+Returns a callable object
+that can be used to initialize
+a construction environment using the
+platform keyword of the Environment() method.
+
+.ES
+env = Environment(platform = Platform('win32'))
+.EE
+.IP
+Note that the
+.B win32
+platform adds the
+.B SYSTEMROOT
+variable from the user's external environment
+to the construction environment's
+.B ENV
+dictionary.
+This is so that any executed commands
+that use sockets to connect with other systems
+(such as fetching source files from
+external CVS repository specifications like
+.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
+will work on Win32 systems.
+
+.TP
+.RI Repository( directory )
+Specifies that
+.I directory
+is a repository to be searched for files.
+Multiple calls to
+.BR Repository ()
+are legal,
+and each one adds to the list of
+repositories that will be searched.
+
+To
+.BR scons ,
+a repository is a copy of the source tree,
+from the top-level directory on down,
+which may contain
+both source files and derived files
+that can be used to build targets in
+the local source tree.
+The canonical example would be an
+official source tree maintained by an integrator.
+If the repository contains derived files,
+then the derived files should have been built using
+.BR scons ,
+so that the repository contains the necessary
+signature information to allow
+.B scons
+to figure out when it is appropriate to
+use the repository copy of a derived file,
+instead of building one locally.
+
+Note that if an up-to-date derived file
+already exists in a repository,
+.B scons
+will
+.I not
+make a copy in the local directory tree.
+In order to guarantee that a local copy
+will be made,
+use the
+.B Local()
+method.
+
+.TP
+.RI Return( vars )
+This tells
+.B scons
+what variable(s) to use as the return value(s) of the current SConscript
+file. These variables will be returned to the "calling" SConscript file
+as the return value(s) of
+.BR SConscript ().
+Multiple variable names should be passed to
+.BR Return ()
+as a list. Example:
+
+.ES
+Return("foo")
+Return(["foo", "bar"])
+.EE
+
+.TP
+.RI SConsignFile([ file ])
+This tells
+.B scons
+to store all file signatures
+in the specified
+.IR file .
+If the
+.I file
+is omitted,
+.B .sconsign.dbm
+is used by default.
+If
+.I file
+is not an absolute path name,
+the file is placed in the same directory as the top-level
+.B SConstruct
+file.
+Examples:
+
+.ES
+# Stores signatures in ".sconsign.dbm"
+# in the top-level SConstruct directory.
+SConsignFile()
+
+# Stores signatures in the file "etc/scons-signatures"
+# relative to the top-level SConstruct directory.
+SConsignFile("etc/scons-signatures")
+
+# Stores signatures in the specified absolute file name.
+SConsignFile("/home/me/SCons/signatures")
+.EE
+
+.TP
+.RI SetOption( name ", " value )
+This function provides a way to set a select subset of the scons command
+line options from a SConscript file. The options supported are: clean which
+cooresponds to -c, --clean, and --remove; implicit_cache which corresponds
+to --implicit-cache; max_drift which corresponds to --max-drift; and
+num_jobs which corresponds to -j and --jobs. See the documentation for the
+corresponding command line object for information about each specific
+option. Example:
+
+.ES
+SetOption('max_drift', 1)
+.EE
+
+.TP
+.RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
+.TP
+.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
+This tells
+.B scons
+to execute
+one or more subsidiary SConscript (configuration) files.
+There are two ways to call the
+.BR SConscript ()
+function.
+
+The first way you can call
+.BR SConscript ()
+is to explicitly specify one or more
+.I scripts
+as the first argument.
+A single script may be specified as a string;
+multiple scripts must be specified as a list
+(either explicitly or as created by
+a function like
+.BR Split ()).
+
+The second way you can call
+.BR SConscript ()
+is to specify a list of (sub)directory names
+as a
+.RI dirs= subdirs
+keyword argument.
+In this case,
+.B scons
+will, by default,
+execute a subsidiary configuration file named
+.B SConscript
+in each of the specified directories.
+You may specify a name other than
+.B SConscript
+by supplying an optional
+.RI name= script
+keyword argument.
+
+The optional
+.I exports
+argument provides a list of variable names or a dictionary of
+named values to export to the
+.IR script(s) ". "
+These variables are locally exported only to the specified
+.IR script(s) ,
+and do not affect the
+global pool of variables used by
+the
+.BR Export ()
+function.
+'\"If multiple dirs are provided,
+'\"each script gets a fresh export.
+The subsidiary
+.I script(s)
+must use the
+.BR Import ()
+function to import the variables.
+
+The optional
+.I build_dir
+argument specifies that all of the target files
+(for example, object files and executables)
+that would normally be built in the subdirectory in which
+.I script
+resides should actually
+be built in
+.IR build_dir .
+
+The optional
+.I src_dir
+argument specifies that the
+source files from which
+the target files should be built
+can be found in
+.IR src_dir .
+
+By default,
+.B scons
+will link or copy (depending on the platform)
+all the source files into the build directory.
+This behavior may be disabled by
+setting the optional
+.I duplicate
+argument to 0
+(it is set to 1 by default),
+in which case
+.B scons
+will refer directly to
+the source files in their source directory
+when building target files.
+(Setting
+.IR duplicate =0
+is usually safe, and always more efficient
+than the default of
+.IR duplicate =1,
+but it may cause build problems in certain end-cases,
+such as compiling from source files that
+are generated by the build.)
+
+Any variables returned by
+.I script
+using
+.BR Return ()
+will be returned by the call to
+.BR SConscript ().
+
+Examples:
+
+.ES
+SConscript('subdir/SConscript')
+foo = SConscript('sub/SConscript', exports='env')
+SConscript('dir/SConscript', exports=['env', 'variable'])
+SConscript('src/SConscript', build_dir='build', duplicate=0)
+SConscript('bld/SConscript', src_dir='src', exports='env variable')
+SConscript(dirs=['sub1', 'sub2'])
+SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
+.EE
+.TP
+.RI SConscriptChdir( value )
+By default,
+.B scons
+changes its working directory
+to the directory in which each
+subsidiary SConscript file lives.
+This behavior may be disabled
+by specifying:
.ES
-def CheckQt(context, qtdir):
- context.Message( 'Checking for qt ...' )
- lastLIBS = context.env['LIBS']
- lastLIBPATH = context.env['LIBPATH']
- lastCPPPATH= context.env['CPPPATH']
- context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
- ret = context.TryLink("""
-#include <qapp.h>
-int main(int argc, char **argv) {
- QApplication qapp(argc, argv);
- return 0;
-}
-""")
- if not ret:
- context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
- context.Result( ret )
- return ret
-
-env = Environment()
-conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
-if not conf.CheckQt('/usr/lib/qt'):
- print 'We really need qt!'
- Exit(1)
-env = conf.Finish()
+SConscriptChdir(0)
.EE
-
-.SS Construction Variable Options
-
-Often when building software, various options need to be specified at build
-time that are not known when the SConstruct/SConscript files are
-written. For example, libraries needed for the build may be in non-standard
-locations, or site-specific compiler options may need to be passed to the
-compiler.
+.IP
+in which case
.B scons
-provides a mechanism for overridding construction variables from the
-command line or a text-based SConscript file through an Options
-object. To create an Options object, call the Options() function:
+will stay in the top-level directory
+while reading all SConscript files.
+(This may be necessary when building from repositories,
+when all the directories in which SConscript files may be found
+don't necessarily exist locally.)
-.TP
-.RI Options([ files "], [" args ])
-This creates an Options object that will read construction variables from
-the file or list of filenames specified in
-.IR files .
-If no files are specified,
-or the
-.I files
-argument is
-.BR None ,
-then no files will be read.
-The optional argument
-.I args
-is a dictionary of
-values that will override anything read from the specified files;
-it is primarily intended to be passed the
-.B ARGUMENTS
-dictionary that holds variables
-specified on the command line.
-Example:
+You may enable and disable
+this ability by calling
+SConscriptChdir()
+multiple times:
.ES
-opts = Options('custom.py')
-opts = Options('overrides.py', ARGUMENTS)
-opts = Options(None, {FOO:'expansion', BAR:7})
+SConscriptChdir(0)
+SConscript('foo/SConscript') # will not chdir to foo
+SConscriptChdir(1)
+SConscript('bar/SConscript') # will chdir to bar
.EE
-Options objects have the following methods:
+.TP
+.RI SourceSignatures( type )
+This function tells SCons what type of signature to use for source files:
+.B "MD5"
+or
+.BR "timestamp" .
+"MD5" means the signature of a source file
+is the MD5 checksum of its contents.
+"timestamp" means the signature of a source file
+is its timestamp (modification time).
+When using "timestamp" signatures,
+changes in the command line will not cause files to be rebuilt.
+"MD5" signatures take longer to compute,
+but are more accurate than "timestamp" signatures.
+The default is "MD5".
.TP
-.RI Add( key ", [" help ", " default ", " validator ", " converter ])
-This adds a customizable construction variable to the Options object.
-.I key
-is the name of the variable.
-.I help
-is the help text for the variable.
-.I default
-is the default value of the variable.
-.I validator
-is called to validate the value of the variable, and should take three
-arguments: key, value, and environment
-.I converter
-is called to convert the value before putting it in the environment, and
-should take a single argument: value. Example:
+.RI Split( arg )
+Returns a list of file names or other objects.
+If arg is a string,
+it will be split on strings of white-space characters
+within the string,
+making it easier to write long lists of file names.
+If arg is already a list,
+the list will be returned untouched.
+If arg is any other type of object,
+it will be returned as a list
+containing just the object.
.ES
-opts.Add('CC', 'The C compiler')
+files = Split("f1.c f2.c f3.c")
+files = Split("""
+ f4.c
+ f5.c
+ f6.c
+""")
.EE
.TP
-.RI Update( env ", [" args ])
-This updates a construction environment
-.I env
-with the customized construction variables. Normally this method is not
-called directly, but is called indirectly by passing the Options object to
-the Environment() function:
+.RI TargetSignatures( type )
+This function tells SCons what type of signatures to use
+for target files:
+.B "build"
+or
+.BR "content" .
+"build" means the signature of a target file
+is made by concatenating all of the
+signatures of all its source files.
+"content" means the signature of a target
+file is an MD5 checksum of its contents.
+"build" signatures are usually faster to compute,
+but "content" signatures can prevent unnecessary rebuilds
+when a target file is rebuilt to the exact same contents as last time.
+The default is "build".
+
+.TP
+.RI Tool( string )
+Returns a callable object
+that can be used to initialize
+a construction environment using the
+tools keyword of the Environment() method.
.ES
-env = Environment(options=opts)
+env = Environment(tools = [ Tool('msvc') ])
.EE
-
-.TP
-.RI Save( filename ", " env )
-This saves the currently set options into a script file named
-.I filename
-that can be used on the next invocation to automatically load the current
-settings. This method combined with the Options method can be used to
-support caching of options between runs.
+.IP
+The object may be called with a construction
+environment as an argument,
+in which case the object will be
+add the necessary variables
+to the construction environment
+and the name of the tool will be added to the
+.B $TOOLS
+construction variable.
.ES
env = Environment()
-opts = Options(['options.cache', 'custom.py'])
-opts.Add(...)
-opts.Update(env)
-opts.Save('options.cache', env)
+t = Tool('msvc')
+t(env) # adds 'msvc' to the TOOLS variable
.EE
.TP
-.RI GenerateHelpText( env ", [" sort ])
-This generates help text documenting the customizable construction
-variables suitable to passing in to the Help() function.
-.I env
-is the construction environment that will be used to get the actual values
-of customizable variables. Calling with
-an optional
-.I sort
-function
-will cause the output to be sorted
-by the specified argument.
-The specific
-.I sort
-function
-should take two arguments
-and return
--1, 0 or 1
-(like the standard Python
-.I cmp
-function).
+.RI Value( value )
+Returns a Node object representing the specified Python value. Value
+nodes can be used as dependencies of targets. If the result of
+calling
+.BR str( value )
+changes between SCons runs, any targets depending on
+.BR Value( value )
+will be rebuilt. When using timestamp source signatures, Value nodes'
+timestamps are equal to the system time when the node is created.
.ES
-Help(opts.GenerateHelpText(env))
-Help(opts.GenerateHelpText(env, sort=cmp))
+def create(target, source, env):
+ f = open(str(target[0]), 'wb')
+ f.write('prefix=' + source[0].get_contents())
+
+prefix = ARGUMENTS.get('prefix', '/usr/local')
+env = Environment()
+env['BUILDERS']['Config'] = Builder(action = create)
+env.Config(target = 'package-config', source = Value(prefix))
.EE
-The text based SConscript file is executed as a Python script, and the
-global variables are queried for customizable construction
-variables. Example:
+.TP
+.RI WhereIs( program ", [" path ", [" pathext ]])
-.ES
-CC = 'my_cc'
-.EE
+Searches for the specified executable
+.I program,
+returning the full path name to the program
+if it is found,
+and returning None if not.
+Searches the specified
+.I path,
+or the user's current PATH
+(os.environ['PATH'])
+by default.
+On Win32 systems, searches for executable
+programs with any of the file extensions
+listed in the specified
+.I pathext,
+or the user's current PATHEXT
+(os.environ['PATHEXT'])
+by default.
.SH EXTENDING SCONS
.SS Builder Objects
This allows white space to be enclosed
in an argument by defining
a command in a list within a list:
-
.ES
Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
.EE
The actual target and source file name(s) may
be retrieved from their Node objects
via the built-in Python str() function:
-
.ES
target_file_name = str(target)
source_file_names = map(lambda x: str(x), source)
To help you get started using SCons,
this section contains a brief overview of some common tasks.
+NOTE: SCons does
+.I not
+build all of its targets by default,
+like other build tools do.
+The canonical way to invoke SCons
+is with a target of '.' (dot)
+to represent all targets in and below the current directory:
+
+.ES
+scons .
+.EE
+
+One or more default targets may be specified
+via the Default() method
+in the SConstruct file.
+
.SS Basic Compilation From a Single Source File
.ES
__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__"
-import SCons
import SCons.Action
import SCons.Builder
import SCons.Defaults
import SCons.Environment
import SCons.Errors
import SCons.Node
-import SCons.Node.Alias
import SCons.Node.FS
-import SCons.Options
+import SCons.Node.Python
import SCons.Platform
import SCons.SConf
import SCons.Script
-import SCons.Tool
import SCons.Util
+import SCons.Options
+import SCons
+import SCons.Node.Alias
import os
import os.path
import string
import sys
import traceback
-import types
def do_nothing(text): pass
HelpFunction = do_nothing
+default_targets = None
+clean_targets = {}
arguments = {}
-GlobalDict = {}
launch_dir = os.path.abspath(os.curdir)
# global exports set by Export():
# chdir flag
sconscript_chdir = 1
-# will be set to 1, if we are reading a SConscript
-sconscript_reading = 0
+def SConscriptChdir(flag):
+ global sconscript_chdir
+ sconscript_chdir = flag
def _scons_add_args(alist):
global arguments
"""Return the locals and globals for the function that called
into this module in the current callstack."""
try: 1/0
- except ZeroDivisionError: frame = sys.exc_info()[2].tb_frame
+ except: frame = sys.exc_info()[2].tb_frame
while frame.f_globals.get("__name__") == __name__: frame = frame.f_back
"""Compute a dictionary of exports given one of the parameters
to the Export() function or the exports argument to SConscript()."""
+ exports = SCons.Util.Split(exports)
loc, glob = get_calling_namespaces()
retval = {}
else:
stack[-1].retval = tuple(retval)
-def _SConscript(fs, *files, **kw):
- global sconscript_reading
- sconscript_reading = 1
- top = fs.Top
- sd = fs.SConstruct_dir.rdir()
- exports = kw.get('exports', [])
+# This function is responsible for converting the parameters passed to
+# SConscript() calls into a list of files and export variables. If the
+# parameters are invalid, throws SCons.Errors.UserError. Returns a tuple
+# (l, e) where l is a list of SConscript filenames and e is a list of
+# exports.
+
+def GetSConscriptFilenames(ls, kw):
+ exports = []
+
+ if len(ls) == 0:
+ try:
+ dirs = kw["dirs"]
+ except KeyError:
+ raise SCons.Errors.UserError, \
+ "Invalid SConscript usage - no parameters"
+
+ if not SCons.Util.is_List(dirs):
+ dirs = [ dirs ]
+ dirs = map(str, dirs)
+
+ name = kw.get('name', 'SConscript')
+
+ files = map(lambda n, name = name: os.path.join(n, name), dirs)
+
+ elif len(ls) == 1:
+
+ files = ls[0]
+
+ elif len(ls) == 2:
+
+ files = ls[0]
+ exports = SCons.Util.Split(ls[1])
+
+ else:
+
+ raise SCons.Errors.UserError, \
+ "Invalid SConscript() usage - too many arguments"
+
+ if not SCons.Util.is_List(files):
+ files = [ files ]
+
+ if kw.get('exports'):
+ exports.extend(SCons.Util.Split(kw['exports']))
+
+ build_dir = kw.get('build_dir')
+ if build_dir:
+ if len(files) != 1:
+ raise SCons.Errors.UserError, \
+ "Invalid SConscript() usage - can only specify one SConscript with a build_dir"
+ duplicate = kw.get('duplicate', 1)
+ src_dir = kw.get('src_dir')
+ if not src_dir:
+ src_dir, fname = os.path.split(str(files[0]))
+ else:
+ if not isinstance(src_dir, SCons.Node.Node):
+ src_dir = SCons.Node.FS.default_fs.Dir(src_dir)
+ fn = files[0]
+ if not isinstance(fn, SCons.Node.Node):
+ fn = SCons.Node.FS.default_fs.File(fn)
+ if fn.is_under(src_dir):
+ # Get path relative to the source directory.
+ fname = fn.get_path(src_dir)
+ else:
+ # Fast way to only get the terminal path component of a Node.
+ fname = fn.get_path(fn.dir)
+ BuildDir(build_dir, src_dir, duplicate)
+ files = [os.path.join(str(build_dir), fname)]
+
+ return (files, exports)
+
+def SConscript(*ls, **kw):
+ files, exports = GetSConscriptFilenames(ls, kw)
+
+ default_fs = SCons.Node.FS.default_fs
+ top = default_fs.Top
+ sd = default_fs.SConstruct_dir.rdir()
# evaluate each SConscript file
results = []
if isinstance(fn, SCons.Node.Node):
f = fn
else:
- f = fs.File(str(fn))
+ f = default_fs.File(str(fn))
_file_ = None
# Change directory to the top of the source
# tree to make sure the os's cwd and the cwd of
- # fs match so we can open the SConscript.
- fs.chdir(top, change_os_dir=1)
+ # SCons.Node.FS.default_fs match so we can open the
+ # SConscript.
+ default_fs.chdir(top, change_os_dir=1)
if f.rexists():
_file_ = open(f.rstr(), "r")
elif f.has_src_builder():
# where the SConstruct and SConscript files might be
# in different Repositories. For now, cross that
# bridge when someone comes to it.
- ldir = fs.Dir(f.dir.get_path(sd))
+ ldir = default_fs.Dir(f.dir.get_path(sd))
try:
- fs.chdir(ldir, change_os_dir=sconscript_chdir)
+ default_fs.chdir(ldir, change_os_dir=sconscript_chdir)
except OSError:
# There was no local directory, so we should be
# able to chdir to the Repository directory.
# Note that we do this directly, not through
- # fs.chdir(), because we still need to
+ # default_fs.chdir(), because we still need to
# interpret the stuff within the SConscript file
# relative to where we are logically.
- fs.chdir(ldir, change_os_dir=0)
+ default_fs.chdir(ldir, change_os_dir=0)
os.chdir(f.rfile().dir.get_abspath())
# Append the SConscript directory to the beginning
f.path)
finally:
- sconscript_reading = 0
sys.path = old_sys_path
frame = stack.pop()
try:
- fs.chdir(frame.prev_dir, change_os_dir=sconscript_chdir)
+ default_fs.chdir(frame.prev_dir, change_os_dir=sconscript_chdir)
except OSError:
# There was no local directory, so chdir to the
# Repository directory. Like above, we do this
# directly.
- fs.chdir(frame.prev_dir, change_os_dir=0)
+ default_fs.chdir(frame.prev_dir, change_os_dir=0)
os.chdir(frame.prev_dir.rdir().get_abspath())
results.append(frame.retval)
# leave this disabled until we find a more efficient mechanism.
#SCons.Node.Annotate = annotate
-class SConsEnvironment(SCons.Environment.Base):
- """An Environment subclass that contains all of the methods that
- are particular to the wrapper SCons interface and which aren't
- (or shouldn't be) part of the build engine itself.
-
- Note that not all of the methods of this class have corresponding
- global functions, there are some private methods.
- """
-
- #
- # Private methods of an SConsEnvironment.
- #
-
- def _check_version(self, major, minor, version_string):
- """Return 0 if 'major' and 'minor' are greater than the version
- in 'version_string', and 1 otherwise."""
- try:
- v_major, v_minor, v_micro, release, serial = sys.version_info
- except AttributeError:
- version = string.split(string.split(version_string, ' ')[0], '.')
- v_major = int(version[0])
- v_minor = int(re.match('\d+', version[1]).group())
- if major > v_major or (major == v_major and minor > v_minor):
- return 0
+def Default(*targets):
+ global default_targets
+ if default_targets is None:
+ default_targets = []
+ for t in targets:
+ if t is None:
+ default_targets = []
+ elif isinstance(t, SCons.Node.Node):
+ default_targets.append(t)
else:
- return 1
-
- def _get_SConscript_filenames(self, ls, kw):
- """
- Convert the parameters passed to # SConscript() calls into a list
- of files and export variables. If the parameters are invalid,
- throws SCons.Errors.UserError. Returns a tuple (l, e) where l
- is a list of SConscript filenames and e is a list of exports.
- """
- exports = []
-
- if len(ls) == 0:
- try:
- dirs = kw["dirs"]
- except KeyError:
- raise SCons.Errors.UserError, \
- "Invalid SConscript usage - no parameters"
-
- if not SCons.Util.is_List(dirs):
- dirs = [ dirs ]
- dirs = map(str, dirs)
-
- name = kw.get('name', 'SConscript')
+ default_targets.extend(SCons.Node.arg2nodes(t,
+ SCons.Node.FS.default_fs.Entry))
- files = map(lambda n, name = name: os.path.join(n, name), dirs)
+def Local(*targets):
+ for targ in targets:
+ if isinstance(targ, SCons.Node.Node):
+ targ.set_local()
+ else:
+ for t in SCons.Node.arg2nodes(targ, SCons.Node.FS.default_fs.Entry):
+ t.set_local()
- elif len(ls) == 1:
+def Help(text):
+ HelpFunction(text)
- files = ls[0]
+def BuildDir(build_dir, src_dir, duplicate=1):
+ SCons.Node.FS.default_fs.BuildDir(build_dir, src_dir, duplicate)
- elif len(ls) == 2:
+def GetBuildPath(files):
+ nodes = SCons.Node.arg2nodes(files, SCons.Node.FS.default_fs.Entry)
+ ret = map(str, nodes)
+ if len(ret) == 1:
+ return ret[0]
+ return ret
- files = ls[0]
- exports = self.Split(ls[1])
+def FindFile(file, dirs):
+ nodes = SCons.Node.arg2nodes(dirs, SCons.Node.FS.default_fs.Dir)
+ return SCons.Node.FS.find_file(file, nodes)
- else:
+def Export(*vars):
+ for var in vars:
+ global_exports.update(compute_exports(var))
- raise SCons.Errors.UserError, \
- "Invalid SConscript() usage - too many arguments"
-
- if not SCons.Util.is_List(files):
- files = [ files ]
-
- if kw.get('exports'):
- exports.extend(self.Split(kw['exports']))
-
- build_dir = kw.get('build_dir')
- if build_dir:
- if len(files) != 1:
- raise SCons.Errors.UserError, \
- "Invalid SConscript() usage - can only specify one SConscript with a build_dir"
- duplicate = kw.get('duplicate', 1)
- src_dir = kw.get('src_dir')
- if not src_dir:
- src_dir, fname = os.path.split(str(files[0]))
- else:
- if not isinstance(src_dir, SCons.Node.Node):
- src_dir = self.fs.Dir(src_dir)
- fn = files[0]
- if not isinstance(fn, SCons.Node.Node):
- fn = self.fs.File(fn)
- if fn.is_under(src_dir):
- # Get path relative to the source directory.
- fname = fn.get_path(src_dir)
- else:
- # Fast way to only get the terminal path component of a Node.
- fname = fn.get_path(fn.dir)
- self.fs.BuildDir(build_dir, src_dir, duplicate)
- files = [os.path.join(str(build_dir), fname)]
-
- return (files, exports)
-
- #
- # Public methods of an SConsEnvironment. These get
- # entry points in the global name space so they can be called
- # as global functions.
- #
-
- def EnsureSConsVersion(self, major, minor):
- """Exit abnormally if the SCons version is not late enough."""
- if not self._check_version(major,minor,SCons.__version__):
- print "SCons %d.%d or greater required, but you have SCons %s" %(major,minor,SCons.__version__)
- sys.exit(2)
-
- def EnsurePythonVersion(self, major, minor):
- """Exit abnormally if the Python version is not late enough."""
- if not self._check_version(major,minor,sys.version):
- v = string.split(sys.version, " ", 1)[0]
- print "Python %d.%d or greater required, but you have Python %s" %(major,minor,v)
- sys.exit(2)
-
- def Exit(self, value=0):
- sys.exit(value)
-
- def Export(self, *vars):
+def Import(*vars):
+ try:
for var in vars:
- global_exports.update(compute_exports(self.Split(var)))
-
- def GetLaunchDir(self):
- global launch_dir
- return launch_dir
-
- def GetOption(self, name):
- name = self.subst(name)
- return SCons.Script.ssoptions.get(name)
-
- def Help(self, text):
- text = self.subst(text, raw=1)
- HelpFunction(text)
-
- def Import(self, *vars):
- try:
- for var in vars:
- var = self.Split(var)
- for v in var:
- if v == '*':
- stack[-1].globals.update(global_exports)
- stack[-1].globals.update(stack[-1].exports)
+ var = SCons.Util.Split(var)
+ for v in var:
+ if v == '*':
+ stack[-1].globals.update(global_exports)
+ stack[-1].globals.update(stack[-1].exports)
+ else:
+ if stack[-1].exports.has_key(v):
+ stack[-1].globals[v] = stack[-1].exports[v]
else:
- if stack[-1].exports.has_key(v):
- stack[-1].globals[v] = stack[-1].exports[v]
- else:
- stack[-1].globals[v] = global_exports[v]
- except KeyError,x:
- raise SCons.Errors.UserError, "Import of non-existant variable '%s'"%x
+ stack[-1].globals[v] = global_exports[v]
+ except KeyError,x:
+ raise SCons.Errors.UserError, "Import of non-existant variable '%s'"%x
- def SConscript(self, *ls, **kw):
- ls = map(lambda l, self=self: self.subst(l), ls)
- subst_kw = {}
- for key, val in kw.items():
- if SCons.Util.is_String(val):
- val = self.subst(val)
- subst_kw[key] = val
-
- files, exports = self._get_SConscript_filenames(ls, subst_kw)
-
- return apply(_SConscript, [self.fs,] + files, {'exports' : exports})
-
- def SConscriptChdir(self, flag):
- global sconscript_chdir
- sconscript_chdir = flag
-
- def SetOption(self, name, value):
- name = self.subst(name)
- SCons.Script.ssoptions.set(name, value)
-
-#
-#
-#
-SCons.Environment.Environment = SConsEnvironment
-
-def Options(files=None, args=arguments):
- return SCons.Options.Options(files, args)
+def GetLaunchDir():
+ return launch_dir
def SetBuildSignatureType(type):
SCons.Warnings.warn(SCons.Warnings.DeprecatedWarning,
"The SetBuildSignatureType() function has been deprecated;\n" +\
"\tuse the TargetSignatures() function instead.")
- SCons.Defaults.DefaultEnvironment().TargetSignatures(type)
+ TargetSignatures(type)
+
+def TargetSignatures(type):
+ import SCons.Sig
+ if type == 'build':
+ SCons.Sig.build_signature = 1
+ elif type == 'content':
+ SCons.Sig.build_signature = 0
+ else:
+ raise SCons.Errors.UserError, "Unknown build signature type '%s'"%type
def SetContentSignatureType(type):
SCons.Warnings.warn(SCons.Warnings.DeprecatedWarning,
"The SetContentSignatureType() function has been deprecated;\n" +\
"\tuse the SourceSignatures() function instead.")
- SCons.Defaults.DefaultEnvironment().SourceSignatures(type)
+ SourceSignatures(type)
+
+def SourceSignatures(type):
+ if type == 'MD5':
+ import SCons.Sig.MD5
+ SCons.Script.sig_module = SCons.Sig.MD5
+ elif type == 'timestamp':
+ import SCons.Sig.TimeStamp
+ SCons.Script.sig_module = SCons.Sig.TimeStamp
+ else:
+ raise SCons.Errors.UserError, "Unknown content signature type '%s'"%type
+
+
+class Options(SCons.Options.Options):
+ def __init__(self, files=None, args=arguments):
+ SCons.Options.Options.__init__(self, files, args)
+
+def CheckVersion(major, minor, version_string):
+ """Return 0 if 'major' and 'minor' are greater than the version
+ in 'version_string', and 1 otherwise."""
+ try:
+ v_major, v_minor, v_micro, release, serial = sys.version_info
+ except AttributeError:
+ version = string.split(string.split(version_string, ' ')[0], '.')
+ v_major = int(version[0])
+ v_minor = int(re.match('\d+', version[1]).group())
+ if major > v_major or (major == v_major and minor > v_minor):
+ return 0
+ else:
+ return 1
+
+def EnsureSConsVersion(major, minor):
+ """Exit abnormally if the SCons version is not late enough."""
+ if not CheckVersion(major,minor,SCons.__version__):
+ print "SCons %d.%d or greater required, but you have SCons %s" %(major,minor,SCons.__version__)
+ sys.exit(2)
+
+def EnsurePythonVersion(major, minor):
+ """Exit abnormally if the Python version is not late enough."""
+ if not CheckVersion(major,minor,sys.version):
+ v = string.split(sys.version, " ", 1)[0]
+ print "Python %d.%d or greater required, but you have Python %s" %(major,minor,v)
+ sys.exit(2)
def GetJobs():
SCons.Warnings.warn(SCons.Warnings.DeprecatedWarning,
"The SetJobs() function has been deprecated;\n" +\
"\tuse SetOption('num_jobs', num) instead.")
SetOption('num_jobs', num)
-
-def ParseConfig(env, command, function=None):
- SCons.Warnings.warn(SCons.Warnings.DeprecatedWarning,
- "The ParseConfig() function has been deprecated;\n" +\
- "\tuse the env.ParseConfig() method instead.")
- return env.ParseConfig(command, function)
-#
-_DefaultEnvironmentProxy = None
-
-def get_DefaultEnvironmentProxy():
- global _DefaultEnvironmentProxy
- if not _DefaultEnvironmentProxy:
- class EnvironmentProxy(SCons.Environment.Environment):
- """A proxy subclass for an environment instance that overrides
- the subst() and subst_list() methods so they don't actually
- actually perform construction variable substitution. This is
- specifically intended to be the shim layer in between global
- function calls (which don't want want construction variable
- substitution) and the DefaultEnvironment() (which would
- substitute variables if left to its own devices)."""
- def __init__(self, subject):
- self.__dict__['__subject'] = subject
- def __getattr__(self, name):
- return getattr(self.__dict__['__subject'], name)
- def __setattr__(self, name, value):
- return setattr(self.__dict__['__subject'], name, value)
- def subst(self, string, raw=0, target=None, source=None):
- return string
- def subst_kw(self, kw, raw=0, target=None, source=None):
- return kw
- def subst_list(self, string, raw=0, target=None, source=None):
- return string
- default_env = SCons.Defaults.DefaultEnvironment()
- _DefaultEnvironmentProxy = EnvironmentProxy(default_env)
- return _DefaultEnvironmentProxy
-
-class DefaultEnvironmentCall:
- """A class that implements "global function" calls of
- Environment methods by fetching the specified method from the
- DefaultEnvironment's class. Note that this uses an intermediate
- proxy class instead of calling the DefaultEnvironment method
- directly so that the proxy can override the subst() method and
- thereby prevent expansion of construction variables (since from
- the user's point of view this was called as a global function,
- with no associated construction environment)."""
- def __init__(self, method_name):
- self.method_name = method_name
- def __call__(self, *args, **kw):
- proxy = get_DefaultEnvironmentProxy()
- method = getattr(proxy, self.method_name)
- return apply(method, args, kw)
-
-# The list of global functions to add to the SConscript name space
-# that end up calling corresponding methods or Builders in the
-# DefaultEnvironment().
-GlobalDefaultEnvironmentFunctions = [
- # Methods from the SConsEnvironment class, above.
- 'EnsurePythonVersion',
- 'EnsureSConsVersion',
- 'Exit',
- 'Export',
- 'GetLaunchDir',
- 'GetOption',
- 'Help',
- 'Import',
- 'SConscript',
- 'SConscriptChdir',
- 'SetOption',
-
- # Methods from the Environment.Base class.
- 'Action',
- 'AddPostAction',
- 'AddPreAction',
- 'Alias',
- 'AlwaysBuild',
- 'BuildDir',
- 'Builder',
- 'CacheDir',
- 'Clean',
- 'Command',
- 'Default',
- 'Depends',
- 'Dir',
- 'Environment',
- 'File',
- 'FindFile',
- 'GetBuildPath',
- 'Ignore',
- 'Install',
- 'InstallAs',
- 'Literal',
- 'Local',
- 'Precious',
- 'Repository',
- 'Scanner',
- 'SConsignFile',
- 'SideEffect',
- 'SourceCode',
- 'SourceSignatures',
- 'Split',
- 'TargetSignatures',
- 'Value',
-]
-
-GlobalDefaultBuilders = [
- # Supported builders.
- 'CFile',
- 'CXXFile',
- 'DVI',
- 'Jar',
- 'Java',
- 'JavaH',
- 'Library',
- 'M4',
- 'MSVSProject',
- 'Object',
- 'PCH',
- 'PDF',
- 'PostScript',
- 'Program',
- 'RES',
- 'RMIC',
- 'SharedLibrary',
- 'SharedObject',
- 'StaticLibrary',
- 'StaticObject',
- 'Tar',
- 'TypeLibrary',
- 'Zip',
-]
-
-for name in GlobalDefaultEnvironmentFunctions + GlobalDefaultBuilders:
- GlobalDict[name] = DefaultEnvironmentCall(name)
+def Clean(target, files):
+ if not isinstance(target, SCons.Node.Node):
+ target = SCons.Node.FS.default_fs.Entry(target, create=1)
+
+ if not SCons.Util.is_List(files):
+ files = [files]
+
+ nodes = []
+ for f in files:
+ if isinstance(f, SCons.Node.Node):
+ nodes.append(f)
+ else:
+ nodes.extend(SCons.Node.arg2nodes(f, SCons.Node.FS.default_fs.Entry))
+
+ try:
+ clean_targets[target].extend(nodes)
+ except KeyError:
+ clean_targets[target] = nodes
+
+def AddPreAction(files, action):
+ nodes = SCons.Node.arg2nodes(files, SCons.Node.FS.default_fs.Entry)
+ for n in nodes:
+ n.add_pre_action(SCons.Action.Action(action))
+
+def AddPostAction(files, action):
+ nodes = SCons.Node.arg2nodes(files, SCons.Node.FS.default_fs.Entry)
+ for n in nodes:
+ n.add_post_action(SCons.Action.Action(action))
+
+def Exit(value=0):
+ sys.exit(value)
+
+
+def Alias(name):
+ alias = SCons.Node.Alias.default_ans.lookup(name)
+ if alias is None:
+ alias = SCons.Node.Alias.default_ans.Alias(name)
+ return alias
+
+def SetOption(name, value):
+ SCons.Script.ssoptions.set(name, value)
+
+def GetOption(name):
+ return SCons.Script.ssoptions.get(name)
+
+def SConsignFile(name=".sconsign.dbm"):
+ import SCons.Sig
+ if not os.path.isabs(name):
+ sd = str(SCons.Node.FS.default_fs.SConstruct_dir)
+ name = os.path.join(sd, name)
+ SCons.Sig.SConsignFile(name)
def BuildDefaultGlobals():
"""
"""
globals = {}
+ globals['Action'] = SCons.Action.Action
+ globals['AddPostAction'] = AddPostAction
+ globals['AddPreAction'] = AddPreAction
+ globals['Alias'] = Alias
globals['ARGUMENTS'] = arguments
+ globals['BuildDir'] = BuildDir
+ globals['Builder'] = SCons.Builder.Builder
+ globals['CacheDir'] = SCons.Node.FS.default_fs.CacheDir
+ globals['Clean'] = Clean
globals['Configure'] = SCons.SConf.SConf
- globals['Options'] = Options
- globals['Platform'] = SCons.Platform.Platform
- globals['Return'] = Return
- globals['Tool'] = SCons.Tool.Tool
- globals['WhereIs'] = SCons.Util.WhereIs
-
- # Functions we're in the process of converting to Environment methods.
globals['CScan'] = SCons.Defaults.CScan
+ globals['Default'] = Default
globals['DefaultEnvironment'] = SCons.Defaults.DefaultEnvironment
-
- # Deprecated functions, leave these here for now.
+ globals['Dir'] = SCons.Node.FS.default_fs.Dir
+ globals['EnsurePythonVersion'] = EnsurePythonVersion
+ globals['EnsureSConsVersion'] = EnsureSConsVersion
+ globals['Environment'] = SCons.Environment.Environment
+ globals['Exit'] = Exit
+ globals['Export'] = Export
+ globals['File'] = SCons.Node.FS.default_fs.File
+ globals['FindFile'] = FindFile
+ globals['GetBuildPath'] = GetBuildPath
+ globals['GetCommandHandler'] = SCons.Action.GetCommandHandler
globals['GetJobs'] = GetJobs
- globals['ParseConfig'] = ParseConfig
+ globals['GetLaunchDir'] = GetLaunchDir
+ globals['GetOption'] = GetOption
+ globals['Help'] = Help
+ globals['Import'] = Import
+ globals['Literal'] = SCons.Util.Literal
+ globals['Local'] = Local
+ globals['Options'] = Options
+ globals['ParseConfig'] = SCons.Util.ParseConfig
+ globals['Platform'] = SCons.Platform.Platform
+ globals['Repository'] = SCons.Node.FS.default_fs.Repository
+ globals['Return'] = Return
+ globals['SConscript'] = SConscript
+ globals['SConscriptChdir'] = SConscriptChdir
+ globals['SConsignFile'] = SConsignFile
+ globals['Scanner'] = SCons.Scanner.Base
globals['SetBuildSignatureType'] = SetBuildSignatureType
+ globals['SetCommandHandler'] = SCons.Action.SetCommandHandler
globals['SetContentSignatureType'] = SetContentSignatureType
globals['SetJobs'] = SetJobs
-
- globals.update(GlobalDict)
-
+ globals['SetOption'] = SetOption
+ globals['SourceSignatures'] = SourceSignatures
+ globals['Split'] = SCons.Util.Split
+ globals['TargetSignatures'] = TargetSignatures
+ globals['Tool'] = SCons.Tool.Tool
+ globals['Value'] = SCons.Node.Python.Value
+ globals['WhereIs'] = SCons.Util.WhereIs
return globals
projects / scons.git / commitdiff