A tool for SCons to enable building of Jinja2 templates. It was originally created for C metaprogramming, in which the source C files were autogenerated from templates. The dependency tracking is handled properly and is inferred from the template itself (that is, if a C file depends on a template, which in turn depends on a second template, then changes to the second template will trigger the necessary rebuilds).
For more infomation on Jinja itself, take a look at the Jinja documentation.
Nothing is C specific, so it should work fine with templates for anything.
A few examples are included (see below for how to use them).
To enble the tool, copy __init__.py in this directory to a directory jinja
in your tool path. In the case of a specific project, the tool path is
something like site_scons/site_tools/
at the same level as the project SConstruct file.
You can clone the repository directly into your site_tools directory with
git clone https://github.com/hgomersall/scons-jinja jinja
(which creates a new directory jinja containing the repository wherever
you happen to be when the command is run).
Next, add the tool to an environment with something like the following:
env = Environment(tools=['default', 'jinja'])
The default keeps all the default tools available.
Once the tool is loaded, it can be used with the Jinja builder. e.g.
env.Jinja('target_file_name.c', os.path.join('templates, a_template.c.jinja'))
The resultant target is then in dependency tree, so the following would work
env.SharedLibrary('my_lib', env.Glob('*.c'))
Jinja templates are assumed to have the .jinja extension.
For more complete usage, see the examples in the examples directory.
Three new environment variables are available:
JINJA_CONTEXT: This is the context dictionary that is passed to the
template when it is rendered.
JINJA_ENVIRONMENT_VARS: When the jinja environment is created during
the render phase, it is passed this dictionary as a set of keyword arguments.
The entries in this dictionary correspond to the initialization parameters
described in
jinja2.Environment.
JINJA_TEMPLATE_SEARCHPATH: This provides additional paths that Jinja
can use to look up dependencies. Templates that are named explicitly as a
SCons node are provided with a path within the build tree. This path is the
default search path for dependencies. For example, if env.Jinja is called
for some template templates/tmpl_1.c.jinja, which is turn depends on
tmpl_2.c.jinja, which is also located in the templates directory,
then tmpl_2.c.jinja will be found with no additional paths in
JINJA_TEMPLATE_SEARCHPATH. If on the other hand, tmpl_2.c.jinja is in
some other directory, say additional_templates, then additional_templates
should be added to the JINJA_TEMPLATE_SEARCHPATH list. Note that these
paths are absolute paths or are relative to the SCons root (not, say, the
SConscript path).
There can only be one set of
variables per environment, this means there is a one-to-one mapping between
SCons environments and Jinja environments. If you need render two templates
with, say, different contexts, then you do it by
creating a new SCons environment for each template, each with their own
JINJA_CONTEXT.
An example of various usages is included in the examples directory.
To use this, you need to create an additional directory
examples/site_scons/site_tools/jinja and copy __init__.py into
that directory.
Run scons inside the examples directory. It should generate various
outputs in various different ways.
SConstruct in examples and SConscript in examples/src show
the usage inconjuction with the various reference template files. The
SConstruct and SConscript files should be fairly self explanatory.