diff options
Diffstat (limited to 'doc/html/bbv2/tasks.html')
| -rwxr-xr-x | doc/html/bbv2/tasks.html | 792 |
1 files changed, 792 insertions, 0 deletions
diff --git a/doc/html/bbv2/tasks.html b/doc/html/bbv2/tasks.html new file mode 100755 index 0000000000..00e54f7b04 --- /dev/null +++ b/doc/html/bbv2/tasks.html @@ -0,0 +1,792 @@ +<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.76.1"> +<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> +<link rel="up" href="../bbv2.html" title="Chapter 39. 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="id3898100"></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="id3898659"></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="id3898771"></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="id3898824"></a>Preserving Directory Hierarchy</h4> +<a class="indexterm" name="id3898827"></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="id3898903"></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="id3898939" href="#ftn.id3898939" class="footnote">12</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="id3899260"></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="id3899849"></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 id="ftn.id3898939" href="#id3898939" class="para">12</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> |