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
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Properties</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="../tutorial.html" title="Chapter3.Tutorial">
<link rel="prev" href="../tutorial.html" title="Chapter3.Tutorial">
<link rel="next" href="hierarchy.html" title="Project Hierarchies">
</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.html"><img src="../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.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="hierarchy.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.tutorial.properties"></a>Properties</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="properties.html#bbv2.tutorial.properties.requirements">Build Requests and Target Requirements</a></span></dt>
<dt><span class="section"><a href="properties.html#bbv2.tutorial.properties.project_attributes">Project Attributes</a></span></dt>
</dl></div>
<p>
To portably represent aspects of target configuration such as
debug and release variants, or single- and multi-threaded
builds, Boost.Build uses <em class="firstterm">features</em> with
associated <em class="firstterm">values</em>. For
example, the <code class="computeroutput">debug-symbols</code> feature can have a value of <code class="computeroutput">on</code> or
<code class="computeroutput">off</code>. A <em class="firstterm">property</em> is just a (feature,
value) pair. When a user initiates a build, Boost.Build
automatically translates the requested properties into appropriate
command-line flags for invoking toolset components like compilers
and linkers.</p>
<p>There are many built-in features that can be combined to
produce arbitrary build configurations. The following command
builds the project's <code class="computeroutput">release</code> variant with inlining
disabled and debug symbols enabled:
</p>
<pre class="screen">
bjam release inlining=off debug-symbols=on
</pre>
<p>
</p>
<p>Properties on the command-line are specified with the syntax:
</p>
<pre class="screen">
<em class="replaceable"><code>feature-name</code></em>=<em class="replaceable"><code>feature-value</code></em>
</pre>
<p>
</p>
<p>The <code class="option">release</code> and <code class="option">debug</code> that we've seen
in <span><strong class="command">bjam</strong></span> invocations are just a shorthand way to
specify values of the <code class="varname">variant</code> feature. For example, the command
above could also have been written this way:
</p>
<pre class="screen">
bjam variant=release inlining=off debug-symbols=on
</pre>
<p>
</p>
<p> <code class="varname">variant</code> is so commonly-used that it has
been given special status as an <em class="firstterm">implicit</em>
feature—Boost.Build will deduce the its identity just
from the name of one of its values.
</p>
<p>
A complete description of features can be found in <a href="../reference/definitions.html#bbv2.reference.features" title="Features and properties">the section called “Features and properties”</a>.
</p>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.tutorial.properties.requirements"></a>Build Requests and Target Requirements</h3></div></div></div>
<p>
The set of properties specified on the command line constitute
a <em class="firstterm">build request</em>—a description of
the desired properties for building the requested targets (or,
if no targets were explicitly requested, the project in the
current directory). The <span class="emphasis"><em>actual</em></span>
properties used for building targets are typically a
combination of the build request and properties derived from
the project's <code class="filename">Jamroot</code> (and its other
Jamfiles, as described in <a href="hierarchy.html" title="Project Hierarchies">the section called “Project Hierarchies”</a>). For example, the
locations of <code class="computeroutput">#include</code>d header files are normally
not specified on the command-line, but described in
Jamfiles as <em class="firstterm">target
requirements</em> and automatically combined with the
build request for those targets. Multithread-enabled
compilation is another example of a typical target
requirement. The Jamfile fragment below
illustrates how these requirements might be specified.
</p>
<pre class="programlisting">
exe hello
: hello.cpp
: <include>boost <threading>multi
;
</pre>
<p>
When <code class="filename">hello</code> is built, the two
requirements specified above will always be present.
If the build request given on the <span><strong class="command">bjam</strong></span>
command-line explictly contradicts a target's requirements,
the target requirements usually override (or, in the case of
“free”” features like
<code class="varname"><include></code>,
<sup>[<a name="id2585522" href="#ftn.id2585522">3</a>]</sup>
augments) the build request.
</p>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../doc/html/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top"><p>The value of the <code class="varname"><include></code> feature is
relative to the location of <code class="filename">Jamroot</code> where it's
used.
</p></td></tr>
</table></div>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.tutorial.properties.project_attributes"></a>Project Attributes</h3></div></div></div>
<p>
If we want the same requirements for our other
target, <code class="filename">hello2</code>, we could simply duplicate
them. However, as projects grow, that approach leads to a great
deal of repeated boilerplate in Jamfiles.
Fortunately, there's a better way. Each project can specify a
set of <em class="firstterm">attributes</em>, including
requirements:
</p>
<pre class="programlisting">
project
: requirements <include>/home/ghost/Work/boost <threading>multi
;
exe hello : hello.cpp ;
exe hello2 : hello.cpp ;
</pre>
<p>
The effect would be as if we specified the same requirement for
both <code class="filename">hello</code> and <code class="filename">hello2</code>.
</p>
</div>
<div class="footnotes">
<br><hr width="100" align="left">
<div class="footnote"><p><sup>[<a name="ftn.id2585522" href="#id2585522">3</a>] </sup>
See <a href="../reference/definitions.html#bbv2.reference.features.attributes" title="Feature Attributes">the section called “Feature Attributes”</a>
</p></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="../tutorial.html"><img src="../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.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="hierarchy.html"><img src="../../../../doc/html/images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
