Chapter 22. Extender Manual

| Home | Libraries | People | FAQ | More

## Chapter 22. Extender Manual

## Introduction

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

Say you're writing an application which 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:

1. Write the template of the code to be generated, leaving placeholders at the points which will change
2. Access the template in your application and replace placeholders with appropriate text.
3. Write the result.

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

Let's see what Boost.Build can do.

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

    import type ;
    type.register VERBATIM : verbatim ;

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

Lastly, you need a tool to convert verbatim files to C++. Say you've sketched such a tool in Python. Then, you have to inform Boost.Build about the tool. The Boost.Build concept which represents a tool is generator.

First, you say that generator 'inline-file' is able to convert VERBATIM type into C++:

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

Second, you must specify the commands to be run to actually perform convertion:

    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.