doc/html/bbv2/tutorial.html

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