Toolset modules

| Home | Libraries | People | FAQ | More

## Toolset modules

If your extensions will be used only on one project, they can be placed in a separate `.jam` file which will be imported by your `project-root.jam`. If the extensions will be used on many projects, the users will thank you for a finishing touch.

The standard way to use a tool in Boost.Build is the `using` rule. To make it work, you module should provide an `init` rule. The rule will be called with the same parameters which 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 version, or tool options.

Here are some guidelines which help to make Boost.Build more consistent:

- The `init` rule should never fail. Even if user provided a wrong 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 command to be executed to specifying 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 better if user don't have to remember if 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 tool 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, the `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.