.RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
.TP
.RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
-Synonyms for
+Deprecated synonyms for
.BR VariantDir ()
and
.BR env.VariantDir ().
.BR VariantDir ()
or
.BR env.VariantDir ().
-(This will be officially deprecated some day.)
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
will be ignored when deciding if
the target file(s) need to be rebuilt.
+You can also use
+.BR Ignore()
+to remove a target from the default build.
+In order to do this you must specify the directory the target will
+be built in as the target, and the file you want to skip building
+as the dependency.
+
+Note that this will only remove the dependencies listed from
+the files built by default. It will still be built if that
+dependency is needed by another object being built.
+See the third and forth examples below.
+
Examples:
.ES
env.Ignore('foo', 'foo.c')
env.Ignore('bar', ['bar1.h', 'bar2.h'])
+env.Ignore('.','foobar.obj')
+env.Ignore('bar','bar/foobar.obj')
.EE
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
+.RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
+'\" .RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
.TP
-.RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
+.RI env.SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
+'\" .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
.TP
-.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
+.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
+'\" .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
.TP
-.RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
+.RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
+'\" .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
This tells
.B scons
to execute
one or more subsidiary SConscript (configuration) files.
+Any variables returned by a called script using
+.BR Return ()
+will be returned by the call to
+.BR SConscript ().
There are two ways to call the
.BR SConscript ()
function.
(either explicitly or as created by
a function like
.BR Split ()).
+Examples:
+.ES
+SConscript('SConscript') # run SConscript in the current directory
+SConscript('src/SConscript') # run SConscript in the src directory
+SConscript(['src/SConscript', 'doc/SConscript'])
+config = SConscript('MyConfig.py')
+.EE
The second way you can call
.BR SConscript ()
by supplying an optional
.RI name= script
keyword argument.
+The first three examples below have the same effect
+as the first three examples above:
+.ES
+SConscript(dirs='.') # run SConscript in the current directory
+SConscript(dirs='src') # run SConscript in the src directory
+SConscript(dirs=['src', 'doc'])
+SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
+.EE
The optional
.I exports
must use the
.BR Import ()
function to import the variables.
+Examples:
+.ES
+foo = SConscript('sub/SConscript', exports='env')
+SConscript('dir/SConscript', exports=['env', 'variable'])
+SConscript(dirs='subdir', exports='env variable')
+SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
+.EE
If the optional
.I variant_dir
-argument is present, it causes an effect equivalent to
-.BR VariantDir (
-.IR variant_dir ,
-.IR src_dir ,
-.IR duplicate )
-to be executed prior to reading the
-.IR script (s).
+argument is present, it causes an effect equivalent to the
+.BR VariantDir ()
+method described below.
(If
.I variant_dir
is not present, the
-.I src_dir
-and
+'\" .IR src_dir and
.I duplicate
-arguments are ignored.)
+'\" arguments are ignored.)
+argument is ignored.)
The
.I variant_dir
-and
-.I src_dir
-arguments are interpreted relative to the directory
-of the calling SConscript file.
-If
-.I src_dir
-is not specified, the directory of the calling SConscript file is assumed.
+'\" and
+'\" .I src_dir
+'\" arguments are interpreted relative to the directory of the calling
+argument is interpreted relative to the directory of the calling
+.BR SConscript file.
See the description of the
.BR VariantDir ()
function below for additional details and restrictions.
-Any variables returned by
-.I script
-using
-.BR Return ()
-will be returned by the call to
-.BR SConscript ().
+If
+'\" .IR variant_dir " is present, but"
+'\" .IR src_dir " is not,"
+.IR variant_dir " is present,"
+the source directory is relative to the called
+.BR SConscript " file."
+.ES
+SConscript('src/SConscript', variant_dir = 'build')
+.EE
+is equivalent to
+.ES
+VariantDir('build', 'src')
+SConscript('build/SConscript')
+.EE
+This later paradigm is often used when the sources are
+in the same directory as the
+.BR SConstruct file:
+.ES
+SConscript('SConscript', variant_dir = 'build')
+.EE
+is equivalent to
+.ES
+VariantDir('build', '.')
+SConscript('build/SConscript')
+.EE
-Examples:
+'\" If
+'\" .IR variant_dir " and"
+'\" .IR src_dir " are both present,"
+'\" xxxxx everything is in a state of confusion.
+'\" .ES
+'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.')
+'\" runs src/SConscript in build/src, but
+'\" SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src')
+'\" runs lib/SConscript (in lib!). However,
+'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src')
+'\" runs src/SConscript in build. Moreover,
+'\" SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src')
+'\" runs src/lib/SConscript in build/lib. Moreover,
+'\" SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src')
+'\" can't find build/src/lib/SConscript, even though it ought to exist.
+'\" .EE
+'\" is equivalent to
+'\" .ES
+'\" ????????????????
+'\" .EE
+'\" and what about this alternative?
+'\"TODO??? SConscript('build/SConscript', src_dir='src')
+
+Here are some composite examples:
.ES
-SConscript('subdir/SConscript')
-foo = SConscript('sub/SConscript', exports='env')
-SConscript('dir/SConscript', exports=['env', 'variable'])
-SConscript('dir/SConscript', exports='env variable')
-SConscript(dirs=['sub1', 'sub2'])
-SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
+# collect the configuration information and use it to build src and doc
+shared_info = SConscript('MyConfig.py')
+SConscript('src/SConscript', exports='shared_info')
+SConscript('doc/SConscript', exports='shared_info')
.EE
.ES
-SConscript('bld/SConscript', variant_dir='bld', duplicate=0)
+# build debugging and production versions. SConscript
+# can use Dir('.').path to determine variant.
+SConscript('SConscript', variant_dir='debug', duplicate=0)
+SConscript('SConscript', variant_dir='prod', duplicate=0)
.EE
-which is equivalent to
+
+.ES
+# build debugging and production versions. SConscript
+# is passed flags to use.
+opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
+SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
+opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
+SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
+.EE
+
.ES
-VariantDir('bld', '.', duplicate=0)
-SConscript('bld/SConscript')
+# build common documentation and compile for different architectures
+SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
+SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
+SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
.EE
-'\"TODO: SConscript('bld/SConscript', src_dir='src', exports='env variable')
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.IR src_dir ,
the file or directory is copied to
.IR variant_dir .
-Target files can be built in a different directory than the original sources
-by simply refering to the sources (and targets) within the variant tree.
+Target files can be built in a different directory
+than the original sources by simply refering to the sources (and targets)
+within the variant tree.
.BR VariantDir ()
can be called multiple times with the same
Duplicating the source tree may be disabled by setting the
.I duplicate
-argument to 0.
+argument to 0 (zero).
This will cause
.B scons
to invoke Builders using the path names of source files in
.EE
.ES
-# this variant builds both the source and docs
+# this builds both the source and docs in a separate subtree
VariantDir('build', '.', duplicate=0)
SConscript(dirs=['build/src','build/doc'])
.EE
-Or, equivalently:
-.ES
-SConscript(dirs=['build/src','build/doc'],
- variant_dir = 'build', duplicate = 0)
-.EE
.ES
-SConscript('build/SConscript', variant_dir = 'build', duplicate = 0)
+# same as previous example, but only uses SConscript
+SConscript(dirs='src', variant_dir='build/src', duplicate=0)
+SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
.EE
-Note that in the last example, the
-.I src_dir
-is not given, so the current directory is assumed, and the
-.B SConstruct
-and the
-.B SConscript
-are actually in the same directory, even though the
-.B SConscript
-is treated as if it were in the
-.B build
-subdirectory.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
instance has the following associated methods:
.TP
-.RI Configure.Finish( self )
+.RI SConf.Finish( context )
+.TP
+.IR sconf .Finish()
This method should be called after configuration is done.
It returns the environment as modified
by the configuration checks performed.
goes by and developers contribute new useful tests.)
.TP
-.RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
+.RI SConf.CheckHeader( context ", " header ", [" include_quotes ", " language ])
+.TP
+.IR sconf .CheckHeader( header ", [" include_quotes ", " language ])
Checks if
.I header
is usable in the specified language.
Returns 1 on success and 0 on failure.
.TP
-.RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
+.RI SConf.CheckCHeader( context ", " header ", [" include_quotes ])
+.TP
+.IR sconf .CheckCHeader( header ", [" include_quotes ])
This is a wrapper around
-.B Configure.CheckHeader
+.B SConf.CheckHeader
which checks if
.I header
is usable in the C language.
Returns 1 on success and 0 on failure.
.TP
-.RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
+.RI SConf.CheckCXXHeader( context ", " header ", [" include_quotes ])
+.TP
+.IR sconf .CheckCXXHeader( header ", [" include_quotes ])
This is a wrapper around
-.B Configure.CheckHeader
+.B SConf.CheckHeader
which checks if
.I header
is usable in the C++ language.
Returns 1 on success and 0 on failure.
.TP
-.RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
+.RI SConf.CheckFunc( context, ", " function_name ", [" header ", " language ])
+.TP
+.IR sconf .CheckFunc( function_name ", [" header ", " language ])
Checks if the specified
C or C++ function is available.
.I function_name
the default is "C".
.TP
-.RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
+.RI SConf.CheckLib( context ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
+.TP
+.IR sconf .CheckLib([ library ", " symbol ", " header ", " language ", " autoadd=1 ])
Checks if
.I library
provides
is not set or is
.BR None ,
then
-.BR Configure.CheckLib ()
+.BR SConf.CheckLib ()
just checks if
you can link against the specified
.IR library .
This method returns 1 on success and 0 on error.
.TP
-.RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
+.RI SConf.CheckLibWithHeader( context ", " library ", " header ", " language ", [" call ", " autoadd ])
+.TP
+.IR sconf .CheckLibWithHeader( library ", " header ", " language ", [" call ", " autoadd ])
In contrast to the
-.RI Configure.CheckLib
+.RI SConf.CheckLib
call, this call provides a more sophisticated way to check against libraries.
Again,
.I library
succeeds). This method returns 1 on success and 0 on error.
.TP
-.RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
+.RI SConf.CheckType( context ", " type_name ", [" includes ", " language ])
+.TP
+.IR sconf .CheckType( type_name ", [" includes ", " language ])
Checks for the existence of a type defined by
.BR typedef .
.I type_name
if not conf.CheckCHeader( 'math.h' ):
print 'We really need math.h!'
Exit(1)
-if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
+if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++',
+ 'QApplication qapp(0,0);' ):
# do stuff for qt - usage, e.g.
conf.env.Append( CPPFLAGS = '-DWITH_QT' )
env = conf.Finish()
.EE
.TP
-.RI Configure.CheckTypeSize( self ", " type_name ", [" header ", " language ", " expect ])
+.RI SConf.CheckTypeSize( context ", " type_name ", [" header ", " language ", " expect ])
+.TP
+.IR sconf .CheckTypeSize( type_name ", [" header ", " language ", " expect ])
Checks for the size of a type defined by
.BR typedef .
.I type_name
.EE
.TP
-.RI Configure.CheckDeclaration( self ", " symbol ", [" includes ", " language ])
+.RI SConf.CheckDeclaration( context ", " symbol ", [" includes ", " language ])
+.TP
+.IR sconf .CheckDeclaration( symbol ", [" includes ", " language ])
Checks if the specified
.I symbol
is declared.
the default is "C".
.TP
-.RI Configure.Define(self ", " symbol ", [" value ", " comment ])
+.RI SConf.Define( context ", " symbol ", [" value ", " comment ])
+.TP
+.IR sconf .Define( symbol ", [" value ", " comment ])
This function does not check for anything, but defines a
preprocessor symbol that will be added to the configuration header file.
It is the equivalent of AC_DEFINE,