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
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Definitions</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="../reference.html" title="Chapter7.Detailed reference">
<link rel="prev" href="buildprocess.html" title="Build process">
<link rel="next" href="generators.html" title="Generators">
</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="buildprocess.html"><img src="../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="generators.html"><img src="../../../../doc/html/images/next.png" alt="Next"></a>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="bbv2.reference.definitions"></a>Definitions</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="definitions.html#bbv2.reference.features">Features and properties</a></span></dt>
<dt><span class="section"><a href="definitions.html#bbv2.reference.variants">Build Variants</a></span></dt>
<dt><span class="section"><a href="definitions.html#bbv2.reference.variants.proprefine">Property refinement</a></span></dt>
<dt><span class="section"><a href="definitions.html#bbv2.reference.variants.propcond">Conditional properties</a></span></dt>
<dt><span class="section"><a href="definitions.html#bbv2.reference.ids">Target identifiers and references</a></span></dt>
</dl></div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.reference.features"></a>Features and properties</h3></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="definitions.html#bbv2.reference.features.validity">Property Validity</a></span></dt>
<dt><span class="section"><a href="definitions.html#bbv2.reference.features.attributes">Feature Attributes</a></span></dt>
<dt><span class="section"><a href="definitions.html#bbv2.reference.features.declaration">Feature Declaration</a></span></dt>
</dl></div>
<p>A <span class="emphasis"><em>feature</em></span> is a normalized (toolset-independent)
aspect of a build configuration, such as whether inlining is
enabled. Feature names may not contain the '<code class="literal">></code>'
character.</p>
<p>Each feature in a build configuration has one or more
associated <span class="emphasis"><em>value</em></span>s. Feature values for non-free features
may not contain the '<code class="literal"><</code>', '<code class="literal">:</code>', or
'<code class="literal">=</code>' characters. Feature values for free features may not
contain the '<code class="literal"><</code>' character.</p>
<p>A <span class="emphasis"><em>property</em></span> is a (feature,value) pair, expressed as
<feature>value.</p>
<p>A <span class="emphasis"><em>subfeature</em></span> is a feature that only exists in the
presence of its parent feature, and whose identity can be derived
(in the context of its parent) from its value. A subfeature's
parent can never be another subfeature. Thus, features and their
subfeatures form a two-level hierarchy.</p>
<p>A <span class="emphasis"><em>value-string</em></span> for a feature <span class="bold"><strong>F</strong></span> is a string of
the form
<code class="literal">value-subvalue1-subvalue2</code>...<code class="literal">-subvalueN</code>, where
<code class="literal">value</code> is a legal value for <span class="bold"><strong>F</strong></span> and
<code class="literal">subvalue1</code>...<code class="literal">subvalueN</code> are legal values of some
of <span class="bold"><strong>F</strong></span>'s subfeatures. For example, the properties
<code class="literal"><toolset>gcc <toolset-version>3.0.1</code> can be
expressed more conscisely using a value-string, as
<code class="literal"><toolset>gcc-3.0.1</code>.</p>
<p>A <span class="emphasis"><em>property set</em></span> is a set of properties (i.e. a
collection without duplicates), for instance:
<code class="literal"><toolset>gcc <runtime-link>static</code>.</p>
<p>A <span class="emphasis"><em>property path</em></span> is a property set whose elements have
been joined into a single string separated by slashes. A property
path representation of the previous example would be
<code class="literal"><toolset>gcc/<runtime-link>static</code>.</p>
<p>A <span class="emphasis"><em>build specification</em></span> is a property set that fully
describes the set of features used to build a target.</p>
<div class="section" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="bbv2.reference.features.validity"></a>Property Validity</h4></div></div></div>
<p>
For <a href="definitions.html#bbv2.reference.features.attributes.free">free</a>
features, all values are valid. For all other features,
the valid values are explicitly specified, and the build
system will report an error for the use of an invalid
feature-value. Subproperty validity may be restricted so
that certain values are valid only in the presence of
certain other subproperties. For example, it is possible
to specify that the <code class="computeroutput"><gcc-target>mingw</code>
property is only valid in the presence of
<code class="computeroutput"><gcc-version>2.95.2</code>.
</p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="bbv2.reference.features.attributes"></a>Feature Attributes</h4></div></div></div>
<p>Each feature has a collection of zero or more of the following
attributes. Feature attributes are low-level descriptions of how the
build system should interpret a feature's values when they appear in
a build request. We also refer to the attributes of properties, so
that an <span class="emphasis"><em>incidental</em></span> property, for example, is
one whose feature has the <span class="emphasis"><em>incidental</em></span>
attribute.</p>
<div class="itemizedlist"><ul type="disc">
<li>
<p><span class="emphasis"><em>incidental</em></span></p>
<p>Incidental features are assumed not to affect build
products at all. As a consequence, the build system may use
the same file for targets whose build specification differs
only in incidental features. A feature that controls a
compiler's warning level is one example of a likely
incidental feature.</p>
<p>Non-incidental features are assumed to affect build
products, so the files for targets whose build specification
differs in non-incidental features are placed in different
directories as described in "target paths" below. [ where? ]
</p>
</li>
<li>
<p>
<a name="bbv2.reference.features.attributes.propagated"></a>
<span class="emphasis"><em>propagated</em></span>
</p>
<p>Features of this kind are
propagated to dependencies. That is, if a <a href="../advanced/targets.html#bbv2.advanced.targets.main">main target</a> is built using a
propagated
property, the build systems attempts to use the same property
when building any of its dependencies as part of that main
target. For instance, when an optimized exectuable is
requested, one usually wants it to be linked with optimized
libraries. Thus, the <code class="literal"><optimization></code> feature is
propagated.</p>
</li>
<li>
<p>
<a name="bbv2.reference.features.attributes.free"></a>
<span class="emphasis"><em>free</em></span>
</p>
<p>Most features have a finite set of allowed values, and can
only take on a single value from that set in a given build
specification. Free features, on the other hand, can have
several values at a time and each value can be an arbitrary
string. For example, it is possible to have several
preprocessor symbols defined simultaneously:</p>
<pre class="programlisting">
<define>NDEBUG=1 <define>HAS_CONFIG_H=1
</pre>
</li>
<li>
<p><span class="emphasis"><em>optional</em></span></p>
<p>An optional feature is a feature that is not required to
appear in a build specification. Every non-optional non-free
feature has a default value that is used when a value for
the feature is not otherwise specified, either in a target's
requirements or in the user's build request. [A feature's
default value is given by the first value listed in the
feature's declaration. -- move this elsewhere - dwa]</p>
</li>
<li>
<p><span class="emphasis"><em>symmetric</em></span></p>
<p>A symmetric feature's default value is not automatically
included in <a href="definitions.html#bbv2.reference.variants" title="Build Variants">build variants</a>. Normally
a feature only generates a subvariant directory when its
value differs from the value specified by the build variant,
leading to an assymmetric subvariant directory structure for
certain values of the feature. A symmetric feature, when
relevant to the toolset, always generates a corresponding
subvariant directory.</p>
</li>
<li>
<p><span class="emphasis"><em>path</em></span></p>
<p>The value of a path feature specifies a path. The path is
treated as relative to the directory of Jamfile where path
feature is used and is translated appropriately by the build
system when the build is invoked from a different
directory</p>
</li>
<li>
<p><span class="emphasis"><em>implicit</em></span></p>
<p>Values of implicit features alone identify the feature.
For example, a user is not required to write
"<toolset>gcc", but can simply write "gcc". Implicit
feature names also don't appear in variant paths, although
the values do. Thus: bin/gcc/... as opposed to
bin/toolset-gcc/.... There should typically be only a few
such features, to avoid possible name clashes.</p>
</li>
<li>
<p><span class="emphasis"><em>composite</em></span></p>
<p>Composite features actually correspond to groups of
properties. For example, a build variant is a composite
feature. When generating targets from a set of build
properties, composite features are recursively expanded and
<span class="emphasis"><em>added</em></span> to the build property set, so rules can find
them if necessary. Non-composite non-free features override
components of composite features in a build property set.</p>
</li>
<li>
<p><span class="emphasis"><em>dependency</em></span></p>
<p>The value of dependency feature if a target reference.
When used for building of a main target, the value of
dependency feature is treated as additional dependency.</p>
<p>For example, dependency features allow to state that
library A depends on library B. As the result, whenever an
application will link to A, it will also link to B.
Specifying B as dependency of A is different from adding B to
the sources of A. </p>
</li>
</ul></div>
<p>Features that are neither free nor incidental are called
<span class="emphasis"><em>base</em></span> features.</p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="bbv2.reference.features.declaration"></a>Feature Declaration</h4></div></div></div>
<p>The low-level feature declaration interface is the
<code class="literal">feature</code> rule from the
<code class="literal">feature</code> module:
</p>
<pre class="programlisting">
rule feature ( name : allowed-values * : attributes * )
</pre>
<p>
A feature's allowed-values may be extended with the
<code class="computeroutput">feature.extend</code> rule.
</p>
</div>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.reference.variants"></a>Build Variants</h3></div></div></div>
<p>
A build variant, or (simply variant) is a special kind of composite
feature that automatically incorporates the default values of
features that . Typically you'll want at least two separate
variants: one for debugging, and one for your release code. [
Volodya says: "Yea, we'd need to mention that it's a composite
feature and describe how they are declared, in pacticular that
default values of non-optional features are incorporated into
build variant automagically. Also, do we wan't some variant
inheritance/extension/templates. I don't remember how it works in
V1, so can't document this for V2.". Will clean up soon -DWA ]
</p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.reference.variants.proprefine"></a>Property refinement</h3></div></div></div>
<p>When a target with certain properties is requested, and that
target requires some set of properties, it is needed to find the
set of properties to use for building. This process is called
<span class="emphasis"><em>property refinement</em></span> and is performed by these rules</p>
<div class="orderedlist"><ol type="1">
<li>
Each property in the required set is added to the original
property set
</li>
<li>
If the original property set includes property with a different
value of non free feature, that property is removed.
</li>
</ol></div>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.reference.variants.propcond"></a>Conditional properties</h3></div></div></div>
<p>Sometime it's desirable to apply certain requirements only for
a specific combination of other properties. For example, one of
compilers that you use issues a pointless warning that you want to
suppress by passing a command line option to it. You would not
want to pass that option to other compilers. Conditional
properties allow you to do just that. Their syntax is:</p>
<pre class="programlisting">
property ( "," property ) * ":" property
</pre>
<p>
For example, the problem above would be solved by:
</p>
<pre class="programlisting">
exe hello : hello.cpp : <toolset>yfc:<cxxflags>-disable-pointless-warning ;
</pre>
<p>
</p>
<p>The syntax also allows several properties in the condition, for
example:
</p>
<pre class="programlisting">
exe hello : hello.cpp : <os>NT,<toolset>gcc:<link>static ;
</pre>
<p>
</p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.reference.ids"></a>Target identifiers and references</h3></div></div></div>
<p><span class="emphasis"><em>Target identifier</em></span> is used to denote a
target. The syntax is:</p>
<pre class="programlisting">
target-id -> (project-id | target-name | file-name )
| (project-id | directory-name) "//" target-name
project-id -> path
target-name -> path
file-name -> path
directory-name -> path
</pre>
<p>
This grammar allows some elements to be recognized as either
</p>
<div class="itemizedlist"><ul type="disc">
<li>
project id (at this point, all project ids start with slash).
</li>
<li>
name of target declared in current Jamfile (note that target
names may include slash).
</li>
<li>
a regular file, denoted by absolute name or name relative to
project's sources location.
</li>
</ul></div>
<p>
To determine the real meaning a check is made if project-id
by the specified name exists, and then if main target of that
name exists. For example, valid target ids might be:
</p>
<pre class="screen">
a -- target in current project
lib/b.cpp -- regular file
/boost/thread -- project "/boost/thread"
/home/ghost/build/lr_library//parser -- target in specific project
</pre>
<p>
</p>
<p><span class="bold"><strong>Rationale:</strong></span>Target is separated from project by special
separator (not just slash), because:</p>
<div class="itemizedlist"><ul type="disc">
<li>
It emphasises that projects and targets are different things.
</li>
<li>
It allows to have main target names with slashes.
</li>
</ul></div>
<p><a name="bbv2.reference.targets.references"></a>
<span class="emphasis"><em>Target reference</em></span> is used to
specify a source target, and may additionally specify desired
properties for that target. It has this syntax:</p>
<pre class="programlisting">
target-reference -> target-id [ "/" requested-properties ]
requested-properties -> property-path
</pre>
<p>
For example,
</p>
<pre class="programlisting">
exe compiler : compiler.cpp libs/cmdline/<optimization>space ;
</pre>
<p>
would cause the version of <code class="literal">cmdline</code> library,
optimized for space, to be linked in even if the
<code class="literal">compiler</code> executable is build with optimization for
speed.
</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="buildprocess.html"><img src="../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="generators.html"><img src="../../../../doc/html/images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
