If your extensions will be used only on one project, they can be placed in
a separate .jam
file and imported by your
Jamroot.jam
. If the extensions will be used on many
projects, users will thank you for a finishing touch.
The using
rule provides a standard mechanism
for loading and configuring extensions. To make it work, your module
should provide an init
rule. The rule will be called
with the same parameters that were passed to the
using
rule. The set of allowed parameters is
determined by you. For example, you can allow the user to specify
paths, tool versions, and other options.
Here are some guidelines that help to make Boost.Build more consistent:
The init
rule should never fail. Even if
the user provided an incorrect path, you should emit a warning and go
on. Configuration may be shared between different machines, and
wrong values on one machine can be OK on another.
Prefer specifying the command to be executed to specifying the tool's installation path. First of all, this gives more control: it's possible to specify
/usr/bin/g++-snapshot time g++
as the command. Second, while some tools have a logical "installation root", it's better if the user doesn't have to remember whether a specific tool requires a full command or a path.
Check for multiple initialization. A user can try to initialize the module several times. You need to check for this and decide what to do. Typically, unless you support several versions of a tool, duplicate initialization is a user error. If the tool's version can be specified during initialization, make sure the version is either always specified, or never specified (in which case the tool is initialied only once). For example, if you allow:
using yfc ; using yfc : 3.3 ; using yfc : 3.4 ;
Then it's not clear if the first initialization corresponds to version 3.3 of the tool, version 3.4 of the tool, or some other version. This can lead to building twice with the same version.
If possible, init
must be callable
with no parameters. In which case, it should try to autodetect all
the necessary information, for example, by looking for a tool in
PATH
or in common installation locations. Often this
is possible and allows the user to simply write:
using yfc ;
Consider using facilities in the
tools/common
module. You can take a look at how
tools/gcc.jam
uses that module in the init
rule.