Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/doc/html/bbv2/reference/definitions.html @ 12

Last change on this file since 12 was 12, checked in by landauf, 18 years ago

added boost
File size: 19.4 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Definitions</title>
5<link rel="stylesheet" href="../../boostbook.css" type="text/css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
7<style type="text/css">
8body { background-image: url('http://docbook.sourceforge.net/release/images/draft.png');
9       background-repeat: no-repeat;
10       background-position: top left;
11       /* The following properties make the watermark "fixed" on the page. */
12       /* I think that's just a bit too distracting for the reader... */
13       /* background-attachment: fixed; */
14       /* background-position: center center; */
15     }</style>
16<link rel="start" href="../../index.html" title="The Boost C++ Libraries">
17<link rel="up" href="../reference.html" title="Chapter 26. Detailed reference">
18<link rel="prev" href="buildprocess.html" title="Build process">
19<link rel="next" href="generators.html" title="Generators">
20</head>
21<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
22<table cellpadding="2" width="100%">
23<td valign="top"><img alt="boost.png (6897 bytes)" width="277" height="86" src="../../../../boost.png"></td>
24<td align="center"><a href="../../../../index.htm">Home</a></td>
25<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
26<td align="center"><a href="../../../../people/people.htm">People</a></td>
27<td align="center"><a href="../../../../more/faq.htm">FAQ</a></td>
28<td align="center"><a href="../../../../more/index.htm">More</a></td>
29</table>
30<hr>
31<div class="spirit-nav">
32<a accesskey="p" href="buildprocess.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="generators.html"><img src="../../images/next.png" alt="Next"></a>
33</div>
34<div class="section" lang="en">
35<div class="titlepage"><div><div><h2 class="title" style="clear: both">
36<a name="bbv2.reference.definitions"></a>Definitions</h2></div></div></div>
37<div class="toc"><dl>
38<dt><span class="section"><a href="definitions.html#bbv2.reference.features">Features and properties</a></span></dt>
39<dt><span class="section"><a href="definitions.html#bbv2.reference.variants">Build Variants</a></span></dt>
40<dt><span class="section"><a href="definitions.html#bbv2.reference.variants.proprefine">Property refinement</a></span></dt>
41<dt><span class="section"><a href="definitions.html#bbv2.reference.variants.propcond">Conditional properties</a></span></dt>
42<dt><span class="section"><a href="definitions.html#bbv2.reference.ids">Target identifiers and references</a></span></dt>
43</dl></div>
44<div class="section" lang="en">
45<div class="titlepage"><div><div><h3 class="title">
46<a name="bbv2.reference.features"></a>Features and properties</h3></div></div></div>
47<div class="toc"><dl>
48<dt><span class="section"><a href="definitions.html#bbv2.reference.features.validity">Property Validity</a></span></dt>
49<dt><span class="section"><a href="definitions.html#bbv2.reference.features.attributes">Feature Attributes</a></span></dt>
50<dt><span class="section"><a href="definitions.html#bbv2.reference.features.declaration">Feature Declaration</a></span></dt>
51</dl></div>
52<p>A <span class="emphasis"><em>feature</em></span> is a normalized (toolset-independent)
53        aspect of a build configuration, such as whether inlining is
54        enabled. Feature names may not contain the '<code class="literal">&gt;</code>'
55        character.</p>
56<p>Each feature in a build configuration has one or more
57        associated <span class="emphasis"><em>value</em></span>s. Feature values for non-free features
58        may not contain the '<code class="literal">&lt;</code>', '<code class="literal">:</code>', or
59        '<code class="literal">=</code>' characters. Feature values for free features may not
60        contain the '<code class="literal">&lt;</code>' character.</p>
61<p>A <span class="emphasis"><em>property</em></span> is a (feature,value) pair, expressed as
62        &lt;feature&gt;value.</p>
63<p>A <span class="emphasis"><em>subfeature</em></span> is a feature that only exists in the
64        presence of its parent feature, and whose identity can be derived
65        (in the context of its parent) from its value. A subfeature's
66        parent can never be another subfeature. Thus, features and their
67        subfeatures form a two-level hierarchy.</p>
68<p>A <span class="emphasis"><em>value-string</em></span> for a feature <span class="bold"><strong>F</strong></span> is a string of
69        the form
70        <code class="literal">value-subvalue1-subvalue2</code>...<code class="literal">-subvalueN</code>, where
71        <code class="literal">value</code> is a legal value for <span class="bold"><strong>F</strong></span> and
72        <code class="literal">subvalue1</code>...<code class="literal">subvalueN</code> are legal values of some
73        of <span class="bold"><strong>F</strong></span>'s subfeatures. For example, the properties
74        <code class="literal">&lt;toolset&gt;gcc &lt;toolset-version&gt;3.0.1</code> can be
75        expressed more conscisely using a value-string, as
76        <code class="literal">&lt;toolset&gt;gcc-3.0.1</code>.</p>
77<p>A <span class="emphasis"><em>property set</em></span> is a set of properties (i.e. a
78        collection without duplicates), for instance:
79        <code class="literal">&lt;toolset&gt;gcc &lt;runtime-link&gt;static</code>.</p>
80<p>A <span class="emphasis"><em>property path</em></span> is a property set whose elements have
81        been joined into a single string separated by slashes. A property
82        path representation of the previous example would be
83        <code class="literal">&lt;toolset&gt;gcc/&lt;runtime-link&gt;static</code>.</p>
84<p>A <span class="emphasis"><em>build specification</em></span> is a property set that fully
85        describes the set of features used to build a target.</p>
86<div class="section" lang="en">
87<div class="titlepage"><div><div><h4 class="title">
88<a name="bbv2.reference.features.validity"></a>Property Validity</h4></div></div></div>
89<p>
90          For <a href="definitions.html#bbv2.reference.features.attributes.free">free</a>
91            features, all values are valid. For all other features,
92          the valid values are explicitly specified, and the build
93          system will report an error for the use of an invalid
94          feature-value. Subproperty validity may be restricted so
95          that certain values are valid only in the presence of
96          certain other subproperties. For example, it is possible
97          to specify that the <code class="computeroutput">&lt;gcc-target&gt;mingw</code>
98          property is only valid in the presence of
99          <code class="computeroutput">&lt;gcc-version&gt;2.95.2</code>.
100        </p>
101</div>
102<div class="section" lang="en">
103<div class="titlepage"><div><div><h4 class="title">
104<a name="bbv2.reference.features.attributes"></a>Feature Attributes</h4></div></div></div>
105<p>Each feature has a collection of zero or more of the following
106          attributes. Feature attributes are low-level descriptions of how the
107          build system should interpret a feature's values when they appear in
108          a build request. We also refer to the attributes of properties, so
109          that an <span class="emphasis"><em>incidental</em></span> property, for example, is
110          one whose feature has the <span class="emphasis"><em>incidental</em></span>
111          attribute.</p>
112<div class="itemizedlist"><ul type="disc">
113<li>
114<p><span class="emphasis"><em>incidental</em></span></p>
115<p>Incidental features are assumed not to affect build
116              products at all. As a consequence, the build system may use
117              the same file for targets whose build specification differs
118              only in incidental features. A feature that controls a
119              compiler's warning level is one example of a likely
120              incidental feature.</p>
121<p>Non-incidental features are assumed to affect build
122              products, so the files for targets whose build specification
123              differs in non-incidental features are placed in different
124              directories as described in "target paths" below. [ where? ]
125            </p>
126</li>
127<li>
128<p><a name="bbv2.reference.features.attributes.propagated"></a><span class="emphasis"><em>propagated</em></span></p>
129<p>Features of this kind are
130              propagated to dependencies. That is, if a <a href="../advanced/jamfiles.html#bbv2.advanced.targets.main">main target</a> is built using a
131              propagated
132              property, the build systems attempts to use the same property
133              when building any of its dependencies as part of that main
134              target. For instance, when an optimized exectuable is
135              requested, one usually wants it to be linked with optimized
136              libraries. Thus, the <code class="literal">&lt;optimization&gt;</code> feature is
137              propagated.</p>
138</li>
139<li>
140<p><a name="bbv2.reference.features.attributes.free"></a><span class="emphasis"><em>free</em></span></p>
141<p>Most features have a finite set of allowed values, and can
142              only take on a single value from that set in a given build
143              specification. Free features, on the other hand, can have
144              several values at a time and each value can be an arbitrary
145              string. For example, it is possible to have several
146              preprocessor symbols defined simultaneously:</p>
147<pre class="programlisting">
148&lt;define&gt;NDEBUG=1 &lt;define&gt;HAS_CONFIG_H=1
149</pre>
150</li>
151<li>
152<p><span class="emphasis"><em>optional</em></span></p>
153<p>An optional feature is a feature that is not required to
154              appear in a build specification. Every non-optional non-free
155              feature has a default value that is used when a value for
156              the feature is not otherwise specified, either in a target's
157              requirements or in the user's build request. [A feature's
158              default value is given by the first value listed in the
159              feature's declaration. -- move this elsewhere - dwa]</p>
160</li>
161<li>
162<p><span class="emphasis"><em>symmetric</em></span></p>
163<p>A symmetric feature's default value is not automatically
164              included in <a href="definitions.html#bbv2.reference.variants" title="Build Variants">build variants</a>.  Normally
165              a feature only generates a subvariant directory when its
166              value differs from the value specified by the build variant,
167              leading to an assymmetric subvariant directory structure for
168              certain values of the feature. A symmetric feature, when
169              relevant to the toolset, always generates a corresponding
170              subvariant directory.</p>
171</li>
172<li>
173<p><span class="emphasis"><em>path</em></span></p>
174<p>The value of a path feature specifies a path. The path is
175              treated as relative to the directory of Jamfile where path
176              feature is used and is translated appropriately by the build
177              system when the build is invoked from a different
178              directory</p>
179</li>
180<li>
181<p><span class="emphasis"><em>implicit</em></span></p>
182<p>Values of implicit features alone identify the feature.
183              For example, a user is not required to write
184              "&lt;toolset&gt;gcc", but can simply write "gcc". Implicit
185              feature names also don't appear in variant paths, although
186              the values do. Thus: bin/gcc/... as opposed to
187              bin/toolset-gcc/.... There should typically be only a few
188              such features, to avoid possible name clashes.</p>
189</li>
190<li>
191<p><span class="emphasis"><em>composite</em></span></p>
192<p>Composite features actually correspond to groups of
193              properties. For example, a build variant is a composite
194              feature. When generating targets from a set of build
195              properties, composite features are recursively expanded and
196              <span class="emphasis"><em>added</em></span> to the build property set, so rules can find
197              them if necessary. Non-composite non-free features override
198              components of composite features in a build property set.</p>
199</li>
200<li>
201<p><span class="emphasis"><em>dependency</em></span></p>
202<p>The value of dependency feature if a target reference.
203              When used for building of a main target, the value of
204              dependency feature is treated as additional dependency.</p>
205<p>For example, dependency features allow to state that
206              library A depends on library B. As the result, whenever an
207              application will link to A, it will also link to B.
208              Specifying B as dependency of A is different from adding B to
209              the sources of A. </p>
210</li>
211</ul></div>
212<p>Features that are neither free nor incidental are called
213          <span class="emphasis"><em>base</em></span> features.</p>
214</div>
215<div class="section" lang="en">
216<div class="titlepage"><div><div><h4 class="title">
217<a name="bbv2.reference.features.declaration"></a>Feature Declaration</h4></div></div></div>
218<p>The low-level feature declaration interface is the
219          <code class="literal">feature</code> rule from the
220          <code class="literal">feature</code> module:
221         
222</p>
223<pre class="programlisting">
224rule feature ( name : allowed-values * : attributes * )
225</pre>
226<p>
227         
228          A feature's allowed-values may be extended with the
229          <code class="computeroutput">feature.extend</code> rule.
230        </p>
231</div>
232</div>
233<div class="section" lang="en">
234<div class="titlepage"><div><div><h3 class="title">
235<a name="bbv2.reference.variants"></a>Build Variants</h3></div></div></div>
236<p>
237        A build variant, or (simply variant) is a special kind of composite
238        feature that automatically incorporates the default values of
239        features that . Typically you'll want at least two separate
240        variants: one for debugging, and one for your release code. [
241        Volodya says: "Yea, we'd need to mention that it's a composite
242        feature and describe how they are declared, in pacticular that
243        default values of non-optional features are incorporated into
244        build variant automagically. Also, do we wan't some variant
245        inheritance/extension/templates. I don't remember how it works in
246        V1, so can't document this for V2.". Will clean up soon -DWA ]
247      </p>
248</div>
249<div class="section" lang="en">
250<div class="titlepage"><div><div><h3 class="title">
251<a name="bbv2.reference.variants.proprefine"></a>Property refinement</h3></div></div></div>
252<p>When a target with certain properties is requested, and that
253        target requires some set of properties, it is needed to find the
254        set of properties to use for building. This process is called
255        <span class="emphasis"><em>property refinement</em></span> and is performed by these rules</p>
256<div class="orderedlist"><ol type="1">
257<li>
258            Each property in the required set is added to the original
259            property set
260          </li>
261<li>
262            If the original property set includes property with a different
263            value of non free feature, that property is removed.
264          </li>
265</ol></div>
266</div>
267<div class="section" lang="en">
268<div class="titlepage"><div><div><h3 class="title">
269<a name="bbv2.reference.variants.propcond"></a>Conditional properties</h3></div></div></div>
270<p>Sometime it's desirable to apply certain requirements only for
271        a specific combination of other properties. For example, one of
272        compilers that you use issues a pointless warning that you want to
273        suppress by passing a command line option to it. You would not
274        want to pass that option to other compilers. Conditional
275        properties allow you to do just that. Their syntax is:</p>
276<pre class="programlisting">
277        property ( "," property ) * ":" property
278      </pre>
279<p>
280        For example, the problem above would be solved by:
281
282</p>
283<pre class="programlisting">
284exe hello : hello.cpp : &lt;toolset&gt;yfc:&lt;cxxflags&gt;-disable-pointless-warning ;
285</pre>
286<p>The syntax also allows several properties in the condition, for
287        example:
288</p>
289<pre class="programlisting">
290exe hello : hello.cpp : &lt;os&gt;NT,&lt;toolset&gt;gcc:&lt;link&gt;static ;
291</pre>
292</div>
293<div class="section" lang="en">
294<div class="titlepage"><div><div><h3 class="title">
295<a name="bbv2.reference.ids"></a>Target identifiers and references</h3></div></div></div>
296<p><span class="emphasis"><em>Target identifier</em></span> is used to denote a
297        target. The syntax is:</p>
298<pre class="programlisting">
299target-id -&gt; (project-id | target-name | file-name )
300              | (project-id | directory-name) "//" target-name   
301project-id -&gt; path
302target-name -&gt; path
303file-name -&gt; path
304directory-name -&gt; path                 
305</pre>
306<p>
307        This grammar allows some elements to be recognized as either
308       
309        </p>
310<div class="itemizedlist"><ul type="disc">
311<li>
312              project id (at this point, all project ids start with slash).
313            </li>
314<li>
315              name of target declared in current Jamfile (note that target
316              names may include slash).
317            </li>
318<li>
319              a regular file, denoted by absolute name or name relative to
320              project's sources location.
321            </li>
322</ul></div>
323<p>
324
325        To determine the real meaning a check is made if project-id
326        by the specified name exists, and then if main target of that
327        name exists. For example, valid target ids might be:
328
329</p>
330<pre class="screen">
331a                                    -- target in current project
332lib/b.cpp                            -- regular file
333/boost/thread                        -- project "/boost/thread"
334/home/ghost/build/lr_library//parser -- target in specific project
335</pre>
336<p><span class="bold"><strong>Rationale:</strong></span>Target is separated from project by special
337        separator (not just slash), because:</p>
338<div class="itemizedlist"><ul type="disc">
339<li>
340            It emphasises that projects and targets are different things.
341          </li>
342<li>
343            It allows to have main target names with slashes.
344
345            </li>
346</ul></div>
347<p><a name="bbv2.reference.targets.references"></a><span class="emphasis"><em>Target reference</em></span> is used to
348        specify a source target, and may additionally specify desired
349        properties for that target. It has this syntax:</p>
350<pre class="programlisting">
351target-reference -&gt; target-id [ "/" requested-properties ]
352requested-properties -&gt; property-path
353</pre>
354<p>
355        For example,
356
357        </p>
358<pre class="programlisting">
359          exe compiler : compiler.cpp libs/cmdline/&lt;optimization&gt;space ;
360        </pre>
361<p>
362       
363        would cause the version of <code class="literal">cmdline</code> library,
364        optimized for space, to be linked in even if the
365        <code class="literal">compiler</code> executable is build with optimization for
366        speed.
367      </p>
368</div>
369</div>
370<table width="100%"><tr>
371<td align="left"></td>
372<td align="right"><small></small></td>
373</tr></table>
374<hr>
375<div class="spirit-nav">
376<a accesskey="p" href="buildprocess.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="generators.html"><img src="../../images/next.png" alt="Next"></a>
377</div>
378</body>
379</html>
Note: See TracBrowser for help on using the repository browser.