1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Chapter6.Extender Manual</title>
<link rel="stylesheet" href="../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
<link rel="start" href="../index.html" title="Boost.Build V2 User Manual">
<link rel="up" href="../index.html" title="Boost.Build V2 User Manual">
<link rel="prev" href="reference/generated_headers.html" title="Generated headers">
<link rel="next" href="extending/targets.html" title="Target types">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="reference/generated_headers.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="extending/targets.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
</div>
<div class="chapter" lang="en">
<div class="titlepage"><div><div><h2 class="title">
<a name="bbv2.extender"></a>Chapter6.Extender Manual</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
<dt><span class="section"><a href="extender.html#bbv2.extender.intro">Introduction</a></span></dt>
<dt><span class="section"><a href="extending/targets.html">Target types</a></span></dt>
<dt><span class="section"><a href="extending/tools.html">Tools and generators</a></span></dt>
<dt><span class="section"><a href="extending/features.html">Features</a></span></dt>
<dt><span class="section"><a href="extending/rules.html">Main target rules</a></span></dt>
<dt><span class="section"><a href="extending/toolset_modules.html">Toolset modules</a></span></dt>
</dl>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="bbv2.extender.intro"></a>Introduction</h2></div></div></div>
<p>This document explains how to extend Boost.Build to accomodate
your local requirements. Let's start with a simple but
realistic example.</p>
<p>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:</p>
<div class="orderedlist"><ol type="1">
<li>
Write the template of the code to be generated, leaving
placeholders at the points that will change
</li>
<li>
Access the template in your application and replace
placeholders with appropriate text.
</li>
<li>Write the result.</li>
</ol></div>
<p>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 <code class="computeroutput">char*</code> variable whose name is taken from the first line
of the verbatim file and whose value is the file's properly quoted content.</p>
<p>Let's see what Boost.Build can do.</p>
<p>First off, Boost.Build has no idea about "verbatim files". So,
you must register a new target type. The following code does
it:</p>
<pre class="programlisting">
import type ;
type.register VERBATIM : vrb ;
</pre>
<p>The first parameter to
<code class="computeroutput">type.register</code> 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 class="filename">code.vrb</code> in a list of sources, it knows that it's of type
<code class="computeroutput">VERBATIM</code>.</p>
<p>Next, you tell Boost.Build that the verbatim files can be
transformed into C++ files in one build step. A
<em class="firstterm">generator</em> is a template for a build step that
transforms targets of one type (or set of types) into another. Our
generator will be called <code class="computeroutput">verbatim.inline-file</code>; it
transforms <code class="computeroutput">VERBATIM</code> files into <code class="computeroutput">CPP</code> files:
</p>
<pre class="programlisting">
import generators ;
generators.register-standard verbatim.inline-file : VERBATIM : CPP ;
</pre>
<p>
</p>
<p>Lastly, you have to inform Boost.Build about the shell
commands used to make that transformation. That's done with an
<code class="computeroutput">actions</code> declaration.
</p>
<pre class="programlisting">
actions inline-file
{
"./inline-file.py" $(<) $(>)
}
</pre>
<p>
</p>
<p>Now, we're ready to tie it all together. Put all the code
above in file <code class="filename">verbatim.jam</code>, add <code class="computeroutput">import verbatim ;</code>
to <code class="filename">project-root.jam</code>, and it's possible to write
the following in Jamfile:</p>
<pre class="programlisting">
exe codegen : codegen.cpp class_template.verbatim usage.verbatim ;
</pre>
<p>
The verbatim files will be automatically converted into C++
and linked it.
</p>
<p>In the subsequent sections, we will extend this example, and review
all the mechanisms in detail. The complete code is available in <code class="filename">example/customization</code>
directory.
</p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><small></small></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="reference/generated_headers.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="extending/targets.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
