This document explains how to extend Boost.Build to accomodate your local requirements. Let's start with a simple but realistic example.

Say you're writing an application that generates C++ code. If you ever did this, you know that it's not nice. Embedding large portions of C++ code in string literals is very awkward. A much better solution is:

It's quite easy to achieve. You write special verbatim files that are just C++, except that the very first line of the file contains the name of a variable that should be generated. A simple tool is created that takes a verbatim file and creates a cpp file with a single char* variable whose name is taken from the first line of the verbatim file and whose value is the file's properly quoted content.

Let's see what Boost.Build can do.

First off, Boost.Build has no idea about "verbatim files". So, you must register a new target type. The following code does it:

import type ;
type.register VERBATIM : vrb ;

The first parameter to type.register gives the name of the declared type. By convention, it's uppercase. The second parameter is the suffix for files of this type. So, if Boost.Build sees code.vrb in a list of sources, it knows that it's of type VERBATIM.

Next, you tell Boost.Build that the verbatim files can be transformed into C++ files in one build step. A generator is a template for a build step that transforms targets of one type (or set of types) into another. Our generator will be called verbatim.inline-file; it transforms VERBATIM files into CPP files:

import generators ;
generators.register-standard verbatim.inline-file : VERBATIM : CPP ;

Lastly, you have to inform Boost.Build about the shell commands used to make that transformation. That's done with an actions declaration.

actions inline-file
{
    "./inline-file.py" $(<) $(>)
}

Now, we're ready to tie it all together. Put all the code above in file verbatim.jam, add import verbatim ; to project-root.jam, and it's possible to write the following in Jamfile:

exe codegen : codegen.cpp class_template.verbatim usage.verbatim ;

The verbatim files will be automatically converted into C++ and linked it.

In the subsequent sections, we will extend this example, and review all the mechanisms in detail. The complete code is available in example/customization directory.