# Boost.Build v2 extender manual

Introduction
Target types
Tools
Main target rules
Scanners

## 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 archive. 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.

The complete code is available in example/customization directory.

## Target types

## Tools

## Main target rules

## Scanners

Last modified: Jule 3, 2003

© Copyright Vladimir Prus 2002-2003. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided ``as is'' without express or implied warranty, and with no claim as to its suitability for any purpose.