| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> |
| <title>Common tasks</title> |
| <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> |
| <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> |
| <link rel="up" href="../bbv2.html" title="Chapter 33. Boost.Build V2 User Manual"> |
| <link rel="prev" href="overview.html" title="Overview"> |
| <link rel="next" href="reference.html" title="Reference"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table cellpadding="2" width="100%"><tr> |
| <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> |
| <td align="center"><a href="../../../index.html">Home</a></td> |
| <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> |
| <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> |
| <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> |
| <td align="center"><a href="../../../more/index.htm">More</a></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <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> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="bbv2.tasks"></a>Common tasks</h2></div></div></div> |
| <div class="toc"><dl> |
| <dt><span class="section"><a href="tasks.html#bbv2.tasks.programs">Programs</a></span></dt> |
| <dt><span class="section"><a href="tasks.html#bbv2.tasks.libraries">Libraries</a></span></dt> |
| <dt><span class="section"><a href="tasks.html#bbv2.tasks.alias">Alias</a></span></dt> |
| <dt><span class="section"><a href="tasks.html#bbv2.tasks.installing">Installing</a></span></dt> |
| <dt><span class="section"><a href="tasks.html#bbv2.builtins.testing">Testing</a></span></dt> |
| <dt><span class="section"><a href="tasks.html#bbv2.builtins.raw">Custom commands</a></span></dt> |
| <dt><span class="section"><a href="tasks.html#bbv2.reference.precompiled_headers">Precompiled Headers</a></span></dt> |
| <dt><span class="section"><a href="tasks.html#bbv2.reference.generated_headers">Generated headers</a></span></dt> |
| <dt><span class="section"><a href="tasks.html#bbv2.tasks.crosscompile">Cross-compilation</a></span></dt> |
| </dl></div> |
| <p> |
| This section describes main targets types that Boost.Build supports |
| out-of-the-box. Unless otherwise noted, all mentioned main target rules have |
| the common signature, described in <a class="xref" href="overview.html#bbv2.overview.targets" title="Declaring Targets">the section called “Declaring Targets”</a>. |
| </p> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.tasks.programs"></a>Programs</h3></div></div></div> |
| <a class="indexterm" name="id3270009"></a><p> |
| Programs are created using the <code class="computeroutput">exe</code> rule, which follows the |
| <a class="link" href="overview.html#bbv2.main-target-rule-syntax">common syntax</a>. For |
| example: |
| </p> |
| <pre class="programlisting"> |
| exe hello : hello.cpp some_library.lib /some_project//library |
| : <threading>multi |
| ; |
| </pre> |
| <p> |
| This will create an executable file from the sources -- in this case, one |
| C++ file, one library file present in the same directory, and another |
| library that is created by Boost.Build. Generally, sources can include C |
| and C++ files, object files and libraries. Boost.Build will automatically |
| try to convert targets of other types. |
| </p> |
| <div class="tip"><table border="0" summary="Tip"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../doc/src/images/tip.png"></td> |
| <th align="left">Tip</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| On Windows, if an application uses shared libraries, and both the |
| application and the libraries are built using Boost.Build, it is not |
| possible to immediately run the application, because the <code class="literal">PATH |
| </code> environment variable should include the path to the |
| libraries. It means you have to either add the paths manually, or have |
| the build place the application and the libraries into the same |
| directory. See <a class="xref" href="tasks.html#bbv2.tasks.installing" title="Installing">the section called “Installing”</a>. |
| </p></td></tr> |
| </table></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.tasks.libraries"></a>Libraries</h3></div></div></div> |
| <p> |
| Library targets are created using the <code class="computeroutput">lib</code> rule, which |
| follows the <a class="link" href="overview.html#bbv2.main-target-rule-syntax">common syntax |
| </a>. For example: |
| </p> |
| <pre class="programlisting"> |
| lib helpers : helpers.cpp ; |
| </pre> |
| <p> |
| This will define a library target named <code class="computeroutput">helpers</code> built from |
| the <code class="computeroutput">helpers.cpp</code> source file. |
| </p> |
| <p> |
| Depending on the given <link> feature value the library will be |
| either static or shared. |
| </p> |
| <p> |
| Library targets may be used to represent: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"><p> |
| <code class="computeroutput">Built libraries</code> that get built from specified sources, |
| as is the one in the example above. |
| </p></li> |
| <li class="listitem"><p> |
| <code class="computeroutput">Prebuilt libraries</code> which already exist on the system |
| and are just supposed to be used by the build system. Such |
| libraries may be searched for by the tools using them (typically |
| linkers referencing the library using the <code class="option">-l</code> |
| option) or their path may be known in advance by the build system. |
| |
| </p></li> |
| </ul></div> |
| <p> |
| </p> |
| <p> |
| The syntax for these case is given below: |
| </p> |
| <pre class="programlisting"> |
| lib z : : <name>z <search>/home/ghost ; |
| lib compress : : <file>/opt/libs/compress.a ; |
| </pre> |
| <p> |
| The <code class="computeroutput">name</code> property specifies the name that should be passed to |
| the <code class="option">-l</code> option, and the <code class="computeroutput">file</code> property |
| specifies the file location. The <code class="varname">search</code> feature |
| specifies paths in which to search for the library. That feature can be |
| specified several times or it can be omitted, in which case only the |
| default compiler paths will be searched. |
| </p> |
| <p> |
| The difference between using the <code class="varname">file</code> feature as |
| opposed to the <code class="varname">name</code> feature together with the <code class="varname"> |
| search</code> feature is that <code class="varname">file</code> is more precise. |
| A specific file will be used as opposed to the <code class="varname">search</code> |
| feature only adding a library path, or the <code class="varname">name</code> feature |
| giving only the basic name of the library. The search rules are specific |
| to the linker used. For example, given these definition: |
| </p> |
| <pre class="programlisting"> |
| lib a : : <variant>release <file>/pool/release/a.so ; |
| lib a : : <variant>debug <file>/pool/debug/a.so ; |
| lib b : : <variant>release <file>/pool/release/b.so ; |
| lib b : : <variant>debug <file>/pool/debug/b.so ; |
| </pre> |
| <p> |
| It is possible to use a release version of <code class="computeroutput">a</code> and debug |
| version of <code class="computeroutput">b</code>. Had we used the <code class="varname">name</code> and |
| <code class="varname">search</code> features, the linker would have always picked |
| either the release or the debug versions. |
| |
| </p> |
| <p> |
| For convenience, the following syntax is allowed: |
| </p> |
| <pre class="programlisting"> |
| lib z ; |
| lib gui db aux ; |
| </pre> |
| <p> |
| which has exactly the same effect as: |
| </p> |
| <pre class="programlisting"> |
| lib z : : <name>z ; |
| lib gui : : <name>gui ; |
| lib db : : <name>db ; |
| lib aux : : <name>aux ; |
| </pre> |
| <p> |
| </p> |
| <p> |
| When a library references another library you should put that other |
| library in its list of sources. This will do the right thing in all cases. |
| For portability, you should specify |
| library dependencies even for searched and prebuilt libraries, othewise, |
| static linking on Unix will not work. For example: |
| </p> |
| <pre class="programlisting"> |
| lib z ; |
| lib png : z : <name>png ; |
| </pre> |
| <p> |
| </p> |
| <div class="note"><table border="0" summary="Note"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> |
| <th align="left">Note</th> |
| </tr> |
| <tr><td align="left" valign="top"> |
| <p> |
| When a library has a shared library defined as its source, or a static |
| library has another static library defined as its source then any target |
| linking to the first library with automatically link to its source |
| library as well. |
| </p> |
| <p> |
| On the other hand, when a shared library has a static library defined as |
| its source then the first library will be built so that it completely |
| includes the second one. |
| </p> |
| <p> |
| If you do not want shared libraries to include all libraries specified |
| in its sources (especially statically linked ones), you would need to |
| use the following: |
| </p> |
| <pre class="programlisting"> |
| lib b : a.cpp ; |
| lib a : a.cpp : <use>b : : <library>b ; |
| </pre> |
| <p> |
| This specifies that library <code class="computeroutput">a</code> uses library <code class="computeroutput">b</code>, |
| and causes all executables that link to <code class="computeroutput">a</code> also link to |
| <code class="computeroutput">b</code>. In this case, even for shared linking, the |
| <code class="computeroutput">a</code> library will not even refer to <code class="computeroutput">b</code>. |
| </p> |
| </td></tr> |
| </table></div> |
| <p> |
| One Boost.Build feature that is often very useful for defining library |
| targets are usage requirements. For example, imagine that |
| you want you build a <code class="computeroutput">helpers</code> library and its interface is |
| described in its <code class="computeroutput">helpers.hpp</code> header file located in the same |
| directory as the <code class="computeroutput">helpers.cpp</code> source file. Then you could add |
| the following to the Jamfile located in that same directory: |
| </p> |
| <pre class="programlisting"> |
| lib helpers : helpers.cpp : : : <include>. ; |
| </pre> |
| <p> |
| which would automatically add the directory where the target has been |
| defined (and where the library's header file is located) to the compiler's |
| include path for all targets using the <code class="computeroutput">helpers</code> library. This |
| feature greatly simplifies Jamfiles. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.tasks.alias"></a>Alias</h3></div></div></div> |
| <p> |
| The <code class="computeroutput">alias</code> rule gives an alternative name to a |
| group of targets. For example, to give the name <code class="filename">core</code> |
| to a group of three other targets with the following code: |
| </p> |
| <pre class="programlisting"> |
| alias core : im reader writer ; |
| </pre> |
| <p> |
| Using <code class="filename">core</code> on the command line, or in the source list |
| of any other target is the same as explicitly using <code class="filename">im |
| </code>, <code class="filename">reader</code>, and <code class="filename">writer</code>. |
| </p> |
| <p> |
| Another use of the <code class="computeroutput">alias</code> rule is to change build properties. |
| For example, if you want to use link statically to the Boost Threads |
| library, you can write the following: |
| </p> |
| <pre class="programlisting"> |
| alias threads : /boost/thread//boost_thread : <link>static ; |
| </pre> |
| <p> |
| and use only the <code class="computeroutput">threads</code> alias in your Jamfiles. |
| </p> |
| <p> |
| You can also specify usage requirements for the <code class="computeroutput">alias</code> target. |
| If you write the following: |
| </p> |
| <pre class="programlisting"> |
| alias header_only_library : : : : <include>/usr/include/header_only_library ; |
| </pre> |
| <p> |
| then using <code class="computeroutput">header_only_library</code> in sources will only add an |
| include path. Also note that when an alias has sources, their usage |
| requirements are propagated as well. For example: |
| </p> |
| <pre class="programlisting"> |
| lib library1 : library1.cpp : : : <include>/library/include1 ; |
| lib library2 : library2.cpp : : : <include>/library/include2 ; |
| alias static_libraries : library1 library2 : <link>static ; |
| exe main : main.cpp static_libraries ; |
| </pre> |
| <p> |
| will compile <code class="filename">main.cpp</code> with additional includes |
| required for using the specified static libraries. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.tasks.installing"></a>Installing</h3></div></div></div> |
| <p> |
| This section describes various ways to install built target and arbitrary |
| files. |
| </p> |
| <h4> |
| <a name="id3270567"></a>Basic install</h4> |
| <p> |
| For installing a built target you should use the <code class="computeroutput">install</code> |
| rule, which follows the <a class="link" href="overview.html#bbv2.main-target-rule-syntax"> |
| common syntax</a>. For example: |
| </p> |
| <pre class="programlisting"> |
| install dist : hello helpers ; |
| </pre> |
| <p> |
| will cause the targets <code class="computeroutput">hello</code> and <code class="computeroutput">helpers</code> to be |
| moved to the <code class="filename">dist</code> directory, relative to the |
| Jamfile's directory. The directory can be changed using the |
| <code class="computeroutput">location</code> property: |
| </p> |
| <pre class="programlisting"> |
| install dist : hello helpers : <location>/usr/bin ; |
| </pre> |
| <p> |
| While you can achieve the same effect by changing the target name to |
| <code class="filename">/usr/bin</code>, using the <code class="computeroutput">location</code> property is |
| better as it allows you to use a mnemonic target name. |
| </p> |
| <p> |
| The <code class="computeroutput">location</code> property is especially handy when the location |
| is not fixed, but depends on the build variant or environment variables: |
| </p> |
| <pre class="programlisting"> |
| install dist : hello helpers : |
| <variant>release:<location>dist/release |
| <variant>debug:<location>dist/debug ; |
| install dist2 : hello helpers : <location>$(DIST) ; |
| </pre> |
| <p> |
| See also <a class="link" href="reference.html#bbv2.reference.variants.propcond" title="Conditional properties">conditional |
| properties</a> and <a class="link" href="faq.html#bbv2.faq.envar" title="Accessing environment variables">environment |
| variables</a> |
| </p> |
| <h4> |
| <a name="id3270680"></a>Installing with all dependencies</h4> |
| <p> |
| Specifying the names of all libraries to install can be boring. The |
| <code class="computeroutput">install</code> allows you to specify only the top-level executable |
| targets to install, and automatically install all dependencies: |
| </p> |
| <pre class="programlisting"> |
| install dist : hello |
| : <install-dependencies>on <install-type>EXE |
| <install-type>LIB |
| ; |
| </pre> |
| <p> |
| will find all targets that <code class="computeroutput">hello</code> depends on, and install all |
| of those which are either executables or libraries. More specifically, for |
| each target, other targets that were specified as sources or as dependency |
| properties, will be recursively found. One exception is that targets |
| referred with the <a class="link" href="reference.html#bbv2.builtin.features.use"> |
| <code class="computeroutput">use</code></a> feature are not considered, as that feature is |
| typically used to refer to header-only libraries. If the set of target |
| types is specified, only targets of that type will be installed, |
| otherwise, all found target will be installed. |
| </p> |
| <h4> |
| <a name="id3270733"></a>Preserving Directory Hierarchy</h4> |
| <a class="indexterm" name="id3270736"></a><p> |
| By default, the <code class="computeroutput">install</code> rule will strip paths from its |
| sources. So, if sources include <code class="filename">a/b/c.hpp</code>, the |
| <code class="filename">a/b</code> part will be ignored. To make the |
| <code class="computeroutput">install</code> rule preserve the directory hierarchy you need to |
| use the <code class="literal"><install-source-root></code> feature to specify |
| the root of the hierarchy you are installing. Relative paths from that |
| root will be preserved. For example, if you write: |
| </p> |
| <pre class="programlisting"> |
| install headers |
| : a/b/c.h |
| : <location>/tmp <install-source-root>a |
| ; |
| </pre> |
| <p> |
| the a file named <code class="filename">/tmp/b/c.h</code> will be created. |
| </p> |
| <p> |
| The <a class="link" href="reference.html#bbv2.reference.glob-tree">glob-tree</a> rule can be |
| used to find all files below a given directory, making it easy to install |
| an entire directory tree. |
| </p> |
| <h4> |
| <a name="id3270812"></a>Installing into Several Directories</h4> |
| <p> |
| The <a class="link" href="tasks.html#bbv2.tasks.alias" title="Alias"><code class="computeroutput">alias</code></a> rule can be |
| used when targets need to be installed into several directories: |
| </p> |
| <pre class="programlisting"> |
| alias install : install-bin install-lib ; |
| install install-bin : applications : /usr/bin ; |
| install install-lib : helper : /usr/lib ; |
| </pre> |
| <p> |
| </p> |
| <p> |
| Because the <code class="computeroutput">install</code> rule just copies targets, most free |
| features <sup>[<a name="id3270848" href="#ftn.id3270848" class="footnote">13</a>]</sup> have no |
| effect when used in requirements of the <code class="computeroutput">install</code> rule. The |
| only two that matter are <a class="link" href="reference.html#bbv2.builtin.features.dependency"> |
| <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> |
| </a>. |
| </p> |
| <div class="note"><table border="0" summary="Note"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> |
| <th align="left">Note</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| (Unix specific) On Unix, executables built using Boost.Build typically |
| contain the list of paths to all used shared libraries. For installing, |
| this is not desired, so Boost.Build relinks the executable with an empty |
| list of paths. You can also specify additional paths for installed |
| executables using the <code class="varname">dll-path</code> feature. |
| </p></td></tr> |
| </table></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.builtins.testing"></a>Testing</h3></div></div></div> |
| <p> |
| Boost.Build has convenient support for running unit tests. The simplest |
| 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: |
| </p> |
| <pre class="programlisting"> |
| unit-test helpers_test : helpers_test.cpp helpers ; |
| </pre> |
| <p> |
| </p> |
| <p> |
| The <code class="computeroutput">unit-test</code> rule behaves like the |
| <code class="computeroutput">exe</code> rule, but after the executable is created |
| it is also run. If the executable returns an error code, the build system |
| will also return an error and will try running the executable on the next |
| invocation until it runs successfully. This behaviour ensures that you can |
| not miss a unit test failure. |
| </p> |
| <p> |
| By default, the executable is run directly. Sometimes, it is desirable to |
| run the executable using some helper command. You should use the <code class="literal"> |
| testing.launcher</code> property to specify the name of the helper |
| command. For example, if you write: |
| </p> |
| <pre class="programlisting"> |
| unit-test helpers_test |
| : helpers_test.cpp helpers |
| : <span class="bold"><strong><testing.launcher>valgrind</strong></span> |
| ; |
| </pre> |
| <p> |
| The command used to run the executable will be: |
| </p> |
| <pre class="screen"> |
| <span class="bold"><strong>valgrind</strong></span> bin/$toolset/debug/helpers_test |
| </pre> |
| <p> |
| </p> |
| <p> |
| There are few specialized testing rules, listed below: |
| </p> |
| <pre class="programlisting"> |
| rule compile ( sources : requirements * : target-name ? ) |
| rule compile-fail ( sources : requirements * : target-name ? ) |
| rule link ( sources + : requirements * : target-name ? ) |
| rule link-fail ( sources + : requirements * : target-name ? ) |
| </pre> |
| <p> |
| They are given a list of sources and requirements. If the target name is |
| not provided, the name of the first source file is used instead. The |
| <code class="literal">compile*</code> tests try to compile the passed source. The |
| <code class="literal">link*</code> rules try to compile and link an application from |
| all the passed sources. The <code class="literal">compile</code> and <code class="literal">link |
| </code> rules expect that compilation/linking succeeds. The <code class="literal"> |
| compile-fail</code> and <code class="literal">link-fail</code> rules expect that |
| the compilation/linking fails. |
| </p> |
| <p> |
| There are two specialized rules for running applications, which are more |
| powerful than the <code class="computeroutput">unit-test</code> rule. The <code class="computeroutput">run</code> rule |
| has the following signature: |
| </p> |
| <pre class="programlisting"> |
| rule run ( sources + : args * : input-files * : requirements * : target-name ? |
| : default-build * ) |
| </pre> |
| <p> |
| The rule builds application from the provided sources and runs it, passing |
| <code class="varname">args</code> and <code class="varname">input-files</code> as command-line |
| arguments. The <code class="varname">args</code> parameter is passed verbatim and |
| the values of the <code class="varname">input-files</code> parameter are treated as |
| paths relative to containing Jamfile, and are adjusted if <span class="command"><strong>bjam |
| </strong></span> is invoked from a different directory. The |
| <code class="computeroutput">run-fail</code> rule is identical to the <code class="computeroutput">run</code> rule, |
| except that it expects that the run fails. |
| </p> |
| <p> |
| All rules described in this section, if executed successfully, create a |
| special manifest file to indicate that the test passed. For the |
| <code class="computeroutput">unit-test</code> rule the files is named <code class="filename"><em class="replaceable"><code> |
| target-name</code></em>.passed</code> and for the other rules it is |
| called <code class="filename"><em class="replaceable"><code>target-name</code></em>.test</code>. |
| The <code class="computeroutput">run*</code> rules also capture all output from the program, and |
| store it in a file named <code class="filename"><em class="replaceable"><code> |
| target-name</code></em>.output</code>. |
| </p> |
| <p> |
| <a class="indexterm" name="id3271169"></a> |
| If the <code class="literal">preserve-test-targets</code> feature has the value |
| <code class="literal">off</code>, then <code class="computeroutput">run</code> and the <code class="computeroutput">run-fail</code> |
| rules will remove the executable after running it. This somewhat decreases |
| disk space requirements for continuous testing environments. The default |
| value of <code class="literal">preserve-test-targets</code> feature is <code class="literal">on</code>. |
| </p> |
| <p> |
| It is possible to print the list of all test targets (except for |
| <code class="computeroutput">unit-test</code>) declared in your project, by passing the <code class="literal"> |
| --dump-tests</code> command-line option. The output will consist of |
| lines of the form: |
| </p> |
| <pre class="screen"> |
| boost-test(<em class="replaceable"><code>test-type</code></em>) <em class="replaceable"><code>path</code></em> : <em class="replaceable"><code>sources</code></em> |
| </pre> |
| <p> |
| </p> |
| <p> |
| It is possible to process the list of tests, the output of bjam during |
| command run, and the presense/absense of the <code class="filename">*.test</code> |
| files created when test passes into human-readable status table of tests. |
| Such processing utilities are not included in Boost.Build. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.builtins.raw"></a>Custom commands</h3></div></div></div> |
| <p> |
| When you use most of main target rules, Boost.Build automatically figures |
| what commands to run and it what order. As soon as you want to use new |
| file types or support new tools, one approach is to extend Boost.Build to |
| smoothly support them, as documented in <a class="xref" href="extender.html" title="Extender Manual">the section called “Extender Manual”</a>. |
| However, if there is only a single place where the new tool is used, it |
| might be easier to just explicitly specify the commands to run. |
| </p> |
| <p> |
| |
| Three main target rules can be used for that. The <code class="computeroutput">make |
| </code> rule allows you to construct a single file from any number |
| of source file, by running a command you specify. The <code class="computeroutput"> |
| notfile</code> rule allows you to run an arbitrary command, |
| without creating any files. And finaly, the <code class="computeroutput">generate |
| </code> rule allows you to describe transformation using |
| Boost.Build's virtual targets. This is higher-level than file names that |
| the <code class="computeroutput">make</code> rule operates with and allows you to |
| create more than one target, create differently named targets depending on |
| properties or use more than one tool. |
| </p> |
| <p> |
| The <code class="computeroutput">make</code> rule is used when you want to create |
| one file from a number of sources using some specific command. The |
| <code class="computeroutput">notfile</code> is used to unconditionally run a |
| command. |
| </p> |
| <p> |
| Suppose you want to create file <code class="filename">file.out</code> from file |
| <code class="filename">file.in</code> by running command <span class="command"><strong> |
| in2out</strong></span>. Here is how you would do this in Boost.Build: |
| </p> |
| <pre class="programlisting"> |
| make file.out : file.in : @in2out ; |
| actions in2out |
| { |
| in2out $(<) $(>) |
| } |
| </pre> |
| <p> |
| If you run <span class="command"><strong>bjam</strong></span> and <code class="filename">file.out</code> does |
| not exist, Boost.Build will run the <span class="command"><strong>in2out</strong></span> command to |
| create that file. For more details on specifying actions, see <a class="xref" href="overview.html#bbv2.overview.jam_language.actions">the section called “Boost.Jam Language”</a>. |
| </p> |
| <p> |
| It could be that you just want to run some command unconditionally, and |
| that command does not create any specific files. For that you can use the |
| <code class="computeroutput">notfile</code> rule. For example: |
| </p> |
| <pre class="programlisting"> |
| notfile echo_something : @echo ; |
| actions echo |
| { |
| echo "something" |
| } |
| </pre> |
| <p> |
| The only difference from the <code class="computeroutput">make</code> rule is |
| that the name of the target is not considered a name of a file, so |
| Boost.Build will unconditionally run the action. |
| </p> |
| <p> |
| |
| The <code class="computeroutput">generate</code> rule is used when you want to |
| express transformations using Boost.Build's virtual targets, as opposed to |
| just filenames. The <code class="computeroutput">generate</code> rule has the |
| standard main target rule signature, but you are required to specify the |
| <code class="literal">generating-rule</code> property. The value of the property |
| should be in the form <code class="literal"> |
| @<em class="replaceable"><code>rule-name</code></em></code>, the named rule should |
| have the following signature: |
| </p> |
| <pre class="programlisting"> |
| rule generating-rule ( project name : property-set : sources * ) |
| </pre> |
| <p> |
| and will be called with an instance of the <code class="computeroutput">project-target</code> |
| class, the name of the main target, an instance of the |
| <code class="computeroutput">property-set</code> class containing build properties, and the list |
| of instances of the <code class="computeroutput">virtual-target</code> class corresponding to |
| sources. The rule must return a list of <code class="computeroutput">virtual-target</code> |
| instances. The interface of the <code class="computeroutput">virtual-target</code> class can be |
| learned by looking at the <code class="filename">build/virtual-target.jam</code> |
| file. The <code class="filename">generate</code> example contained in the |
| Boost.Build distribution illustrates how the <code class="literal">generate</code> |
| rule can be used. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.reference.precompiled_headers"></a>Precompiled Headers</h3></div></div></div> |
| <p> |
| Precompiled headers is a mechanism to speed up compilation by creating a |
| partially processed version of some header files, and then using that |
| version during compilations rather then repeatedly parsing the original |
| headers. Boost.Build supports precompiled headers with gcc and msvc |
| toolsets. |
| </p> |
| <p> |
| To use precompiled headers, follow the following steps: |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="1"> |
| <li class="listitem"><p> |
| Create a header that includes headers used by your project that you |
| want precompiled. It is better to include only headers that are |
| sufficiently stable — like headers from the compiler and |
| external libraries. Please wrap the header in <code class="computeroutput">#ifdef |
| BOOST_BUILD_PCH_ENABLED</code>, so that the potentially expensive |
| inclusion of headers is not done when PCH is not enabled. Include the |
| new header at the top of your source files. |
| </p></li> |
| <li class="listitem"> |
| <p> |
| Declare a new Boost.Build target for the precompiled header and add |
| that precompiled header to the sources of the target whose compilation |
| you want to speed up: |
| </p> |
| <pre class="programlisting"> |
| cpp-pch pch : pch.hpp ; |
| exe main : main.cpp pch ; |
| </pre> |
| <p> |
| You can use the <code class="computeroutput">c-pch</code> rule if you want to |
| use the precompiled header in C programs. |
| </p> |
| </li> |
| </ol></div> |
| <p> |
| The <code class="filename">pch</code> example in Boost.Build distribution can be |
| used as reference. |
| </p> |
| <p> |
| Please note the following: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"><p> |
| The inclusion of the precompiled header must be the first thing in a |
| source file, before any code or preprocessor directives. |
| </p></li> |
| <li class="listitem"><p> |
| The build properties used to compile the source files and the |
| precompiled header must be the same. Consider using project |
| requirements to assure this. |
| </p></li> |
| <li class="listitem"><p> |
| Precompiled headers must be used purely as a way to improve |
| compilation time, not to save the number of <code class="computeroutput">#include</code> |
| statements. If a source file needs to include some header, explicitly |
| include it in the source file, even if the same header is included |
| from the precompiled header. This makes sure that your project will |
| build even if precompiled headers are not supported. |
| </p></li> |
| <li class="listitem"><p> |
| On the gcc compiler, the name of the header being precompiled must be |
| equal to the name of the <code class="computeroutput">cpp-pch</code> target. This is a gcc |
| requirement. |
| </p></li> |
| <li class="listitem"><p> |
| Prior to version 4.2, the gcc compiler did not allow anonymous |
| namespaces in precompiled headers, which limits their utility. See the |
| <a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=29085" target="_top"> bug |
| report</a> for details. |
| </p></li> |
| </ul></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.reference.generated_headers"></a>Generated headers</h3></div></div></div> |
| <p> |
| Usually, Boost.Build handles implicit dependendies completely |
| automatically. For example, for C++ files, all <code class="literal">#include</code> |
| statements are found and handled. The only aspect where user help might be |
| needed is implicit dependency on generated files. |
| </p> |
| <p> |
| By default, Boost.Build handles such dependencies within one main target. |
| For example, assume that main target "app" has two sources, "app.cpp" and |
| "parser.y". The latter source is converted into "parser.c" and "parser.h". |
| Then, if "app.cpp" includes "parser.h", Boost.Build will detect this |
| dependency. Moreover, since "parser.h" will be generated into a build |
| directory, the path to that directory will automatically added to include |
| path. |
| </p> |
| <p> |
| Making this mechanism work across main target boundaries is possible, but |
| imposes certain overhead. For that reason, if there is implicit dependency |
| on files from other main targets, the <code class="literal"><implicit-dependency> |
| </code> [ link ] feature must be used, for example: |
| </p> |
| <pre class="programlisting"> |
| lib parser : parser.y ; |
| exe app : app.cpp : <implicit-dependency>parser ; |
| </pre> |
| <p> |
| The above example tells the build system that when scanning all sources of |
| "app" for implicit-dependencies, it should consider targets from "parser" |
| as potential dependencies. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.tasks.crosscompile"></a>Cross-compilation</h3></div></div></div> |
| <a class="indexterm" name="id3271759"></a><p>Boost.Build supports cross compilation with the gcc and msvc |
| toolsets.</p> |
| <p> |
| When using gcc, you first need to specify your cross compiler |
| in <code class="filename">user-config.jam</code> (see <a class="xref" href="overview.html#bbv2.overview.configuration" title="Configuration">the section called “Configuration”</a>), |
| for example:</p> |
| <pre class="programlisting"> |
| using gcc : arm : arm-none-linux-gnueabi-g++ ; |
| </pre> |
| <p> |
| After that, if the host and target os are the same, for example Linux, you can |
| just request that this compiler version to be used: |
| </p> |
| <pre class="screen"> |
| bjam toolset=gcc-arm |
| </pre> |
| <p> |
| If you want to target different operating system from the host, you need |
| to additionally specify the value for the <code class="computeroutput">target-os</code> feature, for |
| example: |
| </p> |
| <pre class="screen"> |
| # On windows box |
| bjam toolset=gcc-arm <span class="bold"><strong>target-os=linux</strong></span> |
| # On Linux box |
| bjam toolset=gcc-mingw <span class="bold"><strong>target-os=windows</strong></span> |
| </pre> |
| <p> |
| For the complete list of allowed opeating system names, please see the documentation for |
| <a class="link" href="reference.html#bbv2.reference.features.target-os">target-os feature</a>. |
| </p> |
| <p> |
| When using the msvc compiler, it's only possible to cross-compiler to a 64-bit system |
| 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 “64-bit support”</a> for |
| details. |
| </p> |
| </div> |
| <div class="footnotes"> |
| <br><hr width="100" align="left"> |
| <div class="footnote"><p><sup>[<a name="ftn.id3270848" href="#id3270848" class="para">13</a>] </sup>see the definition of "free" in <a class="xref" href="reference.html#bbv2.reference.features.attributes" title="Feature Attributes">the section called “Feature Attributes”</a>.</p></div> |
| </div> |
| </div> |
| <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> |
| <td align="left"></td> |
| <td align="right"><div class="copyright-footer">Copyright © 2006-2009 Vladimir Prus<p>Distributed under the Boost Software License, Version 1.0. |
| (See accompanying file <code class="filename">LICENSE_1_0.txt</code> or copy at |
| <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) |
| </p> |
| </div></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <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> |
| </div> |
| </body> |
| </html> |