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
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Chapter 24. User documentation</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="tutorial/prebuilt.html" title="Prebuilt targets">
<link rel="next" href="advanced/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="tutorial/prebuilt.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="advanced/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.advanced"></a>Chapter 24. User documentation</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.configuration">Configuration</a></span></dt>
<dt><span class="section"><a href="advanced/jamfiles.html">Writing Jamfiles</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="advanced/jamfiles.html#bbv2.advanced.overview">Overview</a></span></dt>
<dt><span class="section"><a href="advanced/jamfiles.html#bbv2.advanced.targets">Main targets</a></span></dt>
<dt><span class="section"><a href="advanced/jamfiles.html#bbv2.advanced.projects">Projects</a></span></dt>
<dt><span class="section"><a href="advanced/jamfiles.html#bbv2.advanced.other-rules">Jamfile Utility Rules</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="advanced/build_process.html">The Build Process</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="advanced/build_process.html#id1698059">Build request</a></span></dt>
<dt><span class="section"><a href="advanced/build_process.html#id1698101">Building a main target</a></span></dt>
<dt><span class="section"><a href="advanced/build_process.html#id1698205">Building a project</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="advanced/builtins/targets.html">Builtin target types</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="advanced/builtins/targets.html#id1698264">Programs</a></span></dt>
<dt><span class="section"><a href="advanced/builtins/targets.html#id1698326">Libraries</a></span></dt>
<dt><span class="section"><a href="advanced/builtins/targets.html#bbv2.builtins.alias">Alias</a></span></dt>
<dt><span class="section"><a href="advanced/builtins/targets.html#bbv2.builtins.stage">Installing</a></span></dt>
<dt><span class="section"><a href="advanced/builtins/targets.html#bbv2.builtins.testing">Testing</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="advanced/builtins/features.html">Builtin features</a></span></dt>
<dt><span class="section"><a href="advanced/differences_to_v1.html">Differences to Boost.Build V1</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="advanced/differences_to_v1.html#bbv2.advanced.differences_to_v1.configuration">Configuration</a></span></dt>
<dt><span class="section"><a href="advanced/differences_to_v1.html#bbv2.advanced.differences_to_v1.jamfiles">Writing Jamfiles</a></span></dt>
<dt><span class="section"><a href="advanced/differences_to_v1.html#bbv2.advanced.differences_to_v1.build_process">Build process</a></span></dt>
</dl></dd>
</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="Chapter 26. Detailed reference">Chapter 26, <i>Detailed reference</i></a> as
well as the on-line help system must be used to obtain
low-level documentation (see <a href="reference.html#bbv2.reference.init.options.help">???</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>So, to be able to successfully use Boost.Build, you need to know only
three things:
</p>
<div class="itemizedlist"><ul type="disc">
<li><p><a href="advanced.html#bbv2.advanced.configuration" title="Configuration">
How to configure Boost.Build</a></p></li>
<li><p><a href="advanced/jamfiles.html" title="Writing Jamfiles">
How to write 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 the
<a href="http://www.boost.org/tools/build/jam_src/index.html#jam_fundamentals" target="_top">Boost.Jam</a>
and <a href="http://www.boost.org/tools/build/jam_src/jam.html" target="_top">Classic
Jam</a> documentation.
</p></li>
</ul></div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="bbv2.advanced.configuration"></a>Configuration</h2></div></div></div>
<p>The Boost.Build configuration is specified in the file
<code class="filename">user-config.jam</code>. You can edit the one that comes with Boost.Build, or
create a copy in your home directory and edit that. (See the <a href="reference.html#bbv2.reference.init.config" title="Table 26.1. Search paths for configuration files">reference</a> for the exact search
paths.) The primary function of that file is to declare which compilers
and other tools are available. The simplest syntax to configure a tool is:
</p>
<pre class="programlisting">
using <em class="replaceable"><code>tool-name</code></em> ;
</pre>
<p>
The <code class="computeroutput">using</code> rule is given a name of tool, and will make that tool
available to Boost.Build. For example, <code class="computeroutput">using gcc ;</code> will make the gcc compiler
available.
</p>
<p>
Since nothing but a tool name is specified, Boost.Build will
pick some default settings. For example, it will use the
<span><strong class="command">gcc</strong></span> executable found in the
<code class="envar">PATH</code>, or look in some known installation
locations. In most cases, this strategy works automatically. In
case you have several versions of a compiler, it's installed in
some unusual location, or you need to tweak its configuration,
you'll need to pass additional parameters to the
<code class="computeroutput">using</code> rule. The parameters to
<code class="computeroutput">using</code> can be different for each
tool. You can obtain specific documentation for any tool's
configuration parameters by invoking
</p>
<pre class="programlisting">
bjam --help <em class="replaceable"><code>tool-name</code></em>.init
</pre>
<p>
That said, for all the compiler toolsets Boost.Build supports
out-of-the-box, the list of parameters to
<code class="computeroutput">using</code> is the same: <em class="parameter"><code>toolset-name</code></em>, <em class="parameter"><code>version</code></em>, <em class="parameter"><code>invocation-command</code></em>, and <em class="parameter"><code>options</code></em>.
</p>
<p>The <em class="parameter"><code>version</code></em>
parameter identifies the toolset version, in case you have
several installed. It can have any form you like, but
it's recommended that you use a numeric identifier like
<code class="literal">7.1</code>.
</p>
<p>
The <em class="parameter"><code>invocation-command</code></em>
parameter is the command that must be executed to run the
compiler. This parameter can usually be omitted if the compiler
executable
</p>
<div class="itemizedlist"><ul type="disc">
<li><p>has its “usual
name” and is in the <code class="envar">PATH</code>,
or</p></li>
<li><p>was installed in a standard
“installation directory”,
or</p></li>
<li><p>can be found through a global mechanism like the
Windows registry.</p></li>
</ul></div>
<p>
For example:
</p>
<pre class="programlisting">
using msvc : 7.1 ;
using gcc ;
</pre>
<p>
If the compiler can be found in the <code class="envar">PATH</code> but only by a
nonstandard name, you can just supply that name:
</p>
<pre class="programlisting">
using gcc : : g++-3.2 ;
</pre>
<p>
Otherwise, it might be necessary to supply the complete path to the
compiler executable:
</p>
<pre class="programlisting">
using msvc : : Z:/Programs/Microsoft Visual Studio/vc98/bin/cl ;
</pre>
<p>
Some Boost.Build toolsets will use that path to take additional
actions required before invoking the compiler, such as calling
vendor-supplied scripts to set up its required environment variables.
</p>
<p>To configure several versions of a toolset, simply invoke
the <code class="computeroutput">using</code> rule multiple times:
</p>
<pre class="programlisting">
using gcc : 3.3 ;
using gcc : 3.4 : g++-3.4 ;
using gcc : 3.2 : g++-3.2 ;
</pre>
<p>
Note that in the first call to
<code class="computeroutput">using</code>, the compiler found in the
<code class="envar">PATH</code> will be used, and there's no need to
explicitly specify the command.
</p>
<p>As shown above, both the <em class="parameter"><code>version</code></em> and <em class="parameter"><code>invocation-command</code></em> parameters are
optional, but there's an important restriction: if you configure
the same toolset more than once, you must pass the <em class="parameter"><code>version</code></em>
parameter every time. For example, the following is not allowed:
</p>
<pre class="programlisting">
using gcc ;
using gcc : 3.4 : g++-3.4 ;
</pre>
<p>
because the first <code class="computeroutput">using</code> call does
not specify a <em class="parameter"><code>version</code></em>.
</p>
<p>The <em class="parameter"><code>options</code></em>
parameter is used to fine-tune the configuration. All of
Boost.Build's standard compiler toolsets accept properties of the
four builtin features <code class="varname">cflags</code>,
<code class="varname">cxxflags</code>, <code class="varname">compileflags</code> and
<code class="varname">linkflags</code> as <em class="parameter"><code>options</code></em> specifying flags that will be
always passed to the corresponding tools. Values of the
<code class="varname">cflags</code> feature are passed directly to the C
compiler, values of the <code class="varname">cxxflags</code> feature are
passed directly to the C++ compiler, and values of the
<code class="varname">compileflags</code> feature are passed to both. For
example, to configure a <span><strong class="command">gcc</strong></span> toolset so that it
always generates 64-bit code you could write:
</p>
<pre class="programlisting">
using gcc : 3.4 : : <compileflags>-m64 <linkflags>-m64 ;
</pre>
</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="../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="advanced/jamfiles.html"><img src="../images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
