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
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Chapter 26. Detailed reference</title>
<link rel="stylesheet" href="../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
<style type="text/css">
body { background-image: url('http://docbook.sourceforge.net/release/images/draft.png');
background-repeat: no-repeat;
background-position: top left;
/* The following properties make the watermark "fixed" on the page. */
/* I think that's just a bit too distracting for the reader... */
/* background-attachment: fixed; */
/* background-position: center center; */
}</style>
<link rel="start" href="../index.html" title="The Boost C++ Libraries">
<link rel="up" href="../bbv2.html" title="Part III. Boost.Build v2 User Manual">
<link rel="prev" href="extending/toolset_modules.html" title="Toolset modules">
<link rel="next" href="reference/jamfiles.html" title="Writing Jamfiles">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%">
<td valign="top"><img alt="boost.png (6897 bytes)" width="277" height="86" src="../../../boost.png"></td>
<td align="center"><a href="../../../index.htm">Home</a></td>
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="../../../people/people.htm">People</a></td>
<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
<td align="center"><a href="../../../more/index.htm">More</a></td>
</table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="extending/toolset_modules.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../bbv2.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="reference/jamfiles.html"><img src="../images/next.png" alt="Next"></a>
</div>
<div class="chapter" lang="en">
<div class="titlepage"><div><div><h2 class="title">
<a name="bbv2.reference"></a>Chapter 26. Detailed reference</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
<dt><span class="section"><a href="reference.html#bbv2.reference.general">General information</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="reference.html#bbv2.reference.init">Initialization</a></span></dt>
<dt><span class="section"><a href="reference.html#bbv2.reference.commandline">Command line</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="reference/jamfiles.html">Writing Jamfiles</a></span></dt>
<dd><dl><dt><span class="section"><a href="reference/jamfiles.html#bbv2.reference.headers">Generated headers</a></span></dt></dl></dd>
<dt><span class="section"><a href="reference/buildprocess.html">Build process</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="reference/buildprocess.html#bbv2.reference.buildprocess.alternatives">Alternative selection</a></span></dt>
<dt><span class="section"><a href="reference/buildprocess.html#bbv2.reference.buildprocess.common">Determining common properties</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="reference/definitions.html">Definitions</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="reference/definitions.html#bbv2.reference.features">Features and properties</a></span></dt>
<dt><span class="section"><a href="reference/definitions.html#bbv2.reference.variants">Build Variants</a></span></dt>
<dt><span class="section"><a href="reference/definitions.html#bbv2.reference.variants.proprefine">Property refinement</a></span></dt>
<dt><span class="section"><a href="reference/definitions.html#bbv2.reference.variants.propcond">Conditional properties</a></span></dt>
<dt><span class="section"><a href="reference/definitions.html#bbv2.reference.ids">Target identifiers and references</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="reference/generators.html">Generators</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="reference/generators.html#id1708734">Selecting and ranking viable generators</a></span></dt>
<dt><span class="section"><a href="reference/generators.html#id1708774">Running generators</a></span></dt>
<dt><span class="section"><a href="reference/generators.html#id1708800">Selecting dependency graph</a></span></dt>
<dt><span class="section"><a href="reference/generators.html#id1708811">Property adjustment</a></span></dt>
<dt><span class="section"><a href="reference/generators.html#id1708854">Transformations cache</a></span></dt>
</dl></dd>
</dl>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="bbv2.reference.general"></a>General information</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="reference.html#bbv2.reference.init">Initialization</a></span></dt>
<dt><span class="section"><a href="reference.html#bbv2.reference.commandline">Command line</a></span></dt>
</dl></div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.reference.init"></a>Initialization</h3></div></div></div>
<p>bjam's first job upon startup is to load the Jam code that
implements the build system. To do this, it searches for a file
called <code class="filename">boost-build.jam</code>, first in the invocation directory, then
in its parent and so forth up to the filesystem root, and finally
in the directories specified by the environment variable
BOOST_BUILD_PATH. When found, the file is interpreted, and should
specify the build system location by calling the boost-build
rule:</p>
<pre class="programlisting">
rule boost-build ( location ? )
</pre>
<p>
If location is a relative path, it is treated as relative to
the directory of <code class="filename">boost-build.jam</code>. The directory specified by
that location and the directories in BOOST_BUILD_PATH are then searched for
a file called <code class="filename">bootstrap.jam</code>, which is expected to
bootstrap the build system. This arrangement allows the build
system to work without any command-line or environment variable
settings. For example, if the build system files were located in a
directory "build-system/" at your project root, you might place a
<code class="filename">boost-build.jam</code> at the project root containing:
</p>
<pre class="programlisting">
boost-build build-system ;
</pre>
<p>
In this case, running bjam anywhere in the project tree will
automatically find the build system.</p>
<p>The default <code class="filename">bootstrap.jam</code>, after loading some standard
definitions, loads two files, which can be provided/customised by
user: <code class="filename">site-config.jam</code> and <code class="filename">user-config.jam</code>.</p>
<p>Locations where those files a search are summarized below:</p>
<div class="table">
<a name="bbv2.reference.init.config"></a><p class="title"><b>Table 26.1. Search paths for configuration files</b></p>
<table class="table" summary="Search paths for configuration files">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th> </th>
<th>site-config.jam</th>
<th>user-config.jam</th>
</tr></thead>
<tbody>
<tr>
<td>Linux</td>
<td>
<p><code class="computeroutput">/etc</code></p>
<p><code class="computeroutput">$HOME</code></p>
<p><code class="computeroutput">$BOOST_BUILD_PATH</code></p>
</td>
<td>
<p><code class="computeroutput">$HOME</code></p>
<p><code class="computeroutput">$BOOST_BUILD_PATH</code></p>
</td>
</tr>
<tr>
<td>Windows</td>
<td>
<p><code class="computeroutput">%SystemRoot%</code></p>
<p><code class="computeroutput">%HOMEDRIVE%%HOMEPATH%</code></p>
<p><code class="computeroutput">%HOME%</code></p>
<p><code class="computeroutput">%BOOST_BUILD_PATH%</code></p>
</td>
<td>
<p><code class="computeroutput">%HOMEDRIVE%%HOMEPATH%</code></p>
<p><code class="computeroutput">%HOME%</code></p>
<p><code class="computeroutput">%BOOST_BUILD_PATH%</code></p>
</td>
</tr>
</tbody>
</table>
</div>
<p>
Boost.Build comes with default versions of those files,
which can serve as templates for customized versions.
</p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.reference.commandline"></a>Command line</h3></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="reference.html#bbv2.reference.init.args">Command line arguments</a></span></dt>
<dt><span class="section"><a href="reference.html#bbv2.reference.init.options">Command line options</a></span></dt>
</dl></div>
<p>The command line may contain:</p>
<div class="itemizedlist"><ul type="disc">
<li>Jam options,</li>
<li>Boost.Build <a href="reference.html#bbv2.reference.init.options" title="Command line options">options</a>,</li>
<li>Command line arguments</li>
</ul></div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="bbv2.reference.init.args"></a>Command line arguments</h4></div></div></div>
<p>
Command line arguments specify targets and build
request using the following rules.
</p>
<div class="itemizedlist"><ul type="disc">
<li>
An argument that does not contain slashes or the <code class="computeroutput">=</code>
symbol is either a value of an implicit feature or of a target to
be built. It is taken to be value of a feature if an appropriate
feature exists. Otherwise, it is considered a <a href="reference/definitions.html#bbv2.reference.ids" title="Target identifiers and references">target id</a>. Building the
special target name “clean” has the same effect as
using the <code class="computeroutput">--clean</code> option.
</li>
<li>
<p>
An argument containing either slashes or
the <code class="computeroutput">=</code> symbol specifies a number of build
request elements (see ???). In its simplest
form, it's just a set of properties, separated by
slashes, which become a single build request element,
for example:
</p>
<pre class="programlisting">
borland/<runtime-link>static
</pre>
<p>
A more complex form can be used to save typing. For example,
instead of
</p>
<pre class="programlisting">
borland/runtime-link=static borland/runtime-link=dynamic
</pre>
<p>
one can use
</p>
<pre class="programlisting">
borland/runtime-link=static,dynamic
</pre>
<p>
Exactly, the conversion from argument to build request
elements is performed by (1) splitting the argument at each slash,
(2) converting each split part into a set of properties and (3)
taking all possible combinations
of the property sets. Each split
part should have the either the form
</p>
<pre class="programlisting"><span class="emphasis"><em>feature-name</em></span>=<span class="emphasis"><em>feature-value1</em></span>[","<span class="emphasis"><em>feature-valueN</em></span>]*
</pre>
<p>
or, in case of implicit features
</p>
<pre class="programlisting"><span class="emphasis"><em>feature-value1</em></span>[","<span class="emphasis"><em>feature-valueN</em></span>;]*
</pre>
<p>
will be converted into the property set
</p>
<pre class="programlisting">
<feature-name>feature-value1 .... <feature-name>feature-valueN
</pre>
</li>
</ul></div>
<p>
For example, the command line
</p>
<pre class="programlisting">
target1 debug gcc/runtime-link=dynamic,static
</pre>
<p>
would cause target called <code class="literal">target1</code> to be rebuilt in
debug mode, except that for gcc, both dynamically and statically
linked binaries would be created.
</p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="bbv2.reference.init.options"></a>Command line options</h4></div></div></div>
<p>All of the Boost.Build options start with the "--" prefix.
They are described in the following table.</p>
<div class="table">
<a name="id1707672"></a><p class="title"><b>Table 26.2. Command line options</b></p>
<table class="table" summary="Command line options">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>Option</th>
<th>Description</th>
</tr></thead>
<tbody>
<tr>
<td><code class="literal">--version</code></td>
<td>Prints information on Boost.Build and Boost.Jam
versions.</td>
</tr>
<tr>
<td>
<a name="bbv2.reference.init.options.help"></a><code class="literal">--help</code>
</td>
<td>Access to the online help system. This prints general
information on how to use the help system with additional
--help* options.</td>
</tr>
<tr>
<td><code class="literal">--clean</code></td>
<td>Removes everything instead of building. Unlike
<code class="literal">clean</code> target in make, it is possible to clean only
some targets.</td>
</tr>
<tr>
<td><code class="literal">--debug</code></td>
<td>Enables internal checks.</td>
</tr>
<tr>
<td><code class="literal">--dump-projects</code></td>
<td>Cause the project structure to be output.</td>
</tr>
<tr>
<td><code class="literal">--no-error-backtrace</code></td>
<td>Don't print backtrace on errors. Primary useful for
testing.</td>
</tr>
<tr>
<td><code class="literal">--ignore-config</code></td>
<td>Do not load <code class="literal">site-config.jam</code> and
<code class="literal">user-config.jam</code>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</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="extending/toolset_modules.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../bbv2.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="reference/jamfiles.html"><img src="../images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
