Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/doc/html/bbv2/tutorial/properties.html @ 12

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

added boost
File size: 8.7 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Properties</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="../tutorial.html" title="Chapter 23. Tutorial">
18<link rel="prev" href="../tutorial.html" title="Chapter 23. Tutorial">
19<link rel="next" href="hierarchy.html" title="Project Hierarchies">
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="../tutorial.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.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="hierarchy.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.tutorial.properties"></a>Properties</h2></div></div></div>
37<div class="toc"><dl>
38<dt><span class="section"><a href="properties.html#bbv2.tutorial.properties.requirements">Build Requests and Target Requirements</a></span></dt>
39<dt><span class="section"><a href="properties.html#bbv2.tutorial.properties.project_attributes">Project Attributes</a></span></dt>
40</dl></div>
41<p>
42      To portably represent aspects of target configuration such as
43      debug and release variants, or single- and multi-threaded
44      builds, Boost.Build uses <em class="firstterm">features</em> with
45      associated <em class="firstterm">values</em>.  For
46      example, the <code class="computeroutput">debug-symbols</code> feature can have a value of <code class="computeroutput">on</code> or
47      <code class="computeroutput">off</code>.  A <em class="firstterm">property</em> is just a (feature,
48      value) pair.  When a user initiates a build, Boost.Build
49      automatically translates the requested properties into appropriate
50      command-line flags for invoking toolset components like compilers
51      and linkers.</p>
52<p>There are many built-in features that can be combined to
53      produce arbitrary build configurations.  The following command
54      builds the project's <code class="computeroutput">release</code> variant with inlining
55      disabled and debug symbols enabled:
56
57</p>
58<pre class="screen">
59bjam release inlining=off debug-symbols=on
60</pre>
61<p>Properties on the command-line are specified with the syntax:
62
63</p>
64<pre class="screen"><em class="replaceable"><code>feature-name</code></em>=<em class="replaceable"><code>feature-value</code></em></pre>
65<p>The <code class="option">release</code> and <code class="option">debug</code> that we've seen
66      in <span><strong class="command">bjam</strong></span> invocations are just a shorthand way to
67      specify values of the <code class="varname">variant</code> feature.  For example, the command
68      above could also have been written this way:
69
70      </p>
71<pre class="screen">
72bjam variant=release inlining=off debug-symbols=on
73      </pre>
74<p><code class="varname">variant</code> is so commonly-used that it has
75      been given special status as an <em class="firstterm">implicit</em>
76      feature&#8212;Boost.Build will deduce the its identity just
77      from the name of one of its values.
78    </p>
79<p>
80      A complete description of features can be found in <a href="../reference/definitions.html#bbv2.reference.features" title="Features and properties">the section called &#8220;Features and properties&#8221;</a>.
81    </p>
82<div class="section" lang="en">
83<div class="titlepage"><div><div><h3 class="title">
84<a name="bbv2.tutorial.properties.requirements"></a>Build Requests and Target Requirements</h3></div></div></div>
85<p>     
86        The set of properties specified on the command line constitute
87        a <em class="firstterm">build request</em>&#8212;a description of
88        the desired properties for building the requested targets (or,
89        if no targets were explicitly requested, the project in the
90        current directory).  The <span class="emphasis"><em>actual</em></span>
91        properties used for building targets are typically a
92        combination of the build request and properties derived from
93        the project's <code class="filename">Jamroot</code> (and its other
94        Jamfiles, as described in <a href="hierarchy.html" title="Project Hierarchies">the section called &#8220;Project Hierarchies&#8221;</a>).  For example, the
95        locations of <code class="computeroutput">#include</code>d header files are normally
96        not specified on the command-line, but described in
97        Jamfiles as <em class="firstterm">target
98        requirements</em> and automatically combined with the
99        build request for those targets.  Multithread-enabled
100        compilation is another example of a typical target
101        requirement.  The Jamfile fragment below
102        illustrates how these requirements might be specified.
103      </p>
104<pre class="programlisting">
105exe hello
106    : hello.cpp
107    : &lt;include&gt;boost &lt;threading&gt;multi
108    ;
109</pre>
110<p> 
111        When <code class="filename">hello</code> is built, the two
112        requirements specified above will always be present.
113        If the build request given on the <span><strong class="command">bjam</strong></span>
114        command-line explictly contradicts a target's requirements,
115        the target requirements usually override (or, in the case of
116        &#8220;free&#8221;&#8221; features like
117        <code class="varname">&lt;include&gt;</code>,
118        <sup>[<a name="id2854170" href="#ftn.id2854170">4</a>]</sup>
119        augments) the build request.
120
121      </p>
122<div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;">
123<h3 class="title">Tip</h3>
124<p>The value of the <code class="varname">&lt;include&gt;</code> feature is
125          relative to the location of <code class="filename">Jamroot</code> where it's
126          used.
127        </p>
128</div>
129</div>
130<div class="section" lang="en">
131<div class="titlepage"><div><div><h3 class="title">
132<a name="bbv2.tutorial.properties.project_attributes"></a>Project Attributes</h3></div></div></div>
133<p>
134        If we want the same requirements for our other
135        target, <code class="filename">hello2</code>, we could simply duplicate
136        them.  However, as projects grow, that approach leads to a great
137        deal of repeated boilerplate in Jamfiles.
138       
139        Fortunately, there's a better way. Each project can specify a
140        set of <em class="firstterm">attributes</em>, including
141        requirements:
142
143</p>
144<pre class="programlisting">
145project
146    : requirements &lt;include&gt;/home/ghost/Work/boost &lt;threading&gt;multi
147    ;
148
149exe hello : hello.cpp ;
150exe hello2 : hello.cpp ;
151</pre>
152<p>
153
154        The effect would be as if we specified the same requirement for
155        both <code class="filename">hello</code> and <code class="filename">hello2</code>.
156      </p>
157</div>
158<div class="footnotes">
159<br><hr width="100" align="left">
160<div class="footnote"><p><sup>[<a name="ftn.id2854170" href="#id2854170">4</a>] </sup>
161See <a href="../reference/definitions.html#bbv2.reference.features.attributes" title="Feature Attributes">the section called &#8220;Feature Attributes&#8221;</a></p></div>
162</div>
163</div>
164<table width="100%"><tr>
165<td align="left"></td>
166<td align="right"><small></small></td>
167</tr></table>
168<hr>
169<div class="spirit-nav">
170<a accesskey="p" href="../tutorial.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.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="hierarchy.html"><img src="../../images/next.png" alt="Next"></a>
171</div>
172</body>
173</html>
Note: See TracBrowser for help on using the repository browser.