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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Chapter4.Overview</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="tutorial/prebuilt.html" title="Prebuilt targets">
<link rel="next" href="advanced/configuration.html" title="Configuration">
</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="tutorial/prebuilt.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="advanced/configuration.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.advanced"></a>Chapter4.Overview</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
<dt><span class="section"><a href="advanced.html#bbv2.advanced.jam_language">Boost.Jam Language</a></span></dt>
<dt><span class="section"><a href="advanced/configuration.html">Configuration</a></span></dt>
<dt><span class="section"><a href="advanced/invocation.html">Invocation</a></span></dt>
<dt><span class="section"><a href="advanced/targets.html">Declaring Targets</a></span></dt>
<dt><span class="section"><a href="advanced/projects.html">Projects</a></span></dt>
<dt><span class="section"><a href="advanced/build_process.html">The Build Process</a></span></dt>
</dl>
</div>
<p>This section will provide the information necessary to create your own
projects using Boost.Build. The information provided here is relatively
high-level, and <a href="reference.html" title="Chapter7.Detailed reference">Chapter7, <i>Detailed reference</i></a> as
well as the on-line help system must be used to obtain
low-level documentation (see <a href="advanced/invocation.html#bbv2.reference.init.options.help"><code class="option">--help</code></a>).</p>
<p>Boost.Build actually consists of two parts - Boost.Jam, a
build engine with its own interpreted language, and Boost.Build itself,
implemented in Boost.Jam's language. The chain of events when
you type <span><strong class="command">bjam</strong></span> on the command line is:
</p>
<div class="orderedlist"><ol type="1">
<li><p>Boost.Jam tries to find Boost.Build and loads the top-level
module. The exact process is described in <a href="reference.html#bbv2.reference.init" title="Initialization">the section called “Initialization”</a></p></li>
<li><p>The top-level module loads user-defined configuration
files, <code class="filename">user-config.jam</code> and <code class="filename">site-config.jam</code>, which define
available toolsets.</p></li>
<li><p>The Jamfile in the current directory is read. That in turn
might cause reading of further Jamfiles. As a result, a tree of
projects is created, with targets inside projects.</p></li>
<li><p>Finally, using the build request specified on the command line,
Boost.Build decides which targets should be built, and how. That
information is passed back to Boost.Jam, which takes care of
actually running commands.</p></li>
</ol></div>
<p>
</p>
<p>So, to be able to successfully use Boost.Build, you need to know only
four things:
</p>
<div class="itemizedlist"><ul type="disc">
<li><p><a href="advanced/configuration.html" title="Configuration">
How to configure Boost.Build</a></p></li>
<li><p><a href="advanced/targets.html" title="Declaring Targets">
How to write declares targets in Jamfiles</a></p></li>
<li><p><a href="advanced/build_process.html" title="The Build Process">
How the build process works</a></p></li>
<li><p>Some Basics about the Boost.Jam language. See
<a href="advanced.html#bbv2.advanced.jam_language" title="Boost.Jam Language">the section called “Boost.Jam Language”</a>.
</p></li>
</ul></div>
<p>
</p>
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="bbv2.advanced.jam_language"></a>Boost.Jam Language</h2></div></div></div>
<p>This section will describe the basics of the Boost.Jam
language—just enough for writing Jamfiles. For more information,
please see the <a href="jam.html" title="AppendixA.Boost.Jam Documentation">Boost.Jam</a>
documentation.</p>
<p>Boost.Jam has an interpreted, procedural language.
On the lowest level, a Boost.Jam program consists of variables and
<a class="indexterm" name="id2587056"></a>
<em class="firstterm">rules</em> (the Jam term for function). They are grouped
in modules—there's one global module and a number of named
modules. Besides that, a Boost.Jam program contains classes and class
instances.
</p>
<p>Syntantically, a Boost.Jam program consists of two kind of
elements—keywords (which have a special meaning to Boost.Jam) and
literals.
Consider this code:
</p>
<pre class="programlisting">
a = b ;</pre>
<p>
which assigns the value <code class="literal">b</code> to the variable
<code class="literal">a</code>. Here, <code class="literal">=</code> and
<code class="literal">;</code> are keywords, while <code class="literal">a</code> and
<code class="literal">b</code> are literals.
</p>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/html/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top"><p>All syntax elements, even keywords, must be separated by
spaces. For example, omitting the space character before
<code class="literal">;</code> will lead to a syntax error.
</p></td></tr>
</table></div>
<p>
If you want to use a literal value that is the same as some keyword, the
value can be quoted:
</p>
<pre class="programlisting">
a = "=" ;</pre>
<p>
</p>
<p>All variables in Boost.Jam have the same type—list of
strings. To define a variable one assigns a value to it, like in the
previous example. An undefined variable is the same as a variable with
an empty value. Variables can be accessed with the
<code class="computeroutput">$(<em class="replaceable"><code>variable</code></em>)</code> syntax. For example:
</p>
<pre class="programlisting">
a = $(b) $(c) ;</pre>
<p>
</p>
<p>
Rules are defined by specifying the rule name, the parameter names,
and the allowed size of the list value for each parameter.
</p>
<pre class="programlisting">
rule <em class="replaceable"><code>example</code></em>
(
<em class="replaceable"><code>parameter1</code></em> :
<em class="replaceable"><code>parameter2 ?</code></em> :
<em class="replaceable"><code>parameter3 +</code></em> :
<em class="replaceable"><code>parameter4 *</code></em>
)
{
// body
}</pre>
<p>
When this rule is called, the list passed as the first argument must
have exactly one value. The list passed as the second argument can
either have one value of be empty. The two remaining arguments can
be arbitrary long, but the third argument may not be empty.
</p>
<p>The overview of Boost.Jam language statements is given below:
</p>
<pre class="programlisting">
helper 1 : 2 : 3 ;
x = [ helper 1 : 2 : 3 ] ;</pre>
<p>
This code calls the named rule with the specified arguments. When the
result of the call must be used inside some expression, you need to add
brackets around the call, like shown on the second line.
</p>
<pre class="programlisting">
if cond { statements } [ else { statements } ]</pre>
<p>
This is a regular if-statement. The condition is composed of:
</p>
<div class="itemizedlist"><ul type="disc">
<li><p>Literals (true if at least one string is not empty)</p></li>
<li><p>Comparisons: <code class="computeroutput">a
<em class="replaceable"><code>operator</code></em> b</code> where
<em class="replaceable"><code>operator</code></em> is one of <code class="computeroutput">=</code>,
<code class="computeroutput">!=</code>, <code class="computeroutput"><</code>, <code class="computeroutput">></code>,
<code class="computeroutput"><=</code>, <code class="computeroutput">>=</code>. The comparison is done
pairwise between each string in the left and the right arguments.
</p></li>
<li><p>Logical operations: <code class="computeroutput">! a</code>, <code class="computeroutput">a &&
b</code>, <code class="computeroutput">a || b</code></p></li>
<li><p>Grouping: <code class="computeroutput">( cond )</code></p></li>
</ul></div>
<p>
</p>
<pre class="programlisting">
for var in list { statements }</pre>
<p>
Executes statements for each element in list, setting the variable
<code class="varname">var</code> to the element value.
</p>
<pre class="programlisting">
while cond { statements }</pre>
<p>
Repeatedly execute statements while cond remains true upon entry.
</p>
<pre class="programlisting">
return values ;
</pre>
<p>This statement should be used only inside a
rule and assigns <code class="computeroutput">values</code> to the return value of the
rule.
</p>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/html/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top">
<p>
The <code class="computeroutput">return</code> statement does not exit the rule. For example:
</p>
<pre class="programlisting">
rule test ( )
{
if 1 = 1 {
return "reasonable" ;
}
return "strange" ;
}</pre>
<p> will return <code class="literal">strange</code>, not
<code class="literal">reasonable</code>.
</p>
</td></tr>
</table></div>
<p>
</p>
<pre class="programlisting">
import <em class="replaceable"><code>module</code></em> ;
import <em class="replaceable"><code>module</code></em> : <em class="replaceable"><code>rule</code></em> ;</pre>
<p>
The first form imports the specified bjam module. All rules from
that module are made available using the qualified name:
<code class="computeroutput"><em class="replaceable"><code>module</code></em>.<em class="replaceable"><code>rule</code></em></code>.
The second form imports the specified rules only, and they can be called
using unqualified names.
</p>
<p><a name="bbv2.advanced.jam_language.actions"></a>
Sometimes, you'd need to specify the actual command lines to be used
when creating targets. In jam language, you use named actions to do this.
For example:
</p>
<pre class="programlisting">
actions create-file-from-another
{
create-file-from-another $(<) $(>)
}
</pre>
<p>
This specifies a named action called
<code class="literal">create-file-from-another</code>. The text inside braces is the
command to invoke. The <code class="literal">$(<)</code> variable will be expanded to list of
generated files, and the <code class="literal">$(>)</code> variable will be expanded
to the list of source files.
</p>
<p>To flexibly adjust command line, you can define a rule with the
same name as the action, and taking three parameters -- targets, sources
and properties. For example:
</p>
<pre class="programlisting">
rule create-file-from-another ( targets * : sources * : properties * )
{
if <variant>debug in $(properties)
{
OPTIONS on $(targets) = --debug ;
}
}
actions create-file-from-another
{
create-file-from-another $(OPTIONS) $(<) $(>)
}
</pre>
<p>
In this example, the rule checks if certain build property is specified.
If so, it sets variable <code class="varname">OPIONS</code> that's used inside
action. Note that the variable is set "on targets" -- the value will
be only visible inside action, not globally. Were it set globally,
using variable named <code class="varname">OPTIONS</code> in two unrelated
actions would be impossible.
</p>
<p>More details can be found in Jam reference, <a href="../jam/language.html#jam.language.rules" title=" Rules">the section called “ Rules”</a>
</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="tutorial/prebuilt.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="advanced/configuration.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
