The site_scons
directories give you a place to
put Python modules and packages that you can import into your SConscript
files
(site_scons
),
add-on tools that can integrate into SCons
(site_scons/site_tools
),
and a site_scons/site_init.py
file that
gets read before any SConstruct
or SConscript
file,
allowing you to change SCons's default behavior.
Each system type (Windows, Mac, Linux, etc.) searches a canonical set of directories for site_scons; see the man page for details. The top-level SConstruct's site_scons dir is always searched last, and its dir is placed first in the tool path so it overrides all others.
If you get a tool from somewhere (the SCons wiki or a third party,
for instance) and you'd like to use it in your project, a
site_scons
dir is the simplest place to put it.
Tools come in two flavors; either a Python function that operates on
an Environment
or a Python module or package containing two functions,
exists()
and generate()
.
A single-function Tool can just be included in your
site_scons/site_init.py
file where it will be
parsed and made available for use. For instance, you could have a
site_scons/site_init.py
file like this:
def TOOL_ADD_HEADER(env): """A Tool to add a header from $HEADER to the source file""" add_header = Builder(action=['echo "$HEADER" > $TARGET', 'cat $SOURCE >> $TARGET']) env.Append(BUILDERS = {'AddHeader' : add_header}) env['HEADER'] = '' # set default value
and a SConstruct
like this:
# Use TOOL_ADD_HEADER from site_scons/site_init.py env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====") env.AddHeader('tgt', 'src')
The TOOL_ADD_HEADER
tool method will be
called to add the AddHeader
tool to the
environment.
A more full-fledged tool with
exists()
and generate()
methods can be installed either as a module in the file
site_scons/site_tools/toolname.py
or as a
package in the
directory site_scons/site_tools/toolname
. In
the case of using a package, the exists()
and generate()
are in the
file site_scons/site_tools/toolname/__init__.py
.
(In all the above case toolname
is replaced
by the name of the tool.)
Since site_scons/site_tools
is automatically
added to the head of the tool search path, any tool found there
will be available to all environments. Furthermore, a tool found
there will override a built-in tool of the same name, so if you
need to change the behavior of a built-in
tool, site_scons
gives you the hook you need.
Many people have a library of utility Python functions they'd like
to include in SConscript
s; just put that module in
site_scons/my_utils.py
or any valid Python module name of your
choice. For instance you can do something like this in
site_scons/my_utils.py
to add
build_id
and MakeWorkDir
functions:
from SCons.Script import * # for Execute and Mkdir def build_id(): """Return a build ID (stub version)""" return "100" def MakeWorkDir(workdir): """Create the specified dir immediately""" Execute(Mkdir(workdir))
And then in your SConscript
or any sub-SConscript
anywhere in
your build, you can import my_utils
and use it:
import my_utils print("build_id=" + my_utils.build_id()) my_utils.MakeWorkDir('/tmp/work')
Note that although you can put this library in
site_scons/site_init.py
,
it is no better there than site_scons/my_utils.py
since you still have to import that module into your SConscript
.
Also note that in order to refer to objects in the SCons namespace
such as Environment
or Mkdir
or Execute
in any file other
than a SConstruct
or SConscript
you always need to do
from SCons.Script import *
This is true in modules in site_scons
such as
site_scons/site_init.py
as well.
You can use any of the user- or machine-wide site dirs such as
~/.scons/site_scons
instead of
./site_scons
, or use the
--site-dir
option to point to your own dir.
site_init.py
and
site_tools
will be located under that dir.
To avoid using a site_scons
dir at all,
even if it exists, use the --no-site-dir
option.