doc/html/bbv2/tasks.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>Common tasks</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="overview.html" title="Overview">
  11 <link rel="next" href="reference.html" title="Reference">
  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="overview.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="reference.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.tasks"></a>Common tasks</h2></div></div></div>
  29 <div class="toc"><dl class="toc">
  30 <dt><span class="section"><a href="tasks.html#bbv2.tasks.programs">Programs</a></span></dt>
  31 <dt><span class="section"><a href="tasks.html#bbv2.tasks.libraries">Libraries</a></span></dt>
  32 <dt><span class="section"><a href="tasks.html#bbv2.tasks.alias">Alias</a></span></dt>
  33 <dt><span class="section"><a href="tasks.html#bbv2.tasks.installing">Installing</a></span></dt>
  34 <dt><span class="section"><a href="tasks.html#bbv2.builtins.testing">Testing</a></span></dt>
  35 <dt><span class="section"><a href="tasks.html#bbv2.builtins.raw">Custom commands</a></span></dt>
  36 <dt><span class="section"><a href="tasks.html#bbv2.reference.precompiled_headers">Precompiled Headers</a></span></dt>
  37 <dt><span class="section"><a href="tasks.html#bbv2.reference.generated_headers">Generated headers</a></span></dt>
  38 <dt><span class="section"><a href="tasks.html#bbv2.tasks.crosscompile">Cross-compilation</a></span></dt>
  39 </dl></div>
  40 <p>
  41     This section describes main targets types that Boost.Build supports
  42     out-of-the-box. Unless otherwise noted, all mentioned main target rules have
  43     the common signature, described in <a class="xref" href="overview.html#bbv2.overview.targets" title="Declaring Targets">the section called &#8220;Declaring Targets&#8221;</a>.
  44   </p>
  45 <div class="section">
  46 <div class="titlepage"><div><div><h3 class="title">
  47 <a name="bbv2.tasks.programs"></a>Programs</h3></div></div></div>
  48 <a class="indexterm" name="idp637041952"></a><p>
  49       Programs are created using the <code class="computeroutput">exe</code> rule, which follows the
  50       <a class="link" href="overview.html#bbv2.main-target-rule-syntax">common syntax</a>. For
  51       example:
  52 </p>
  53 <pre class="programlisting">
  54 exe hello : hello.cpp some_library.lib /some_project//library
  55           : &lt;threading&gt;multi
  56           ;
  57 </pre>
  58 <p>
  59       This will create an executable file from the sources&#8212;in this case, one
  60       C++ file, one library file present in the same directory, and another
  61       library that is created by Boost.Build. Generally, sources can include C
  62       and C++ files, object files and libraries. Boost.Build will automatically
  63       try to convert targets of other types.
  64     </p>
  65 <div class="tip"><table border="0" summary="Tip">
  66 <tr>
  67 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../doc/src/images/tip.png"></td>
  68 <th align="left">Tip</th>
  69 </tr>
  70 <tr><td align="left" valign="top"><p>
  71         On Windows, if an application uses shared libraries, and both the
  72         application and the libraries are built using Boost.Build, it is not
  73         possible to immediately run the application, because the <code class="literal">PATH
  74         </code> environment variable should include the path to the
  75         libraries. It means you have to either add the paths manually, or have
  76         the build place the application and the libraries into the same
  77         directory. See <a class="xref" href="tasks.html#bbv2.tasks.installing" title="Installing">the section called &#8220;Installing&#8221;</a>.
  78       </p></td></tr>
  79 </table></div>
  80 </div>
  81 <div class="section">
  82 <div class="titlepage"><div><div><h3 class="title">
  83 <a name="bbv2.tasks.libraries"></a>Libraries</h3></div></div></div>
  84 <a class="indexterm" name="idp637050368"></a><p>
  85       Library targets are created using the <code class="computeroutput">lib</code> rule, which
  86       follows the <a class="link" href="overview.html#bbv2.main-target-rule-syntax">common syntax
  87       </a>. For example:
  88 </p>
  89 <pre class="programlisting">
  90 lib helpers : helpers.cpp ;
  91 </pre>
  92 <p>
  93       This will define a library target named <code class="computeroutput">helpers</code> built from
  94       the <code class="computeroutput">helpers.cpp</code> source file.
  95       It can be either a static library or a shared library,
  96       depending on the value of the <a class="link" href="reference.html#bbv2.overview.builtins.features.link">&lt;link&gt;</a> feature.
  97     </p>
  98 <p>
  99       Library targets can represent:
 100       </p>
 101 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 102 <li class="listitem"><p>
 103             Libraries that should be built from source,
 104             as in the example above.
 105           </p></li>
 106 <li class="listitem"><p>
 107             Prebuilt libraries which already exist on the system.
 108             Such libraries can be searched for by the tools using them (typically
 109             with the linker's <code class="option">-l</code> option) or their paths can be
 110             known in advance by the build system.
 111           </p></li>
 112 </ul></div>
 113 <p>
 114     </p>
 115 <p>
 116       The syntax for prebuilt libraries is given below:
 117 </p>
 118 <pre class="programlisting">
 119 lib z : : &lt;name&gt;z &lt;search&gt;/home/ghost ;
 120 lib compress : : &lt;file&gt;/opt/libs/compress.a ;
 121 </pre>
 122 <p>
 123       The <code class="computeroutput">name</code> property specifies the name of the library
 124       without the standard prefixes and suffixes.  For example, depending
 125       on the system, <code class="computeroutput">z</code> could refer to a file called
 126       z.so, libz.a, or z.lib, etc.  The <code class="computeroutput">search</code> feature
 127       specifies paths in which to search for the library in addition
 128       to the default compiler paths. <code class="computeroutput">search</code> can be specified
 129       several times or it can be omitted, in which case only the default
 130       compiler paths will be searched. The <code class="computeroutput">file</code> property
 131       specifies the file location.
 132     </p>
 133 <p>
 134       The difference between using the <code class="computeroutput">file</code> feature and
 135       using a combination of the <code class="computeroutput">name</code> and <code class="computeroutput">search</code>
 136       features is that <code class="computeroutput">file</code> is more precise.
 137
 138       </p>
 139 <div class="warning"><table border="0" summary="Warning">
 140 <tr>
 141 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td>
 142 <th align="left">Warning</th>
 143 </tr>
 144 <tr><td align="left" valign="top">
 145 <p>
 146           The value of the <code class="computeroutput">search</code> feature is just added to the
 147           linker search path.  When linking to multiple libraries,
 148           the paths specified by <code class="computeroutput">search</code> are combined without
 149           regard to which <code class="computeroutput">lib</code> target each path came from.
 150           Thus, given
 151 </p>
 152 <pre class="programlisting">
 153 lib a : : &lt;name&gt;a &lt;search&gt;/pool/release ;
 154 lib b : : &lt;name&gt;b &lt;search&gt;/pool/debug ;
 155 </pre>
 156 <p>
 157           If /pool/release/a.so, /pool/release/b.so, /pool/debug/a.so,
 158           and /pool/release/b.so all exist, the linker will probably
 159           take both <code class="computeroutput">a</code> and <code class="computeroutput">b</code> from the same
 160           directory, instead of finding <code class="computeroutput">a</code> in /pool/release
 161           and <code class="computeroutput">b</code> in /pool/debug.  If you need to distinguish
 162           between multiple libraries with the same name, it's safer
 163           to use <code class="computeroutput">file</code>.
 164         </p>
 165 </td></tr>
 166 </table></div>
 167 <p>
 168     </p>
 169 <p>
 170       For convenience, the following syntax is allowed:
 171 </p>
 172 <pre class="programlisting">
 173 lib z ;
 174 lib gui db aux ;
 175 </pre>
 176 <p>
 177       which has exactly the same effect as:
 178 </p>
 179 <pre class="programlisting">
 180 lib z : : &lt;name&gt;z ;
 181 lib gui : : &lt;name&gt;gui ;
 182 lib db : : &lt;name&gt;db ;
 183 lib aux : : &lt;name&gt;aux ;
 184 </pre>
 185 <p>
 186     </p>
 187 <p>
 188       When a library references another library you should put that other
 189       library in its list of sources. This will do the right thing in all cases.
 190        For portability, you should specify
 191       library dependencies even for searched and prebuilt libraries, othewise,
 192       static linking on Unix will not work. For example:
 193 </p>
 194 <pre class="programlisting">
 195 lib z ;
 196 lib png : z : &lt;name&gt;png ;
 197 </pre>
 198 <p>
 199     </p>
 200 <div class="note"><table border="0" summary="Note">
 201 <tr>
 202 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td>
 203 <th align="left">Note</th>
 204 </tr>
 205 <tr><td align="left" valign="top">
 206 <p>
 207         When a library has a shared library as a source, or a static
 208         library has another static library as a source then any target
 209         linking to the first library with automatically link to its source
 210         library as well.
 211       </p>
 212 <p>
 213         On the other hand, when a shared library has a static library as
 214         a source then the first library will be built so that it completely
 215         includes the second one.
 216       </p>
 217 <p>
 218         If you do not want a shared library to include all the libraries specified
 219         in its sources (especially statically linked ones), you would need to
 220         use the following:
 221 </p>
 222 <pre class="programlisting">
 223 lib b : a.cpp ;
 224 lib a : a.cpp : &lt;use&gt;b : : &lt;library&gt;b ;
 225 </pre>
 226 <p>
 227         This specifies that library <code class="computeroutput">a</code> uses library <code class="computeroutput">b</code>,
 228         and causes all executables that link to <code class="computeroutput">a</code> to link to
 229         <code class="computeroutput">b</code> also. In this case, even for shared linking, the
 230         <code class="computeroutput">a</code> library will not refer to <code class="computeroutput">b</code>.
 231       </p>
 232 </td></tr>
 233 </table></div>
 234 <p>
 235
 236       <a class="link" href="overview.html#bbv2.overview.targets" title="Declaring Targets">Usage requirements</a> are often
 237       very useful for defining library targets. For example, imagine that
 238       you want you build a <code class="computeroutput">helpers</code> library and its interface is
 239       described in its <code class="computeroutput">helpers.hpp</code> header file located in the same
 240       directory as the <code class="computeroutput">helpers.cpp</code> source file. Then you could add
 241       the following to the Jamfile located in that same directory:
 242 </p>
 243 <pre class="programlisting">
 244 lib helpers : helpers.cpp : : : &lt;include&gt;. ;
 245 </pre>
 246 <p>
 247       which would automatically add the directory where the target has been
 248       defined (and where the library's header file is located) to the compiler's
 249       include path for all targets using the <code class="computeroutput">helpers</code> library. This
 250       feature greatly simplifies Jamfiles.
 251     </p>
 252 </div>
 253 <div class="section">
 254 <div class="titlepage"><div><div><h3 class="title">
 255 <a name="bbv2.tasks.alias"></a>Alias</h3></div></div></div>
 256 <p>
 257       The <code class="computeroutput">alias</code> rule gives an alternative name to a
 258       group of targets. For example, to give the name <code class="filename">core</code>
 259       to a group of three other targets with the following code:
 260 </p>
 261 <pre class="programlisting">
 262 alias core : im reader writer ;
 263 </pre>
 264 <p>
 265       Using <code class="filename">core</code> on the command line, or in the source list
 266       of any other target is the same as explicitly using <code class="filename">im
 267       </code>, <code class="filename">reader</code>, and <code class="filename">writer</code>.
 268     </p>
 269 <p>
 270       Another use of the <code class="computeroutput">alias</code> rule is to change build properties.
 271       For example, if you want to use link statically to the Boost Threads
 272       library, you can write the following:
 273 </p>
 274 <pre class="programlisting">
 275 alias threads : /boost/thread//boost_thread : &lt;link&gt;static ;
 276 </pre>
 277 <p>
 278       and use only the <code class="computeroutput">threads</code> alias in your Jamfiles.
 279     </p>
 280 <p>
 281       You can also specify usage requirements for the <code class="computeroutput">alias</code> target.
 282       If you write the following:
 283 </p>
 284 <pre class="programlisting">
 285 alias header_only_library : : : :  &lt;include&gt;/usr/include/header_only_library ;
 286 </pre>
 287 <p>
 288       then using <code class="computeroutput">header_only_library</code> in sources will only add an
 289       include path. Also note that when an alias has sources, their usage
 290       requirements are propagated as well. For example:
 291 </p>
 292 <pre class="programlisting">
 293 lib library1 : library1.cpp : : : &lt;include&gt;/library/include1 ;
 294 lib library2 : library2.cpp : : : &lt;include&gt;/library/include2 ;
 295 alias static_libraries : library1 library2 : &lt;link&gt;static ;
 296 exe main : main.cpp static_libraries ;
 297 </pre>
 298 <p>
 299       will compile <code class="filename">main.cpp</code> with additional includes
 300       required for using the specified static libraries.
 301     </p>
 302 </div>
 303 <div class="section">
 304 <div class="titlepage"><div><div><h3 class="title">
 305 <a name="bbv2.tasks.installing"></a>Installing</h3></div></div></div>
 306 <p>
 307       This section describes various ways to install built target and arbitrary
 308       files.
 309     </p>
 310 <h4>
 311 <a name="idp637109104"></a>Basic install</h4>
 312 <p>
 313       For installing a built target you should use the <code class="computeroutput">install</code>
 314       rule, which follows the <a class="link" href="overview.html#bbv2.main-target-rule-syntax">
 315       common syntax</a>. For example:
 316 </p>
 317 <pre class="programlisting">
 318 install dist : hello helpers ;
 319 </pre>
 320 <p>
 321       will cause the targets <code class="computeroutput">hello</code> and <code class="computeroutput">helpers</code> to be
 322       moved to the <code class="filename">dist</code> directory, relative to the
 323       Jamfile's directory. The directory can be changed using the
 324       <code class="computeroutput">location</code> property:
 325 </p>
 326 <pre class="programlisting">
 327 install dist : hello helpers : &lt;location&gt;/usr/bin ;
 328 </pre>
 329 <p>
 330       While you can achieve the same effect by changing the target name to
 331       <code class="filename">/usr/bin</code>, using the <code class="computeroutput">location</code> property is
 332       better as it allows you to use a mnemonic target name.
 333     </p>
 334 <p>
 335       The <code class="computeroutput">location</code> property is especially handy when the location
 336       is not fixed, but depends on the build variant or environment variables:
 337 </p>
 338 <pre class="programlisting">
 339 install dist : hello helpers :
 340     &lt;variant&gt;release:&lt;location&gt;dist/release
 341     &lt;variant&gt;debug:&lt;location&gt;dist/debug ;
 342 install dist2 : hello helpers : &lt;location&gt;$(DIST) ;
 343 </pre>
 344 <p>
 345       See also <a class="link" href="reference.html#bbv2.reference.variants.propcond" title="Conditional properties">conditional
 346       properties</a> and <a class="link" href="faq.html#bbv2.faq.envar" title="Accessing environment variables">environment
 347       variables</a>
 348     </p>
 349 <h4>
 350 <a name="idp637121808"></a>Installing with all dependencies</h4>
 351 <p>
 352       Specifying the names of all libraries to install can be boring. The
 353       <code class="computeroutput">install</code> allows you to specify only the top-level executable
 354       targets to install, and automatically install all dependencies:
 355 </p>
 356 <pre class="programlisting">
 357 install dist : hello
 358            : &lt;install-dependencies&gt;on &lt;install-type&gt;EXE
 359              &lt;install-type&gt;LIB
 360            ;
 361 </pre>
 362 <p>
 363       will find all targets that <code class="computeroutput">hello</code> depends on, and install all
 364       of those which are either executables or libraries. More specifically, for
 365       each target, other targets that were specified as sources or as dependency
 366       properties, will be recursively found. One exception is that targets
 367       referred with the <a class="link" href="reference.html#bbv2.builtin.features.use">
 368       <code class="computeroutput">use</code></a> feature are not considered, as that feature is
 369       typically used to refer to header-only libraries. If the set of target
 370       types is specified, only targets of that type will be installed,
 371       otherwise, all found target will be installed.
 372     </p>
 373 <h4>
 374 <a name="idp637127200"></a>Preserving Directory Hierarchy</h4>
 375 <a class="indexterm" name="idp637127584"></a><p>
 376       By default, the <code class="computeroutput">install</code> rule will strip paths from its
 377       sources. So, if sources include <code class="filename">a/b/c.hpp</code>, the
 378       <code class="filename">a/b</code> part will be ignored. To make the
 379       <code class="computeroutput">install</code> rule preserve the directory hierarchy you need to
 380       use the <code class="literal">&lt;install-source-root&gt;</code> feature to specify
 381       the root of the hierarchy you are installing. Relative paths from that
 382       root will be preserved. For example, if you write:
 383 </p>
 384 <pre class="programlisting">
 385 install headers
 386     : a/b/c.h
 387     : &lt;location&gt;/tmp &lt;install-source-root&gt;a
 388     ;
 389 </pre>
 390 <p>
 391       the a file named <code class="filename">/tmp/b/c.h</code> will be created.
 392     </p>
 393 <p>
 394       The <a class="link" href="reference.html#bbv2.reference.glob-tree">glob-tree</a> rule can be
 395       used to find all files below a given directory, making it easy to install
 396       an entire directory tree.
 397     </p>
 398 <h4>
 399 <a name="idp637135936"></a>Installing into Several Directories</h4>
 400 <p>
 401       The <a class="link" href="tasks.html#bbv2.tasks.alias" title="Alias"><code class="computeroutput">alias</code></a> rule can be
 402       used when targets need to be installed into several directories:
 403 </p>
 404 <pre class="programlisting">
 405 alias install : install-bin install-lib ;
 406 install install-bin : applications : /usr/bin ;
 407 install install-lib : helper : /usr/lib ;
 408 </pre>
 409 <p>
 410     </p>
 411 <p>
 412       Because the <code class="computeroutput">install</code> rule just copies targets, most free
 413       features <a href="#ftn.idp637139920" class="footnote" name="idp637139920"><sup class="footnote">[18]</sup></a> have no
 414       effect when used in requirements of the <code class="computeroutput">install</code> rule. The
 415       only two that matter are <a class="link" href="reference.html#bbv2.builtin.features.dependency">
 416       <code class="varname">dependency</code></a> and, on Unix, <a class="link" href="reference.html#bbv2.reference.features.dll-path"><code class="varname">dll-path</code>
 417       </a>.
 418     </p>
 419 <div class="note"><table border="0" summary="Note">
 420 <tr>
 421 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td>
 422 <th align="left">Note</th>
 423 </tr>
 424 <tr><td align="left" valign="top"><p>
 425         (Unix specific) On Unix, executables built using Boost.Build typically
 426         contain the list of paths to all used shared libraries. For installing,
 427         this is not desired, so Boost.Build relinks the executable with an empty
 428         list of paths. You can also specify additional paths for installed
 429         executables using the <code class="varname">dll-path</code> feature.
 430       </p></td></tr>
 431 </table></div>
 432 </div>
 433 <div class="section">
 434 <div class="titlepage"><div><div><h3 class="title">
 435 <a name="bbv2.builtins.testing"></a>Testing</h3></div></div></div>
 436 <p>
 437       Boost.Build has convenient support for running unit tests. The simplest
 438       way is the <code class="computeroutput">unit-test</code> rule, which follows the <a class="link" href="overview.html#bbv2.main-target-rule-syntax">common syntax</a>. For example:
 439 </p>
 440 <pre class="programlisting">
 441 unit-test helpers_test : helpers_test.cpp helpers ;
 442 </pre>
 443 <p>
 444     </p>
 445 <p>
 446       The <code class="computeroutput">unit-test</code> rule behaves like the
 447       <a class="link" href="tasks.html#bbv2.tasks.programs" title="Programs">exe</a> rule, but after the executable is created
 448       it is also run. If the executable returns an error code, the build system
 449       will also return an error and will try running the executable on the next
 450       invocation until it runs successfully. This behaviour ensures that you can
 451       not miss a unit test failure.
 452     </p>
 453 <p>
 454        There are few specialized testing rules, listed below:
 455 </p>
 456 <pre class="programlisting">
 457 rule compile ( sources : requirements * : target-name ? )
 458 rule compile-fail ( sources : requirements * : target-name ? )
 459 rule link ( sources + : requirements * : target-name ? )
 460 rule link-fail ( sources + : requirements * : target-name ? )
 461 </pre>
 462 <p>
 463       They are given a list of sources and requirements. If the target name is
 464       not provided, the name of the first source file is used instead. The
 465       <code class="literal">compile*</code> tests try to compile the passed source. The
 466       <code class="literal">link*</code> rules try to compile and link an application from
 467       all the passed sources. The <code class="literal">compile</code> and <code class="literal">link
 468       </code> rules expect that compilation/linking succeeds. The <code class="literal">
 469       compile-fail</code> and <code class="literal">link-fail</code> rules expect that
 470       the compilation/linking fails.
 471     </p>
 472 <p>
 473       There are two specialized rules for running applications, which are more
 474       powerful than the <code class="computeroutput">unit-test</code> rule. The <code class="computeroutput">run</code> rule
 475       has the following signature:
 476 </p>
 477 <pre class="programlisting">
 478 rule run ( sources + : args * : input-files * : requirements * : target-name ?
 479     : default-build * )
 480 </pre>
 481 <p>
 482       The rule builds application from the provided sources and runs it, passing
 483       <code class="varname">args</code> and <code class="varname">input-files</code> as command-line
 484       arguments. The <code class="varname">args</code> parameter is passed verbatim and
 485       the values of the <code class="varname">input-files</code> parameter are treated as
 486       paths relative to containing Jamfile, and are adjusted if <span class="command"><strong>b2</strong></span>
 487       is invoked from a different directory. The
 488       <code class="computeroutput">run-fail</code> rule is identical to the <code class="computeroutput">run</code> rule,
 489       except that it expects that the run fails.
 490     </p>
 491 <p>
 492       All rules described in this section, if executed successfully, create a
 493       special manifest file to indicate that the test passed. For the
 494       <code class="computeroutput">unit-test</code> rule the files is named <code class="filename"><em class="replaceable"><code>
 495       target-name</code></em>.passed</code> and for the other rules it is
 496       called <code class="filename"><em class="replaceable"><code>target-name</code></em>.test</code>.
 497       The <code class="computeroutput">run*</code> rules also capture all output from the program, and
 498       store it in a file named <code class="filename"><em class="replaceable"><code>
 499       target-name</code></em>.output</code>.
 500     </p>
 501 <p>
 502       <a class="indexterm" name="idp637171056"></a>
 503       If the <code class="literal">preserve-test-targets</code> feature has the value
 504       <code class="literal">off</code>, then <code class="computeroutput">run</code> and the <code class="computeroutput">run-fail</code>
 505       rules will remove the executable after running it.  This somewhat decreases
 506       disk space requirements for continuous testing environments. The default
 507       value of <code class="literal">preserve-test-targets</code> feature is <code class="literal">on</code>.
 508     </p>
 509 <p>
 510       It is possible to print the list of all test targets (except for
 511       <code class="computeroutput">unit-test</code>) declared in your project, by passing the <code class="literal">
 512       --dump-tests</code> command-line option. The output will consist of
 513       lines of the form:
 514 </p>
 515 <pre class="screen">
 516 boost-test(<em class="replaceable"><code>test-type</code></em>) <em class="replaceable"><code>path</code></em> : <em class="replaceable"><code>sources</code></em>
 517 </pre>
 518 <p>
 519     </p>
 520 <p>
 521       It is possible to process the list of tests, Boost.Build output
 522       and the presense/absense of the <code class="filename">*.test</code>
 523       files created when test passes into human-readable status table of tests.
 524       Such processing utilities are not included in Boost.Build.
 525     </p>
 526 <p>The following features adjust behaviour of the testing metatargets.</p>
 527 <div class="variablelist"><dl class="variablelist">
 528 <dt><span class="term"><code class="literal">testing.arg</code></span></dt>
 529 <dd>
 530 <p>
 531             Defines an argument to be passed to the target when it is executed
 532             before the list of input files.
 533           </p>
 534 <p>
 535 </p>
 536 <pre class="programlisting">
 537 unit-test helpers_test
 538   : helpers_test.cpp helpers
 539   : <span class="bold"><strong>&lt;testing.arg&gt;"--foo bar"</strong></span>
 540   ;
 541 </pre>
 542 <p>
 543           </p>
 544 </dd>
 545 <dt><span class="term"><code class="literal">testing.input-file</code></span></dt>
 546 <dd><p>
 547             Specifies a file to be passed to the executable on the command line
 548             after the arguments. All files must be specified in alphabetical
 549             order due to constrainsts in the current implementation.
 550           </p></dd>
 551 <dt><span class="term"><code class="literal">testing.launcher</code></span></dt>
 552 <dd>
 553 <p>
 554             By default, the executable is run directly. Sometimes, it is
 555             desirable to run the executable using some helper command. You
 556             should use this property to specify the name of the helper
 557             command. For example, if you write:
 558 </p>
 559 <pre class="programlisting">
 560 unit-test helpers_test
 561   : helpers_test.cpp helpers
 562   : <span class="bold"><strong>&lt;testing.launcher&gt;valgrind</strong></span>
 563   ;
 564 </pre>
 565 <p>
 566             The command used to run the executable will be:
 567 </p>
 568 <pre class="screen">
 569 <span class="bold"><strong>valgrind</strong></span> bin/$toolset/debug/helpers_test
 570 </pre>
 571 <p>
 572           </p>
 573 </dd>
 574 <dt><span class="term"><code class="literal">test-info</code></span></dt>
 575 <dd><p>
 576             A description of the test. This is displayed as part of the
 577             <code class="literal">--dump-tests</code> command-line option.
 578           </p></dd>
 579 </dl></div>
 580 </div>
 581 <div class="section">
 582 <div class="titlepage"><div><div><h3 class="title">
 583 <a name="bbv2.builtins.raw"></a>Custom commands</h3></div></div></div>
 584 <p>
 585       For most main target rules, Boost.Build automatically figures out
 586       the commands to run.  When you want to use new
 587       file types or support new tools, one approach is to extend Boost.Build to
 588       support them smoothly, as documented in <a class="xref" href="extender.html" title="Extender Manual">the section called &#8220;Extender Manual&#8221;</a>.
 589       However, if the new tool is only used in a single place, it
 590       might be easier just to specify the commands to run explicitly.
 591     </p>
 592 <p>
 593
 594       Three main target rules can be used for that. The <code class="computeroutput">make
 595       </code> rule allows you to construct a single file from any number
 596       of source file, by running a command you specify. The <code class="computeroutput">
 597       notfile</code> rule allows you to run an arbitrary command,
 598       without creating any files. And finaly, the <code class="computeroutput">generate
 599       </code> rule allows you to describe a transformation using
 600       Boost.Build's virtual targets. This is higher-level than the file names that
 601       the <code class="computeroutput">make</code> rule operates with and allows you to
 602       create more than one target, create differently named targets depending on
 603       properties, or use more than one tool.
 604     </p>
 605 <p>
 606       The <code class="computeroutput">make</code> rule is used when you want to create
 607       one file from a number of sources using some specific command. The
 608       <code class="computeroutput">notfile</code> is used to unconditionally run a
 609       command.
 610     </p>
 611 <p>
 612       Suppose you want to create the file <code class="filename">file.out</code> from
 613       the file <code class="filename">file.in</code> by running the command <span class="command"><strong>
 614       in2out</strong></span>. Here is how you would do this in Boost.Build:
 615 </p>
 616 <pre class="programlisting">
 617 make file.out : file.in : @in2out ;
 618 actions in2out
 619 {
 620     in2out $(&lt;) $(&gt;)
 621 }
 622 </pre>
 623 <p>
 624       If you run <span class="command"><strong>b2</strong></span> and <code class="filename">file.out</code> does
 625       not exist, Boost.Build will run the <span class="command"><strong>in2out</strong></span> command to
 626       create that file. For more details on specifying actions, see <a class="xref" href="overview.html#bbv2.overview.jam_language.actions">the section called &#8220;Boost.Jam Language&#8221;</a>.
 627     </p>
 628 <p>
 629       It could be that you just want to run some command unconditionally, and
 630       that command does not create any specific files. For that you can use the
 631       <code class="computeroutput">notfile</code> rule. For example:
 632 </p>
 633 <pre class="programlisting">
 634 notfile echo_something : @echo ;
 635 actions echo
 636 {
 637     echo "something"
 638 }
 639 </pre>
 640 <p>
 641       The only difference from the <code class="computeroutput">make</code> rule is
 642       that the name of the target is not considered a name of a file, so
 643       Boost.Build will unconditionally run the action.
 644     </p>
 645 <p>
 646
 647       The <code class="computeroutput">generate</code> rule is used when you want to
 648       express transformations using Boost.Build's virtual targets, as opposed to
 649       just filenames. The <code class="computeroutput">generate</code> rule has the
 650       standard main target rule signature, but you are required to specify the
 651       <code class="literal">generating-rule</code> property. The value of the property
 652       should be in the form <code class="literal">
 653       @<em class="replaceable"><code>rule-name</code></em></code>, the named rule should
 654       have the following signature:
 655 </p>
 656 <pre class="programlisting">
 657 rule generating-rule ( project name : property-set : sources * )
 658 </pre>
 659 <p>
 660       and will be called with an instance of the <code class="computeroutput">project-target</code>
 661       class, the name of the main target, an instance of the
 662       <code class="computeroutput">property-set</code> class containing build properties, and the list
 663       of instances of the <code class="computeroutput">virtual-target</code> class corresponding to
 664       sources. The rule must return a list of <code class="computeroutput">virtual-target</code>
 665       instances. The interface of the <code class="computeroutput">virtual-target</code> class can be
 666       learned by looking at the <code class="filename">build/virtual-target.jam</code>
 667       file. The <code class="filename">generate</code> example contained in the
 668       Boost.Build distribution illustrates how the <code class="literal">generate</code>
 669       rule can be used.
 670     </p>
 671 </div>
 672 <div class="section">
 673 <div class="titlepage"><div><div><h3 class="title">
 674 <a name="bbv2.reference.precompiled_headers"></a>Precompiled Headers</h3></div></div></div>
 675 <p>
 676       Precompiled headers is a mechanism to speed up compilation by creating a
 677       partially processed version of some header files, and then using that
 678       version during compilations rather then repeatedly parsing the original
 679       headers. Boost.Build supports precompiled headers with gcc and msvc
 680       toolsets.
 681     </p>
 682 <p>
 683       To use precompiled headers, follow the following steps:
 684     </p>
 685 <div class="orderedlist"><ol class="orderedlist" type="1">
 686 <li class="listitem"><p>
 687           Create a header that includes headers used by your project that you
 688           want precompiled. It is better to include only headers that are
 689           sufficiently stable &#8212; like headers from the compiler and
 690           external libraries. Please wrap the header in <code class="computeroutput">#ifdef
 691           BOOST_BUILD_PCH_ENABLED</code>, so that the potentially expensive
 692           inclusion of headers is not done when PCH is not enabled. Include the
 693           new header at the top of your source files.
 694         </p></li>
 695 <li class="listitem">
 696 <p>
 697           Declare a new Boost.Build target for the precompiled header and add
 698           that precompiled header to the sources of the target whose compilation
 699           you want to speed up:
 700 </p>
 701 <pre class="programlisting">
 702 cpp-pch pch : pch.hpp ;
 703 exe main : main.cpp pch ;
 704 </pre>
 705 <p>
 706           You can use the <code class="computeroutput">c-pch</code> rule if you want to
 707           use the precompiled header in C programs.
 708         </p>
 709 </li>
 710 </ol></div>
 711 <p>
 712       The <code class="filename">pch</code> example in Boost.Build distribution can be
 713       used as reference.
 714     </p>
 715 <p>
 716       Please note the following:
 717     </p>
 718 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 719 <li class="listitem"><p>
 720           The inclusion of the precompiled header must be the first thing in a
 721           source file, before any code or preprocessor directives.
 722         </p></li>
 723 <li class="listitem"><p>
 724           The build properties used to compile the source files and the
 725           precompiled header must be the same. Consider using project
 726           requirements to assure this.
 727         </p></li>
 728 <li class="listitem"><p>
 729           Precompiled headers must be used purely as a way to improve
 730           compilation time, not to save the number of <code class="computeroutput">#include</code>
 731           statements. If a source file needs to include some header, explicitly
 732           include it in the source file, even if the same header is included
 733           from the precompiled header. This makes sure that your project will
 734           build even if precompiled headers are not supported.
 735         </p></li>
 736 <li class="listitem"><p>
 737           On the gcc compiler, the name of the header being precompiled must be
 738           equal to the name of the <code class="computeroutput">cpp-pch</code> target. This is a gcc
 739           requirement.
 740         </p></li>
 741 <li class="listitem"><p>
 742           Prior to version 4.2, the gcc compiler did not allow anonymous
 743           namespaces in precompiled headers, which limits their utility. See the
 744           <a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=29085" target="_top"> bug
 745           report</a> for details.
 746         </p></li>
 747 </ul></div>
 748 </div>
 749 <div class="section">
 750 <div class="titlepage"><div><div><h3 class="title">
 751 <a name="bbv2.reference.generated_headers"></a>Generated headers</h3></div></div></div>
 752 <p>
 753       Usually, Boost.Build handles implicit dependendies completely
 754       automatically. For example, for C++ files, all <code class="literal">#include</code>
 755       statements are found and handled. The only aspect where user help might be
 756       needed is implicit dependency on generated files.
 757     </p>
 758 <p>
 759       By default, Boost.Build handles such dependencies within one main target.
 760       For example, assume that main target "app" has two sources, "app.cpp" and
 761       "parser.y". The latter source is converted into "parser.c" and "parser.h".
 762       Then, if "app.cpp" includes "parser.h", Boost.Build will detect this
 763       dependency. Moreover, since "parser.h" will be generated into a build
 764       directory, the path to that directory will automatically be added to the include
 765       path.
 766     </p>
 767 <p>
 768       Making this mechanism work across main target boundaries is possible, but
 769       imposes certain overhead. For that reason, if there is implicit dependency
 770       on files from other main targets, the <code class="literal">&lt;implicit-dependency&gt;
 771       </code> feature must be used, for example:
 772 </p>
 773 <pre class="programlisting">
 774 lib parser : parser.y ;
 775 exe app : app.cpp : &lt;implicit-dependency&gt;parser ;
 776 </pre>
 777 <p>
 778       The above example tells the build system that when scanning all sources of
 779       "app" for implicit-dependencies, it should consider targets from "parser"
 780       as potential dependencies.
 781     </p>
 782 </div>
 783 <div class="section">
 784 <div class="titlepage"><div><div><h3 class="title">
 785 <a name="bbv2.tasks.crosscompile"></a>Cross-compilation</h3></div></div></div>
 786 <a class="indexterm" name="idp637253296"></a><p>Boost.Build supports cross compilation with the gcc and msvc
 787     toolsets.</p>
 788 <p>
 789       When using gcc, you first need to specify your cross compiler
 790       in <code class="filename">user-config.jam</code> (see <a class="xref" href="overview.html#bbv2.overview.configuration" title="Configuration">the section called &#8220;Configuration&#8221;</a>),
 791       for example:</p>
 792 <pre class="programlisting">
 793 using gcc : arm : arm-none-linux-gnueabi-g++ ;
 794 </pre>
 795 <p>
 796       After that, if the host and target os are the same, for example Linux, you can
 797       just request that this compiler version be used:
 798     </p>
 799 <pre class="screen">
 800 b2 toolset=gcc-arm
 801 </pre>
 802 <p>
 803       If you want to target a different operating system from the host, you need
 804       to additionally specify the value for the <code class="computeroutput">target-os</code> feature, for
 805       example:
 806     </p>
 807 <pre class="screen">
 808 # On windows box
 809 b2 toolset=gcc-arm <span class="bold"><strong>target-os=linux</strong></span>
 810 # On Linux box
 811 b2 toolset=gcc-mingw <span class="bold"><strong>target-os=windows</strong></span>
 812 </pre>
 813 <p>
 814       For the complete list of allowed opeating system names, please see the documentation for
 815       <a class="link" href="reference.html#bbv2.reference.features.target-os">target-os feature</a>.
 816     </p>
 817 <p>
 818       When using the msvc compiler, it's only possible to cross-compile to a 64-bit system
 819       on a 32-bit host. Please see <a class="xref" href="reference.html#v2.reference.tools.compiler.msvc.64" title="64-bit support">the section called &#8220;64-bit support&#8221;</a> for
 820       details.
 821     </p>
 822 </div>
 823 <div class="footnotes">
 824 <br><hr style="width:100; text-align:left;margin-left: 0">
 825 <div id="ftn.idp637139920" class="footnote"><p><a href="#idp637139920" class="para"><sup class="para">[18] </sup></a>see the definition of "free" in <a class="xref" href="reference.html#bbv2.reference.features.attributes" title="Feature Attributes">the section called &#8220;Feature Attributes&#8221;</a>.</p></div>
 826 </div>
 827 </div>
 828 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 829 <td align="left"></td>
 830 <td align="right"><div class="copyright-footer"></div></td>
 831 </tr></table>
 832 <hr>
 833 <div class="spirit-nav">
 834 <a accesskey="p" href="overview.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="reference.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
 835 </div>
 836 </body>
 837 </html>