diff options
Diffstat (limited to 'doc/html/bbv2/advanced/build_process.html')
| -rw-r--r-- | doc/html/bbv2/advanced/build_process.html | 194 |
1 files changed, 194 insertions, 0 deletions
diff --git a/doc/html/bbv2/advanced/build_process.html b/doc/html/bbv2/advanced/build_process.html new file mode 100644 index 0000000000..d65ca9bc2c --- /dev/null +++ b/doc/html/bbv2/advanced/build_process.html @@ -0,0 +1,194 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>The Build Process</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.68.1"> +<style type="text/css"> +body { background-image: url('http://docbook.sourceforge.net/release/images/draft.png'); + background-repeat: no-repeat; + background-position: top left; + /* The following properties make the watermark "fixed" on the page. */ + /* I think that's just a bit too distracting for the reader... */ + /* background-attachment: fixed; */ + /* background-position: center center; */ + }</style> +<link rel="start" href="../../index.html" title="The Boost C++ Libraries"> +<link rel="up" href="../advanced.html" title="Chapter 24. User documentation"> +<link rel="prev" href="jamfiles.html" title="Writing Jamfiles"> +<link rel="next" href="builtins/targets.html" title="Builtin target types"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"> +<td valign="top"><img alt="boost.png (6897 bytes)" width="277" height="86" src="../../../../boost.png"></td> +<td align="center"><a href="../../../../index.htm">Home</a></td> +<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="../../../../people/people.htm">People</a></td> +<td align="center"><a href="../../../../more/faq.htm">FAQ</a></td> +<td align="center"><a href="../../../../more/index.htm">More</a></td> +</table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="jamfiles.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../advanced.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="builtins/targets.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bbv2.advanced.build_process"></a>The Build Process</h2></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="build_process.html#id1704308">Build request</a></span></dt> +<dt><span class="section"><a href="build_process.html#id1704350">Building a main target</a></span></dt> +<dt><span class="section"><a href="build_process.html#id1704448">Building a project</a></span></dt> +</dl></div> +<p>When you've described your targets, you want Boost.Build to run the + right tools and create the needed targets. + + This section will describe + two things: how you specify what to build, and how the main targets are + actually constructed. + </p> +<p>The most important thing to note is that in Boost.Build, unlike + other build tools, the targets you declare do not correspond to specific + files. What you declare in a Jamfile is more like a “metatarget.” + + Depending on the properties you specify on the command line, + each metatarget will produce a set of real targets corresponding + to the requested properties. It is quite possible that the same + metatarget is built several times with different properties, + + producing different files. + </p> +<div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Tip</h3> +<p> + This means that for Boost.Build, you cannot directly obtain a build + variant from a Jamfile. There could be several variants requested by the + user, and each target can be built with different properties. + </p> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id1704308"></a>Build request</h3></div></div></div> +<p> + The command line specifies which targets to build and with which + properties. For example: +</p> +<pre class="programlisting"> +bjam app1 lib1//lib1 toolset=gcc variant=debug optimization=full +</pre> +<p> + would build two targets, "app1" and "lib1//lib1" with the specified + properties. You can refer to any targets, using + <a href="../reference/definitions.html#bbv2.reference.ids" title="Target identifiers and references">target id</a> and specify arbitrary + properties. Some of the properties are very common, and for them the name + of the property can be omitted. For example, the above can be written as: +</p> +<pre class="programlisting"> +bjam app1 lib1//lib1 gcc debug optimization=full +</pre> +<p> + The complete syntax, which has some additional shortcuts, is + described in <a href="../reference.html#bbv2.reference.commandline" title="Command line">the section called “Command line”</a>. + </p> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id1704350"></a>Building a main target</h3></div></div></div> +<p>When you request, directly or indirectly, a build of a main target + with specific requirements, the following steps are made. Some brief + explanation is provided, and more details are given in <a href="../reference/buildprocess.html" title="Build process">the section called “Build process”</a>. + </p> +<div class="orderedlist"><ol type="1"> +<li><p>Applying default build. If the default-build + property of a target specifies a value of a feature that is not + present in the build request, that value is added.</p></li> +<li><p>Selecting the main target alternative to use. For + each alternative we look how many properties are present both in + alternative's requirements, and in build request. The + alternative with large number of matching properties is selected. + </p></li> +<li><p>Determining "common" properties. + + The build request + is <a href="../reference/definitions.html#bbv2.reference.variants.proprefine" title="Property refinement">refined</a> + with target's requirements. + + The conditional properties in + requirements are handled as well. Finally, default values of + features are added. + </p></li> +<li><p>Building targets referred by the sources list and + dependency properties. The list of sources and the properties + can refer to other target using <a href="../reference/definitions.html#bbv2.reference.ids" title="Target identifiers and references">target references</a>. For each + reference, we take all <a href="../reference/definitions.html#bbv2.reference.features.attributes.propagated">propagated</a> + properties, refine them by explicit properties specified in the + target reference, and pass the resulting properties as build + request to the other target. + </p></li> +<li><p>Adding the usage requirements produced when building + dependencies to the "common" properties. When dependencies are + built in the previous step, they return + + both the set of created + "real" targets, and usage requirements. The usage requirements + are added to the common properties and the resulting property + set will be used for building the current target. + </p></li> +<li><p>Building the target using generators. To convert the + sources to the desired type, Boost.Build uses "generators" --- + objects that correspond to tools like compilers and + linkers. Each generator declares what type of targets it + + can + produce and what type of sources it requires. Using this + information, Boost.Build determines which generators must be run + to produce a specific target from specific sources. When + generators are run, they return the "real" targets. + </p></li> +<li><p>Computing the usage requirements to be returned. The + conditional properties in usage requirements are expanded + + and the + result is returned.</p></li> +</ol></div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="id1704448"></a>Building a project</h3></div></div></div> +<p>Often, a user builds a complete project, not just one main + target. In fact, invoking <span><strong class="command">bjam</strong></span> without + arguments + + builds the project defined in the current + directory.</p> +<p>When a project is built, the build request is passed without + modification to all main targets in that project. + + It's is possible to + prevent implicit building of a target in a project with the + <code class="computeroutput">explicit</code> rule: +</p> +<pre class="programlisting"> +explicit hello_test ; +</pre> +<p> + would cause the <code class="computeroutput">hello_test</code> target to be built only if + explicitly requested by the user or by some other target. + </p> +<p>The Jamfile for a project can include a number of + <code class="computeroutput">build-project</code> rule calls + + that specify additional projects + to be built. + </p> +</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"><small></small></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="jamfiles.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../advanced.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="builtins/targets.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> |