Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/doc/html/bbv2/tutorial.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 32.1 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Tutorial</title>
5<link rel="stylesheet" href="../boostbook.css" type="text/css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
7<link rel="start" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
8<link rel="up" href="../bbv2.html" title="Chapter 25. Boost.Build V2 User Manual">
9<link rel="prev" href="installation.html" title="Installation">
10<link rel="next" href="advanced.html" title="Overview">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13<table cellpadding="2" width="100%">
14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
15<td align="center"><a href="../../../index.htm">Home</a></td>
16<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
17<td align="center"><a href="../../../people/people.htm">People</a></td>
18<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
19<td align="center"><a href="../../../more/index.htm">More</a></td>
20</table>
21<hr>
22<div class="spirit-nav">
23<a accesskey="p" href="installation.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.html"><img src="../images/next.png" alt="Next"></a>
24</div>
25<div class="section" lang="en">
26<div class="titlepage"><div><div><h2 class="title" style="clear: both">
27<a name="bbv2.tutorial"></a>Tutorial</h2></div></div></div>
28<div class="toc"><dl>
29<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.hello">Hello, world</a></span></dt>
30<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.properties">Properties</a></span></dt>
31<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.hierarchy">Project Hierarchies</a></span></dt>
32<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.libs">Dependent Targets</a></span></dt>
33<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.testing">Testing</a></span></dt>
34<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.linkage">Static and shared libaries</a></span></dt>
35<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.conditions">Conditions and alternatives</a></span></dt>
36<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.prebuilt">Prebuilt targets</a></span></dt>
37</dl></div>
38<p>This section will guide you though the most basic features of
39  Boost.Build V2. We will start with the &#8220;Hello, world&#8221; example,
40  learn how to use libraries, and finish with testing and installing features. 
41  </p>
42<div class="section" lang="en">
43<div class="titlepage"><div><div><h3 class="title">
44<a name="bbv2.tutorial.hello"></a>Hello, world</h3></div></div></div>
45<p>The simplest project that Boost.Build can construct is
46      stored in <code class="filename">example/hello/</code> directory. The
47      project is described by a file
48      called <code class="filename">Jamroot</code> that contains:
49
50</p>
51<pre class="programlisting">
52exe hello : hello.cpp ;
53</pre>
54<p>
55
56      Even with this simple setup, you can do some interesting
57      things. First of all, just invoking <span><strong class="command">bjam</strong></span> will
58      build the <code class="filename">hello</code>
59      executable by compiling and
60      linking <code class="filename">hello.cpp</code>. By default, debug variant
61      is built. Now, to build the
62      release variant of <code class="filename">hello</code>, invoke
63
64</p>
65<pre class="screen">
66bjam release
67</pre>
68<p>
69
70      Note that debug and release variants are created in different
71      directories, so you can switch between variants or even build
72      multiple variants at once, without any unnecessary
73      recompilation. Let's extend the example by adding another line
74      to our project's <code class="filename">Jamroot</code>:
75
76</p>
77<pre class="programlisting">
78exe hello2 : hello.cpp ;
79</pre>
80<p>
81
82      Now let us build both the debug and release variants of our project
83      again:
84
85</p>
86<pre class="screen">
87bjam debug release
88</pre>
89<p>
90
91      Note that two variants of <code class="filename">hello2</code> are linked.
92      Since we have already built both variants
93      of <code class="filename">hello</code>, hello.cpp won't be recompiled;
94      instead the existing object files will just be linked into the
95      corresponding variants of <code class="filename">hello2</code>. Now
96      let's remove all the built products:
97
98</p>
99<pre class="screen">
100bjam --clean debug release
101</pre>
102<p>
103
104      It's also possible to build or clean specific targets.  The
105      following two commands, respectively, build or clean only the
106      debug version of <code class="filename">hello2</code>.
107
108</p>
109<pre class="screen">
110bjam hello2
111bjam --clean hello2
112</pre>
113<p>
114    </p>
115</div>
116<div class="section" lang="en">
117<div class="titlepage"><div><div><h3 class="title">
118<a name="bbv2.tutorial.properties"></a>Properties</h3></div></div></div>
119<div class="toc"><dl>
120<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.properties.requirements">Build Requests and Target Requirements</a></span></dt>
121<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.properties.project_attributes">Project Attributes</a></span></dt>
122</dl></div>
123<p>
124      To portably represent aspects of target configuration such as
125      debug and release variants, or single- and multi-threaded
126      builds, Boost.Build uses <em class="firstterm">features</em> with
127      associated <em class="firstterm">values</em>.  For
128      example, the <code class="computeroutput">debug-symbols</code> feature can have a value of <code class="computeroutput">on</code> or
129      <code class="computeroutput">off</code>.  A <em class="firstterm">property</em> is just a (feature,
130      value) pair.  When a user initiates a build, Boost.Build
131      automatically translates the requested properties into appropriate
132      command-line flags for invoking toolset components like compilers
133      and linkers.</p>
134<p>There are many built-in features that can be combined to
135      produce arbitrary build configurations.  The following command
136      builds the project's <code class="computeroutput">release</code> variant with inlining
137      disabled and debug symbols enabled:
138
139</p>
140<pre class="screen">
141bjam release inlining=off debug-symbols=on
142</pre>
143<p>
144</p>
145<p>Properties on the command-line are specified with the syntax:
146
147</p>
148<pre class="screen">
149<em class="replaceable"><code>feature-name</code></em>=<em class="replaceable"><code>feature-value</code></em>
150</pre>
151<p>
152</p>
153<p>The <code class="option">release</code> and <code class="option">debug</code> that we've seen
154      in <span><strong class="command">bjam</strong></span> invocations are just a shorthand way to
155      specify values of the <code class="varname">variant</code> feature.  For example, the command
156      above could also have been written this way:
157
158      </p>
159<pre class="screen">
160bjam variant=release inlining=off debug-symbols=on
161      </pre>
162<p>
163    </p>
164<p> <code class="varname">variant</code> is so commonly-used that it has
165      been given special status as an <em class="firstterm">implicit</em>
166      feature&#8212;Boost.Build will deduce the its identity just
167      from the name of one of its values.
168    </p>
169<p>
170      A complete description of features can be found in <a href="reference.html#bbv2.reference.features" title="Features and properties">the section called &#8220;Features and properties&#8221;</a>.
171    </p>
172<div class="section" lang="en">
173<div class="titlepage"><div><div><h4 class="title">
174<a name="bbv2.tutorial.properties.requirements"></a>Build Requests and Target Requirements</h4></div></div></div>
175<p>     
176        The set of properties specified on the command line constitute
177        a <em class="firstterm">build request</em>&#8212;a description of
178        the desired properties for building the requested targets (or,
179        if no targets were explicitly requested, the project in the
180        current directory).  The <span class="emphasis"><em>actual</em></span>
181        properties used for building targets are typically a
182        combination of the build request and properties derived from
183        the project's <code class="filename">Jamroot</code> (and its other
184        Jamfiles, as described in <a href="tutorial.html#bbv2.tutorial.hierarchy" title="Project Hierarchies">the section called &#8220;Project Hierarchies&#8221;</a>).  For example, the
185        locations of <code class="computeroutput">#include</code>d header files are normally
186        not specified on the command-line, but described in
187        Jamfiles as <em class="firstterm">target
188        requirements</em> and automatically combined with the
189        build request for those targets.  Multithread-enabled
190        compilation is another example of a typical target
191        requirement.  The Jamfile fragment below
192        illustrates how these requirements might be specified.
193      </p>
194<pre class="programlisting">
195exe hello
196    : hello.cpp
197    : &lt;include&gt;boost &lt;threading&gt;multi
198    ;
199</pre>
200<p> 
201        When <code class="filename">hello</code> is built, the two
202        requirements specified above will always be present.
203        If the build request given on the <span><strong class="command">bjam</strong></span>
204        command-line explictly contradicts a target's requirements,
205        the target requirements usually override (or, in the case of
206        &#8220;free&#8221;&#8221; features like
207        <code class="varname">&lt;include&gt;</code>,
208        <sup>[<a name="id2118228" href="#ftn.id2118228">5</a>]</sup>
209        augments) the build request.
210
211      </p>
212<div class="tip"><table border="0" summary="Tip">
213<tr>
214<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../images/tip.png"></td>
215<th align="left">Tip</th>
216</tr>
217<tr><td align="left" valign="top"><p>The value of the <code class="varname">&lt;include&gt;</code> feature is
218          relative to the location of <code class="filename">Jamroot</code> where it's
219          used.
220        </p></td></tr>
221</table></div>
222</div>
223<div class="section" lang="en">
224<div class="titlepage"><div><div><h4 class="title">
225<a name="bbv2.tutorial.properties.project_attributes"></a>Project Attributes</h4></div></div></div>
226<p>
227        If we want the same requirements for our other
228        target, <code class="filename">hello2</code>, we could simply duplicate
229        them.  However, as projects grow, that approach leads to a great
230        deal of repeated boilerplate in Jamfiles.
231       
232        Fortunately, there's a better way. Each project can specify a
233        set of <em class="firstterm">attributes</em>, including
234        requirements:
235
236</p>
237<pre class="programlisting">
238project
239    : requirements &lt;include&gt;/home/ghost/Work/boost &lt;threading&gt;multi
240    ;
241
242exe hello : hello.cpp ;
243exe hello2 : hello.cpp ;
244</pre>
245<p>
246
247        The effect would be as if we specified the same requirement for
248        both <code class="filename">hello</code> and <code class="filename">hello2</code>.
249      </p>
250</div>
251</div>
252<div class="section" lang="en">
253<div class="titlepage"><div><div><h3 class="title">
254<a name="bbv2.tutorial.hierarchy"></a>Project Hierarchies</h3></div></div></div>
255<p>So far we've only considered examples with one project
256    &#8212;a. with one user-written Boost.Jam file,
257    <code class="filename">Jamroot</code>). A typical large codebase would be
258    composed of many projects organized into a tree. The top of the
259    tree is called the <em class="firstterm">project root</em>.  Every
260    subproject is defined by a file called
261    <code class="filename">Jamfile</code> in a descendant directory of the
262    project root.  The parent project of a subproject is defined by
263    the nearest <code class="filename">Jamfile</code> or
264    <code class="filename">Jamroot</code> file in an ancestor directory. For
265    example, in the following directory layout:
266
267</p>
268<pre class="screen">
269top/
270  |
271  +-- Jamroot
272  |
273  +-- app/
274  |    |
275  |    +-- Jamfile
276  |    `-- app.cpp
277  |
278  `-- util/
279       |
280       +-- foo/
281       .    |
282       .    +-- Jamfile
283       .    `-- bar.cpp
284</pre>
285<p>
286
287      the project root is <code class="filename">top/</code>.  The projects in
288      <code class="filename">top/app/</code> and
289      <code class="filename">top/util/foo/</code> are immediate children of the
290      root project.
291
292      </p>
293<div class="note"><table border="0" summary="Note">
294<tr>
295<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
296<th align="left">Note</th>
297</tr>
298<tr><td align="left" valign="top"><p>
299          When we refer to a &#8220;Jamfile,&#8221; set in normal
300          type, we mean a file called either
301          <code class="filename">Jamfile</code> or
302          <code class="filename">Jamroot</code>.  When we need to be more
303          specific, the filename will be set as
304          &#8220;<code class="filename">Jamfile</code>&#8221; or
305          &#8220;<code class="filename">Jamroot</code>.&#8221;
306        </p></td></tr>
307</table></div>
308<p>
309    </p>
310<p>
311      Projects inherit all attributes (such as requirements)
312      from their parents.  Inherited requirements are combined with
313      any requirements specified by the subproject. 
314      For example, if <code class="filename">top/Jamroot</code> has
315
316</p>
317<pre class="programlisting">
318&lt;include&gt;/home/ghost/local
319</pre>
320<p>
321
322      in its requirements, then all of its subprojects will have it
323      in their requirements, too.  Of course, any project can add
324      include paths to those specified by its parents. <sup>[<a name="id2118464" href="#ftn.id2118464">6</a>]</sup> 
325    More details can be found in
326      <a href="advanced.html#bbv2.advanced.projects" title="Projects">the section called &#8220;Projects&#8221;</a>.
327    </p>
328<p>
329      Invoking <span><strong class="command">bjam</strong></span> without explicitly specifying
330      any targets on the command line builds the project rooted in the
331      current directory.  Building a project does not automatically
332      cause its subprojects to be built unless the parent project's
333      Jamfile explicitly requests it. In our example,
334      <code class="filename">top/Jamroot</code> might contain:
335
336</p>
337<pre class="programlisting">
338build-project app ;
339</pre>
340<p>
341
342      which would cause the project in <code class="filename">top/app/</code>
343      to be built whenever the project in <code class="filename">top/</code> is
344      built. However, targets in <code class="filename">top/util/foo/</code>
345      will be built only if they are needed by targets in
346      <code class="filename">top/</code> or <code class="filename">top/app/</code>.
347    </p>
348</div>
349<div class="section" lang="en">
350<div class="titlepage"><div><div><h3 class="title">
351<a name="bbv2.tutorial.libs"></a>Dependent Targets</h3></div></div></div>
352<p>
353      When a building a target <code class="filename">X</code> depends on first
354      building another target <code class="filename">Y</code> (such as a
355      library that must be linked with <em class="firstterm">X</em>),
356      <code class="filename">Y</code> is called a
357      <em class="firstterm">dependency</em> of <code class="filename">X</code> and
358      <code class="filename">X</code> is termed a
359      <em class="firstterm">dependent</em> of <code class="filename">Y</code>.
360    </p>
361<p>To get a feeling of target dependencies, let's continue the
362      above example and see how <code class="filename">top/app/Jamfile</code> can
363      use libraries from <code class="filename">top/util/foo</code>.  If
364      <code class="filename">top/util/foo/Jamfile</code> contains
365
366</p>
367<pre class="programlisting">
368lib bar : bar.cpp ;
369</pre>
370<p>
371
372      then to use this library in <code class="filename">top/app/Jamfile</code>, we can
373      write:
374
375</p>
376<pre class="programlisting">
377exe app : app.cpp ../util/foo//bar ;
378</pre>
379<p>
380
381      While <code class="computeroutput">app.cpp</code> refers to a regular source file,
382      <code class="computeroutput">../util/foo//bar</code> is a reference to another target:
383      a library <code class="filename">bar</code> declared in the Jamfile at
384      <code class="filename">../util/foo</code>.
385    </p>
386<div class="tip"><table border="0" summary="Tip">
387<tr>
388<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../images/tip.png"></td>
389<th align="left">Tip</th>
390</tr>
391<tr><td align="left" valign="top"><p>Some other build system have special syntax for listing dependent
392      libraries, for example <code class="varname">LIBS</code> variable. In Boost.Build,
393      you just add the library to the list of sources.
394      </p></td></tr>
395</table></div>
396<p>Suppose we build <code class="filename">app</code> with:
397    </p>
398<pre class="screen">
399bjam app optimization=full define=USE_ASM
400    </pre>
401<p>
402    Which properties will be used to build <code class="computeroutput">foo</code>? The answer is
403    that some features are
404    <em class="firstterm">propagated</em>&#8212;Boost.Build attempts to use
405    dependencies with the same value of propagated features. The
406    <code class="varname">&lt;optimization&gt;</code> feature is propagated, so both
407    <code class="filename">app</code> and <code class="filename">foo</code> will be compiled
408    with full optimization. But <code class="varname">&lt;define&gt;</code> is not
409    propagated: its value will be added as-is to the compiler flags for
410    <code class="filename">a.cpp</code>, but won't affect <code class="filename">foo</code>.
411    </p>
412<p>Let's improve this project further.
413      The library
414      probably has some headers that must be used when compiling
415      <code class="filename">app.cpp</code>. We could manually add the necessary
416      <code class="computeroutput">#include</code> paths to <code class="filename">app</code>'s
417      requirements as values of the
418      <code class="varname">&lt;include&gt;</code> feature, but then this work will
419      be repeated for all programs
420      that use <code class="filename">foo</code>. A better solution is to modify
421      <code class="filename">util/foo/Jamfile</code> in this way:
422
423</p>
424<pre class="programlisting">
425project
426    : usage-requirements &lt;include&gt;.
427    ;
428
429lib foo : foo.cpp ;
430</pre>
431<p>
432
433      Usage requirements are applied not to the target being declared
434      but to its
435      dependents. In this case, <code class="literal">&lt;include&gt;.</code> will be applied to all
436      targets that directly depend on <code class="filename">foo</code>.
437    </p>
438<p>Another improvement is using symbolic identifiers to refer to
439      the library, as opposed to <code class="filename">Jamfile</code> location.
440      In a large project, a library can be used by many targets, and if
441      they all use <code class="filename">Jamfile</code> location,
442      a change in directory organization entails much work.
443      The solution is to use project ids&#8212;symbolic names
444      not tied to directory layout. First, we need to assign a project id by
445      adding this code to
446      <code class="filename">Jamroot</code>:</p>
447<pre class="programlisting">
448use-project /library-example/foo : util/foo ;
449      </pre>
450<p>Second, we modify <code class="filename">app/Jamfile</code> to use the
451      project id:
452
453</p>
454<pre class="programlisting">
455exe app : app.cpp /library-example/foo//bar ;
456</pre>
457<p>
458The <code class="filename">/library-example/foo//bar</code> syntax is used
459      to refer to the target <code class="filename">bar</code> in
460      the project with id <code class="filename">/library-example/foo</code>.
461      We've achieved our goal&#8212;if the library is moved to a different
462      directory, only <code class="filename">Jamroot</code> must be modified.
463      Note that project ids are global&#8212;two Jamfiles are not
464      allowed to assign the same project id to different directories.
465           
466    </p>
467<div class="tip"><table border="0" summary="Tip">
468<tr>
469<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../images/tip.png"></td>
470<th align="left">Tip</th>
471</tr>
472<tr><td align="left" valign="top">
473<p>If you want all applications in some project to link
474      to a certain library, you can avoid having to specify it directly the sources of every
475      target by using the
476      <code class="varname">&lt;source&gt;</code> property. For example, if <code class="filename">/boost/filesystem//fs</code>
477      should be linked to all applications in your project, you can add
478      <code class="computeroutput">&lt;source&gt;/boost/filesystem//fs</code> to the project's requirements, like this:</p>
479<pre class="programlisting">
480project
481   : requirements &lt;source&gt;/boost/filesystem//fs
482   ;   
483      </pre>
484</td></tr>
485</table></div>
486</div>
487<div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title">
488<a name="bbv2.tutorial.testing"></a>Testing</h3></div></div></div></div>
489<div class="section" lang="en">
490<div class="titlepage"><div><div><h3 class="title">
491<a name="bbv2.tutorial.linkage"></a>Static and shared libaries</h3></div></div></div>
492<p>Libraries can be either
493    <span class="emphasis"><em>static</em></span>, which means they are included in executable
494    files that use them, or <span class="emphasis"><em>shared</em></span> (a.k.a.
495    <span class="emphasis"><em>dynamic</em></span>), which are only referred to from executables,
496    and must be available at run time. Boost.Build can create and use both kinds.
497    </p>
498<p>The kind of library produced from a <code class="computeroutput">lib</code> target is
499    determined by the value of the <code class="varname">link</code> feature. Default
500    value is <code class="literal">shared</code>, and to build static library, the value
501    should be <code class="literal">static</code>. You can either requiest static build
502    on the command line:
503    </p>
504<pre class="screen">
505bjam link=static
506    </pre>
507<p>
508    or in the library's requirements:   
509    </p>
510<pre class="programlisting">
511lib l : l.cpp : &lt;link&gt;static ;
512    </pre>
513<p>
514    </p>
515<p>
516      We can also use the <code class="varname">&lt;link&gt;</code> property
517      to express linking requirements on a per-target basis. 
518      For example, if a particular executable can be correctly built
519      only with the static version of a library, we can qualify the
520      executable's <a href="reference.html#bbv2.reference.targets.references">target
521      reference</a> to the library as follows:
522
523
524
525    </p>
526<pre class="programlisting">
527exe important : main.cpp helpers/&lt;link&gt;static ;</pre>
528<p>
529
530    No matter what arguments are specified on the <span><strong class="command">bjam</strong></span>
531    command line, <code class="filename">important</code> will only be linked with
532    the static version of <code class="filename">helpers</code>.
533    </p>
534<p>
535        Specifying properties in target references is especially useful if you
536        use a library defined in some other project (one you can't
537        change) but you still want static (or dynamic) linking to that library
538        in all cases. If that library is used by many targets,
539        you <span class="emphasis"><em>could</em></span> use target references
540        everywhere:
541
542        </p>
543<pre class="programlisting">
544exe e1 : e1.cpp /other_project//bar/&lt;link&gt;static ;
545exe e10 : e10.cpp /other_project//bar/&lt;link&gt;static ;</pre>
546<p>
547
548        but that's far from being convenient. A better approach is
549        to introduce a level of indirection.  Create a local
550        <span class="type">alias</span> target that refers to the static (or
551        dynamic) version of <code class="filename">foo</code>:
552
553        </p>
554<pre class="programlisting">
555alias foo : /other_project//bar/&lt;link&gt;static ;
556exe e1 : e1.cpp foo ;
557exe e10 : e10.cpp foo ;</pre>
558<p>
559
560        The <a href="tasks.html#bbv2.tasks.alias" title="Alias"><code class="computeroutput">alias</code></a> 
561        rule is specifically used to rename a reference to a target and possibly
562        change the properties.
563       
564       
565      </p>
566<div class="tip"><table border="0" summary="Tip">
567<tr>
568<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../images/tip.png"></td>
569<th align="left">Tip</th>
570</tr>
571<tr><td align="left" valign="top">
572<p>
573          When one library uses another, you put the second library in
574          the source list of the first. For example:
575          </p>
576<pre class="programlisting">
577lib utils : utils.cpp /boost/filesystem//fs ;   
578lib core : core.cpp utils ;
579exe app : app.cpp core ;</pre>
580<p>
581          This works no matter what kind of linking is used. When
582          <code class="filename">core</code> is built as a shared library, it is linked
583          directly into <code class="filename">utils</code>. Static libraries can't
584          link to other libraries, so when <code class="filename">core</code> is built
585          as a static library, its dependency on <code class="filename">utils</code> is passed along to
586          <code class="filename">core</code>'s dependents, causing
587          <code class="filename">app</code> to be linked with both
588          <code class="filename">core</code> and <code class="filename">utils</code>.
589        </p>
590</td></tr>
591</table></div>
592<div class="note"><table border="0" summary="Note">
593<tr>
594<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
595<th align="left">Note</th>
596</tr>
597<tr><td align="left" valign="top"><p>(Note for non-UNIX system). Typically, shared libraries must be
598        installed to a directory in the dynamic linker's search
599        path. Otherwise, applications that use shared libraries can't be
600        started. On Windows, the dynamic linker's search path is given by the
601        <code class="envar">PATH</code> environment variable. This restriction is lifted
602        when you use Boost.Build testing facilities&#8212;the
603        <code class="envar">PATH</code> variable will be automatically adjusted before
604        running executable.
605       
606        </p></td></tr>
607</table></div>
608</div>
609<div class="section" lang="en">
610<div class="titlepage"><div><div><h3 class="title">
611<a name="bbv2.tutorial.conditions"></a>Conditions and alternatives</h3></div></div></div>
612<p>Sometimes, particular relationships need to be maintained
613    among a target's build properties. For example, you might want to set
614    specific <code class="computeroutput">#define</code> when a library is built as shared,
615    or when a target's <code class="computeroutput">release</code> variant is built.
616    This can be achieved with <em class="firstterm">conditional requirements</em>.
617
618    </p>
619<pre class="programlisting">
620lib network : network.cpp
621    : <span class="bold"><strong>&lt;link&gt;shared:&lt;define&gt;NEWORK_LIB_SHARED</strong></span>
622     &lt;variant&gt;release:&lt;define&gt;EXTRA_FAST
623    ;
624</pre>
625<p>
626
627      In the example above, whenever <code class="filename">network</code> is
628      built with <code class="computeroutput">&lt;link&gt;shared</code>,
629      <code class="computeroutput">&lt;define&gt;NEWORK_LIB_SHARED</code> will be in its
630      properties, too. Also, whenever its release variant is built,
631      <code class="computeroutput">&lt;define&gt;EXTRA_FAST</code> will appear in its properties.
632    </p>
633<p>
634      Sometimes the ways a target is built are so different that
635      describing them using conditional requirements would be
636      hard. For example, imagine that a library actually uses
637      different source files depending on the toolset used to build
638      it. We can express this situation using <em class="firstterm">target
639      alternatives</em>:
640</p>
641<pre class="programlisting">
642lib demangler : dummy_demangler.cpp ;                      # alternative 1
643lib demangler : demangler_gcc.cpp : &lt;toolset&gt;gcc ;   # alternative 2
644lib demangler : demangler_msvc.cpp : &lt;toolset&gt;msvc ; # alternative 3
645</pre>
646<p>
647      When building <code class="filename">demangler</code>, Boost.Build will compare
648      requirements for each alternative with build properties to find the best match.
649      For example, when building with with <code class="computeroutput">&lt;toolset&gt;gcc</code> 
650      alternative 2, will be selected, and when building with
651      <code class="computeroutput">&lt;toolset&gt;msvc</code> alternative 3 will be selected. In all other
652      cases, the most generic alternative 1 will be built.
653    </p>
654</div>
655<div class="section" lang="en">
656<div class="titlepage"><div><div><h3 class="title">
657<a name="bbv2.tutorial.prebuilt"></a>Prebuilt targets</h3></div></div></div>
658<p>
659      To link to libraries whose build instructions aren't given in a Jamfile,
660      you need to create <code class="computeroutput">lib</code> targets with an appropriate
661      <code class="varname">file</code> property.  Target alternatives can be used to
662      associate multiple library files with a single conceptual target. For
663      example:
664</p>
665<pre class="programlisting">
666# util/lib2/Jamfile
667lib lib2
668    :
669    : &lt;file&gt;lib2_release.a &lt;variant&gt;release
670    ;
671
672lib lib2
673    :
674    : &lt;file&gt;lib2_debug.a &lt;variant&gt;debug
675    ;
676</pre>
677<p>
678
679      This example defines two alternatives for <code class="filename">lib2</code>, and
680      for each one names a prebuilt file.  Naturally, there are no sources.
681      Instead, the <code class="varname">&lt;file&gt;</code> feature is used to specify
682      the file name.
683    </p>
684<p>
685      Once a prebuilt target has been declared, it can be used just like any other target:
686
687</p>
688<pre class="programlisting">
689exe app : app.cpp ../util/lib2//lib2 ;
690</pre>
691<p>
692
693      As with any target, the alternative selected depends on the
694      properties propagated from <code class="filename">lib2</code>'s dependents.
695      If we build the the release and debug versions of <code class="filename">app</code> will be linked
696      with <code class="filename">lib2_release.a</code> and <code class="filename">lib2_debug.a</code>, respectively. 
697
698    </p>
699<p>
700      System libraries&#8212;those that are automatically found by
701      the toolset by searching through some set of predetermined
702      paths&#8212;should be declared almost like regular ones:
703
704</p>
705<pre class="programlisting">
706lib pythonlib : : &lt;name&gt;python22 ;
707</pre>
708<p>
709
710      We again don't specify any sources, but give a
711      <code class="varname">name</code> that should be passed to the
712      compiler. If the gcc toolset were used to link an executable
713      target to <code class="filename">pythonlib</code>, <code class="option">-lpython22</code>
714      would appear in the command line (other compilers may use
715      different options).
716    </p>
717<p>
718      We can also specify where the toolset should look for the library:
719
720</p>
721<pre class="programlisting">
722lib pythonlib : : &lt;name&gt;python22 &lt;search&gt;/opt/lib ;
723</pre>
724<p>
725
726      And, of course, target alternatives can be used in the usual way:
727
728</p>
729<pre class="programlisting">
730lib pythonlib : : &lt;name&gt;python22 &lt;variant&gt;release ;
731lib pythonlib : : &lt;name&gt;python22_d &lt;variant&gt;debug ;
732</pre>
733<p>
734
735    </p>
736<p>A more advanced use of prebuilt targets is described in <a href="faq.html#bbv2.recipies.site-config" title="Targets in site-config.jam">the section called &#8220;Targets in site-config.jam&#8221;</a>.   
737    </p>
738</div>
739<div class="footnotes">
740<br><hr width="100" align="left">
741<div class="footnote"><p><sup>[<a name="ftn.id2118228" href="#id2118228">5</a>] </sup>
742See <a href="reference.html#bbv2.reference.features.attributes" title="Feature Attributes">the section called &#8220;Feature Attributes&#8221;</a>
743</p></div>
744<div class="footnote"><p><sup>[<a name="ftn.id2118464" href="#id2118464">6</a>] </sup>Many
745      features will be overridden,
746      rather than added-to, in subprojects.  See <a href="reference.html#bbv2.reference.features.attributes" title="Feature Attributes">the section called &#8220;Feature Attributes&#8221;</a> for more
747      information</p></div>
748</div>
749</div>
750<table width="100%"><tr>
751<td align="left"></td>
752<td align="right"><small></small></td>
753</tr></table>
754<hr>
755<div class="spirit-nav">
756<a accesskey="p" href="installation.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.html"><img src="../images/next.png" alt="Next"></a>
757</div>
758</body>
759</html>
Note: See TracBrowser for help on using the repository browser.