-.\" 1. Builder's __call__ method can now take arbitrary keyword arguments.
-.\" These args are saved with the target node of the build, then passed along
.\" Copyright (c) 2001, 2002 Steven Knight
.\"
.\" Permission is hereby granted, free of charge, to any person obtaining
.RS
.nf
..
-.\" EE - Example End - ends intend and turns line fill back on
+.\" EE - Example End - ends indent and turns line fill back on
.de EE
.RE
.fi
..
-.TH SCONS 1 "July 2002"
+.TH SCONS 1 "November 2002"
.SH NAME
scons \- a software construction tool
.SH SYNOPSIS
or
.I sconstruct
(in that order) in the current directory and reads its
-configuration from the first file found. An alternate file name may be
+configuration from the first file found.
+An alternate file name may be
specified via the
.B -f
option. If the specified file is not
will internally change its working
directory (chdir) to the directory containing the file.
-The configuration file specifies the files to be built, and
-(optionally) the rules to build those files. Reasonable default
+The
+.I SConstruct
+file can specify subsidiary
+configuration files using the
+.B SConscript()
+function.
+By convention,
+these subsidiary files are named
+.IR SConscript ,
+although any name may be used.
+(Because of this naming convention,
+the term "SConscript files"
+is sometimes used to refer
+generically to all
+.B scons
+configuration files,
+regardless of actual file name.)
+
+The configuration files
+specify the target files to be built, and
+(optionally) the rules to build those targets. Reasonable default
rules exist for building common software components (executable
-programs, object files, libraries), so that for simple software
+programs, object files, libraries), so that for most software
projects, only the target and input files need be specified.
+.B scons
+reads and executes the SConscript files as Python scripts,
+so you may use normal Python scripting capabilities
+(such as flow control, data manipulation, and imported Python libraries)
+to handle complicated build situations.
+.BR scons ,
+however, reads all of the SConscript files
+.I before
+it begins building any targets.
+To make this obvious,
+.B scons
+prints the following messages about what it is doing:
+
+.ES
+$ scons foo.out
+scons: Reading SConscript files ...
+scons: done reading SConscript files.
+scons: Building targets ...
+cp foo.in foo.out
+scons: done building targets.
+$
+.EE
+
+These status messages may be suppressed using the
+.B -Q
+option.
+
.B scons
can scan known input files automatically for dependency
information (for example, #include statements
Targets may be omitted from the command line,
in which case the targets specified
-in the configuration file(s) as
+in the SConscript file(s) as
.B Default
targets will be built:
scons
.EE
-Specifying "cleanup" targets in configuration files is not
+Specifying "cleanup" targets in SConscript files is not
necessary. The
.B -c
flag removes all files
.EE
to remove target files under build and export.
+Additional files or directories to remove can be specified using the
+Clean() function.
A subset of a hierarchical tree may be built by
remaining at the top-level directory (where the
builds four targets in parallel, for example.
-Values of variables to be passed to the configuration file(s)
+Values of variables to be passed to the SConscript file(s)
may be specified on the command line:
.ES
These variables are available in SConscript files
through the ARGUMENTS dictionary,
-and can be used in the configuration file(s) to modify
+and can be used in the SConscript file(s) to modify
the build in any way:
.ES
.\" .B scons
.\" can maintain a cache of target (derived) files that can
.\" be shared between multiple builds. When caching is enabled in a
-.\" configuration file, any target files built by
+.\" SConscript file, any target files built by
.\" .B scons
.\" will be copied
.\" to the cache. If an up-to-date target file is found in the cache, it
-c, --clean, --remove
Clean up by removing all target files for which a construction
command is specified.
+Also remove any files or directories associated to the construction command
+using the Clean() function.
.\" .TP
.\" --cache-disable, --no-cache
.\" Disable caching. Will neither retrieve files from cache nor flush
.\" files to cache. Has no effect if use of caching is not specified
-.\" in a configuration file.
+.\" in an SConscript file.
.\"
.\" .TP
.\" --cache-force, --cache-populate
executing build commands, the total time spent executing SConstruct and
SConscript files, and the total time spent executing SCons itself.
+.TP
+.RI --debug=includes
+Print the include tree after each top-level target is built.
+This is generally used to find out what files are included by the sources
+of a given derived file:
+
+.ES
+$ scons --debug=includes foo.o
+.EE
+
.TP
-e, --environment-overrides
Variables from the execution environment override construction
-variables from the configuration files.
+variables from the SConscript files.
.TP
.RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
Use
.I file
-as the initial configuration
-file. If
+as the initial SConscript file.
+If
.I file
is in another directory,
.B scons
.TP
-h, --help
Print a local help message for this build, if one is defined in
-the configuration file(s), plus a line that describes the
+the SConscript file(s), plus a line that describes the
.B -H
option for command-line option help. If no local help message
is defined, prints the standard help message about command-line
.\" -p
.\" Print the data base (construction environments,
.\" Builder and Scanner objects) that are defined
-.\" after reading the configuration files.
+.\" after reading the SConscript files.
.\" After printing, a normal build is performed
.\" as usual, as specified by other command-line options.
.\" This also prints version information
Do not run any commands, or print anything. Just return an exit
status that is zero if the specified targets are already up to
date, non-zero otherwise.
+.TP
+-Q
+Quiets SCons status messages about
+reading SConscript files,
+building targets
+and entering directories.
+Commands that are executed
+to rebuild target files are still printed.
.\" .TP
.\" -r, -R, --no-builtin-rules, --no-builtin-variables
-s, --silent, --quiet
Silent. Do not print commands that are executed to rebuild
target files.
+Also suppresses SCons status messages.
.TP
-S, --no-keep-going, --stop
.\" .SS Python Basics
.\" XXX Adding this in the future would be a help.
.SS Construction Environments
-A construction environment is the basic means by which the configuration
+A construction environment is the basic means by which the SConscript
files communicate build information to
.BR scons .
A new construction environment is created using the
latex
lex
masm
+mingw
+mslib
mslink
msvc
nasm
yacc
.EE
-On posix and cygwin platforms the GNU tools (e.g. gcc) are preferred by SCons,
-on win32 the Microsoft tools (e.g. msvc) are preferred by SCons, and in OS/2 the IBM
-tools (e.g. icc) are preferred by SCons.
+On posix and cygwin platforms
+the GNU tools (e.g. gcc) are preferred by SCons,
+on win32 the Microsoft tools (e.g. msvc)
+followed by MinGW are preferred by SCons,
+and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
.SS Builder Methods
env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
.EE
+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.
+A
+.I Node
+is an internal SCons object
+which represents
+build targets or sources.
+
+The returned Node(s)
+can be passed to other builder methods as source(s)
+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
+.B -D
+flag when compiling one specific object file:
+
+.ES
+bar_obj = env.StaticObject('bar.c', CCFLAGS='-DBAR')
+env.Program(source = ['foo.c', bar_obj, 'main.c'])
+.EE
+
+Using a Node in this way
+makes for a more portable build
+by avoiding having to specify
+a platform-specific object suffix
+when calling the Program() builder.
+
+The path name for a Node's file may be used
+by passing the Node to the Python-builtin
+.B str()
+function:
+
+.ES
+bar_obj = env.StaticObject('bar.c', CCFLAGS='-DBAR')
+print "The path to bar_obj is:", str(bar_obj)
+.EE
+
.B scons
provides the following builders:
.B StaticObject
builder.
+.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
+env['PCH'] = env.PCH('StdAfx.cpp')[0]
+.EE
+
.IP Program
Builds an executable given one or more object files or C, C++
or Fortran source files.
env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
.EE
+.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.RES('resource.rc')
+.EE
+
.IP StaticLibrary
Builds a static library given one or more object files
or C, C++ or Fortran source files.
(upper case) files
as C files.
+.IP _concat
+A function used to produce variables like $_CPPINCFLAGS. It takes six
+arguments: a prefix to concatenate onto each element, a list of elements, a
+suffix to concatenate onto each element, a dictionary of global variables
+for variable interpolation, a list of local variables for variable
+interpolation, and an optional function that will be called to transform the list
+before concatenation.
+
+.ES
+env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, locals(), globals(), RDirs)} $)',
+.EE
+
+
.IP CPPFLAGS
C preprocessor options.
These will be included in any command that uses the C preprocessor,
.IP CXXFLAGS
General options that are passed to the C++ compiler.
+.IP Dir
+A function that converts a file name into a Dir instance relative to the
+target being built.
+
.IP DVIPDF
The TeX DVI file to PDF file converter.
env = Environment(ENV = {'PATH' : os.environ['PATH']})
.EE
+.IP ESCAPE
+A function that will be called to escape shell special characters in
+command lines. The function should take one argument: the command line
+string to escape; and should return the escaped command line.
+
.IP F77
The Fortran compiler.
Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
are included on this command line.
+.IP File
+A function that converts a file name into a File instance relative to the
+target being built.
+
.IP INCPREFIX
The prefix used to specify an include directory on the C compiler command
line.
.IP OBJSUFFIX
The suffix used for (static) object file names.
+.IP PCH
+The Microsoft Visual C++ precompiled header that will be used when compiling
+object files. This variable is ignored by tools other than Microsoft Visual C++.
+When this variable is
+defined SCons will add options to the compiler command line to
+cause it to use the precompiled header, and will also set up the
+dependencies for the PCH file. Example:
+
+.ES
+env['PCH'] = 'StdAfx.pch'
+.EE
+
+.IP PCHSTOP
+This variable specifies how much of a source file is precompiled. This
+variable is ignored by tools other than Microsoft Visual C++, or when
+the PCH variable is not being used. When this variable is define it
+must be a string that is the name of the header that
+is included at the end of the precompiled portion of the source files, or
+the empty string if the "#pragma hrdstop" construct is being used:
+
+.ES
+env['PCHSTOP'] = 'StdAfx.h'
+.EE
+
+.IP PDB
+The Microsoft Visual C++ PDB file that will store debugging information for
+object files, shared libraries, and programs. This variable is ignored by
+tools other than Microsoft Visual C++.
+When this variable is
+defined SCons will add options to the compiler and linker command line to
+cause them to generate external debugging information, and will also set up the
+dependencies for the PDB file. Example:
+
+.ES
+env['PDB'] = 'hello.pdb'
+.EE
+
.IP PDFCOM
The command line used to convert TeX DVI files into a PDF file.
.IP RANLIBFLAGS
General options passed to the archive indexer.
+.IP RC
+The resource compiler used by the RES builder.
+
+.IP RCCOM
+The command line used by the RES builder.
+
+.IP RCFLAGS
+The flags passed to the resource compiler by the RES builder.
+
+.IP RDirs
+A function that converts a file name into a list of Dir instances by
+searching the repositories.
+
.IP SCANNERS
A list of the available implicit dependency scanners. [CScan] by default.
Options that are passed to the C++ compiler
to generate shared-library objects.
+.IP SHELL
+A string naming the shell program that will be passed to the
+.I SPAWN
+function.
+See the
+.I SPAWN
+construction variable for more information.
+
.IP SHF77
The Fortran compiler used for generating shared-library objects.
.IP SHOBJSUFFIX
The suffix used for shared object file names.
+.IP SPAWN
+A command interpreter function that will be called to execute command line
+strings. The function must expect 4 arguments:
+
+.ES
+def spawn(shell, escape, cmd, args, env):
+.EE
+.IP
+.I sh
+is a string naming the shell program to use.
+.I escape
+is a function that can be called to escape shell special characters in
+the command line.
+.I cmd
+is the path to the command to be executed.
+.I args
+is that arguments to the command.
+.I env
+is a dictionary of the environment variables
+in which the command should be executed.
+
.IP TAR
The tar archiver.
The default is 0 (do not build a .def file).
.IP WIN32DEFPREFIX
-The prefix used to build WIN32 .def files.
+The prefix used for WIN32 .def file names.
.IP WIN32DEFSUFFIX
The suffix used for WIN32 .def file names.
-.IP WIN32DLLPREFIX
-The prefix used to build WIN32 shared libraries (.dll files).
-
-.IP WIN32IMPLIBPREFIX
-The prefix used to build WIN32 import libraries.
-
.IP YACC
The parser generator.
compiler.
.B scons
provides a mechanism for overridding construction variables from the
-command line or a text based configuration file through an Options
+command line or a text-based SConscript file through an Options
object. To create an Options object, call the Options() function:
.TP
Help(opts.GenerateHelpText(env))
.EE
-The text based configuration file is executed as a Python script, and the
+The text based SConscript file is executed as a Python script, and the
global variables are queried for customizable construction
variables. Example:
.B scons
also provides various additional functions,
not associated with a construction environment,
-that configuration files can use:
+that SConscript files can use:
.TP
.RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
is usually safe, and is always more efficient than
.IR duplicate =1.
+.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. Default targets will be built by
+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.
-In this version of SCons (0.07),
-.BR Default ()
-will also accept a space-delimited string of target file names;
-this functionality will be removed in the next version of SCons (0.08).
-Target names with white space may be be enclosed in an
-array to prevent the string from being split into
-separate file names.
+method or as a list.
.BR Default ()
will also accept the return value of any of the construction environment
builder methods.
-Example:
+Examples:
.ES
-Default('foo', 'bar', 'baz', ['file with whitespace'])
+Default('foo', 'bar', 'baz')
+Default(['a', 'b', 'c'])
+Default(env.Program('hello', 'hello.c'))
.EE
.TP
is an optional directory that will be used as the parent directory.
.TP
-.RI FindFile( file ", "
+.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 Export( vars )
This tells
.B scons
to export a list of variables from the current
-configuration file to all other configuration files. The exported variables
+SConscript file to all other SConscript files. The exported variables
are kept in a global collection, so subsequent exports
will over-write previous exports that have the same name.
Multiple variable names should be passed to
.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 GetJobs()
+Get the number of jobs (commands) that will be run simultaneously. See also
+.I -j
+and
+.IR SetJobs() .
+
.TP
.RI Help( text )
This specifies help text to be printed if the
.RI Import( vars )
This tells
.B scons
-to import a list of variables into the current configuration file. This
+to import a list of variables into the current SConscript file. This
will import variables that were exported with
.BR Export ()
or in the
Import("env", "variable")
.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
env = Environment(platform = Platform('win32'))
.EE
+.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 configuration
-file. These variables will be returned to the "calling" configuration file
+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
.B scons
to execute
.I script
-as a configuration file. The optional
+as a SConscript (configuration) file. The optional
.I exports
argument provides a list of variable names to export to
.IR script ". "
.B scons
to change its working directory (chdir)
to the directory in which each subsidiary
-configure (SConscript) file lives.
+SConscript file lives.
Note that you may enable and disable
this ability by calling
SConscriptChdir()
.EE
.TP
-.RI SetCommandHandler( function )
+.RI SetBuildSignatureType( type )
-This registers a user
-.I function
-as the handler
-for interpreting and executing command-line strings.
-The function must expect three arguments:
+This function tells SCons what type of build signature to use: "build" or
+"content". "build" means to concatenate the signatures of all source files
+of a derived file to make its signature, and "content" means to use
+the derived files content signature as its signature. "build" signatures
+are usually faster to compute, but "content" signatures can prevent
+redundant rebuilds. The default is "build".
-.ES
-def commandhandler(cmd, args, env):
-.EE
-.IP
-.I cmd
-is the path to the command to be executed.
-.I args
-is that arguments to the command.
-.I env
-is a dictionary of the environment variables
-in which the command should be executed.
+.TP
+.RI SetContentSignatureType( type )
+
+This function tells SCons what type of content signature to use: "MD5" or
+"timestamp". "MD5" means to use the MD5 checksum of a files contents as
+its signature, and "timestamp" means to use a files timestamp as its
+signature. When using "timestamp" signatures, changes in the
+command line will not cause files to be rebuilt. "MD5" signatures take
+longer to compute, but "timestamp" signatures are less accurate. The
+default is "MD5".
+
+.TP
+.RI SetJobs( num )
+Specifies the number of jobs (commands) to run simultaneously.
+.I -j
+overrides this function. See also
+.I -j
+and
+.IR GetJobs() .
.TP
.RI Split( arg )
rather than let each separate Builder object
create a separate Action.
-The Action method takes a single argument
+The Action method takes one or two arguments
and returns an appropriate object for the action
-represented by the type of the argument:
+represented by the type of the first argument:
.IP Action
-If the argument is already an Action object,
+If the first argument is already an Action object,
the object is simply returned.
.IP String
-If the argument is a string,
+If the first argument is a string,
a command-line Action is returned.
.ES
.IP List
-If the argument is a list,
+If the first argument is a list,
then a list of Action objects is returned.
An Action object is created as necessary
for each element in the list.
.EE
.IP Function
-If the argument is a Python function,
+If the first argument is a Python function,
a function Action is returned.
The Python function takes three keyword arguments,
.B target
a = Action(build_it)
.EE
+
+The second, optional argument
+is a Python function that returns
+a string to be printed describing the action being executed.
+This function takes two arguments,
+an array of targets to be created by the function action,
+and an array of sources used to create the target(s):
+
+def build_it(target, source, env):
+ # build the target from the source
+ return 0
+
+def string_it(target, source):
+ return "building '%s' from '%s'" % (target[0], source[0])
+
+a = Action(build_it, string_it)
.PP
If the action argument is not one of the above,
None is returned.
new file types for implicit dependencies.
Scanner accepts the following arguments:
-.IP name
-The name of the Scanner.
-This is mainly used
-to identify the Scanner internally.
-
-.IP argument
-An optional argument that, if specified,
-will be passed to the scanner function.
-
-.IP skeys
-An optional list that can be used to
-determine which scanner should be used for
-a given Node.
-In the usual case of scanning for file names,
-this array can be a list of suffixes
-for the different file types that this
-Scanner knows how to scan.
-
.IP function
A Python function that will process
the Node (file)
dependencies found in the contents.
The function takes three or four arguments:
- def scanner_function(node, env, target):
+ def scanner_function(node, env, path):
- def scanner_function(node, env, target, arg):
+ def scanner_function(node, env, path, arg):
The
.B node
method.
The
-.B target
-argument is the internal
-SCons node representing the target file.
+.B path
+argument is a tuple (or list)
+of directories that can be searched
+for files.
+This will usually be the tuple returned by the
+.B path_function
+argument (see below).
The
.B arg
argument is the argument supplied
when the scanner was created, if any.
+.IP name
+The name of the Scanner.
+This is mainly used
+to identify the Scanner internally.
+
+.IP argument
+An optional argument that, if specified,
+will be passed to the scanner function
+(described above)
+and the path function
+(specified below).
+
+.IP skeys
+An optional list that can be used to
+determine which scanner should be used for
+a given Node.
+In the usual case of scanning for file names,
+this array will be a list of suffixes
+for the different file types that this
+Scanner knows how to scan.
+
+.IP path_function
+A Python function that takes
+two or three arguments:
+a construction environment, directory Node,
+and optional argument supplied
+when the scanner was created.
+The
+.B path_function
+returns a tuple of directories
+that can be searched for files to be returned
+by this Scanner object.
+
+.IP node_class
+The class of Node that should be returned
+by this Scanner object.
+Any strings or other objects returned
+by the scanner function
+that are not of this class
+will be run through the
+.B node_factory
+function.
+
+.IP node_factory
+A Python function that will take a string
+or other object
+and turn it into the appropriate class of Node
+to be returned by this Scanner object.
+
.IP scan_check
An optional Python function that takes a Node (file)
as an argument and returns whether the
for example, the underlying file
represented by a Node does not yet exist.
+.IP recursive
+An optional flag that
+specifies whether this scanner should be re-invoked
+on the dependency files returned by the scanner.
+When this flag is not set,
+the Node subsystem will
+only invoke the scanner on the file being scanned,
+and not (for example) also on the files
+specified by the #include lines
+in the file being scanned.
+
.SH SYSTEM-SPECIFIC BEHAVIOR
SCons and its configuration files are very portable,
due largely to its implementation in Python.
script named
.B scons .
+.SS MinGW
+
+The MinGW bin directory must be in your PATH environment variable or the
+PATH variable under the ENV construction variable for SCons
+to detect and use the MinGW tools. When running under the native Windows
+Python interpreter, SCons will prefer the MinGW tools over the Cygwin
+tools, if they are both installed, regardless of the order of the bin
+directories in the PATH variable. If you have both MSVC and MinGW
+installed and you want to use MinGW instead of MSVC,
+then you must explictly tell SCons to use MinGW by passing
+
+.ES
+tools=['mingw']
+.EE
+
+to the Environment() function, because SCons will prefer the MSVC tools
+over the MinGW tools.
+
.SH EXAMPLES
To help you get started using SCons,
include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
-def kfile_scan(node, env, target, arg):
+def kfile_scan(node, env, path, arg):
contents = node.get_contents()
includes = include_re.findall(contents)
return includes
bar_in = File('bar.in')
env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
-bar_in.scanner_set(kscan)
+bar_in.target_scanner = kscan
.EE
.SS Creating a Hierarchical Build
or get documentation on the options:
.ES
-> scons -h
+$ scons -h
CC: The C compiler.
default: None
.EE
+.SS Using Microsoft Visual C++ precompiled headers
+
+Since windows.h includes everything and the kitchen sink, it can take quite
+some time to compile it over and over again for a bunch of object files, so
+Microsoft provides a mechanism to compile a set of headers once and then
+include the previously compiled headers in any object file. This
+technology is called precompiled headers. The general recipe is to create a
+file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
+then include every header you want to precompile in "StdAfx.h", and finally
+include "StdAfx.h" as the first header in all the source files you are
+compiling to object files. For example:
+
+StdAfx.h:
+.ES
+#include <windows.h>
+#include <my_big_header.h>
+.EE
+
+StdAfx.cpp:
+.ES
+#include <StdAfx.h>
+.EE
+
+Foo.cpp:
+.ES
+#include <StdAfx.h>
+
+/* do some stuff */
+.EE
+
+Bar.cpp:
+.ES
+#include <StdAfx.h>
+
+/* do some other stuff */
+.EE
+
+SConstruct:
+.ES
+env=Environment()
+env['PCHSTOP'] = StdAfx.h
+env['PCH'] = env.PCH('StdAfx.cpp')[0]
+env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
+.EE
+
+For more information see the document for the PCH builder, and the PCH and
+PCHSTOP construction variables. To learn about the details of precompiled
+headers consult the MSDN documention for /Yc, /Yu, and /Yp.
+
+.SS Using Microsoft Visual C++ external debugging information
+
+Since including debugging information in programs and shared libraries can
+cause their size to increase significantly, Microsoft provides a mechanism
+for including the debugging information in an external file called a PDB
+file. SCons supports PDB files through the PDB construction
+variable.
+
+SConstruct:
+.ES
+env=Environment()
+env['PDB'] = 'MyApp.pdb'
+env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
+.EE
+
+For more information see the document for the PDB construction variable.
+
.SH ENVIRONMENT
.IP SCONS_LIB_DIR
projects / scons.git / blobdiff