The site_scons directory gives you a place to put Python modules you can import into your SConscripts (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, allowing you to change SCons's default behavior.
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, the
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 file 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.
Similarly, a more full-fledged tool with
exists()
and generate()
methods can be installed in
site_scons/site_tools/toolname.py. 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 SConscripts; 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 a build_id method:
def build_id(): """Return a build ID (stub version)""" return "100"
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()
If you have a machine-wide site dir you'd like to use instead of ./site_scons, use the --site-dir option to point to your 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.