doc/html/bbv2/tutorial.html

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