Imported Upstream version 1.49.0upstream/1.49.0

author: Anas Nashif <anas.nashif@intel.com> 2012-10-30 12:57:26 -0700
committer: Anas Nashif <anas.nashif@intel.com> 2012-10-30 12:57:26 -0700
commit: 1a78a62555be32868418fe52f8e330c9d0f95d5a (patch)
tree: d3765a80e7d3b9640ec2e930743630cd6b9fce2b /doc/html/bbv2
download: boost-1a78a62555be32868418fe52f8e330c9d0f95d5a.tar.gz
boost-1a78a62555be32868418fe52f8e330c9d0f95d5a.tar.bz2
boost-1a78a62555be32868418fe52f8e330c9d0f95d5a.zip
7 files changed, 6496 insertions, 0 deletions
diff --git a/doc/html/bbv2/extender.html b/doc/html/bbv2/extender.html
new file mode 100755
index 0000000000..95749df283
--- /dev/null
+++ b/doc/html/bbv2/extender.html
@@ -0,0 +1,1034 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Extender Manual</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&#160;39.&#160;Boost.Build V2 User Manual">
+<link rel="prev" href="reference.html" title="Reference">
+<link rel="next" href="faq.html" title="Frequently Asked Questions">
+</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="reference.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="faq.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.extender"></a>Extender Manual</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="extender.html#bbv2.extender.intro">Introduction</a></span></dt>
+<dt><span class="section"><a href="extender.html#bbv2.extender.example">Example: 1-to-1 generator</a></span></dt>
+<dt><span class="section"><a href="extender.html#bbv2.extending.targets">Target types</a></span></dt>
+<dt><span class="section"><a href="extender.html#bbv2.extending.tools">Tools and generators</a></span></dt>
+<dt><span class="section"><a href="extender.html#bbv2.extending.features">Features</a></span></dt>
+<dt><span class="section"><a href="extender.html#bbv2.extending.rules">Main target rules</a></span></dt>
+<dt><span class="section"><a href="extender.html#bbv2.extending.toolset_modules">Toolset modules</a></span></dt>
+</dl></div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.extender.intro"></a>Introduction</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="extender.html#bbv2.extender.overview.metatargets">Metatargets</a></span></dt>
+<dt><span class="section"><a href="extender.html#bbv2.extender.overview.targets">Concrete targets</a></span></dt>
+<dt><span class="section"><a href="extender.html#bbv2.extender.overview.generators">Generators</a></span></dt>
+</dl></div>
+<p>
+        This section explains how to extend Boost.Build to accomodate your
+        local requirements&#8212;primarily to add support for non-standard
+        tools you have. Before we start, be sure you have read and understoon
+        the concept of metatarget, <a class="xref" href="overview.html#bbv2.overview.concepts" title="Concepts">the section called &#8220;Concepts&#8221;</a>,
+        which is critical to understanding the remaining material.
+      </p>
+<p>
+        The current version of Boost.Build has three levels of targets, listed
+        below.
+      </p>
+<div class="variablelist"><dl>
+<dt><span class="term">metatarget</span></dt>
+<dd><p>
+              Object that is created from declarations in Jamfiles. May
+              be called with a set of properties to produce concrete
+              targets.
+            </p></dd>
+<dt><span class="term">concrete target</span></dt>
+<dd><p>
+              Object that corresponds to a file or an action.
+            </p></dd>
+<dt><span class="term">jam target</span></dt>
+<dd><p>
+              Low-level concrete target that is specific to Boost.Jam build
+              engine. Essentially a string&#8212;most often a name of file.                
+            </p></dd>
+</dl></div>
+<p>
+        In most cases, you will only have to deal with concrete targets and
+        the process that creates concrete targets from
+        metatargets. Extending metatarget level is rarely required. The jam
+        targets are typically only used inside the command line patterns.
+      </p>
+<div class="warning"><table border="0" summary="Warning">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td>
+<th align="left">Warning</th>
+</tr>
+<tr><td align="left" valign="top"><p>All of the Boost.Jam target-related builtin functions, like
+        <code class="computeroutput">DEPENDS</code> or <code class="computeroutput">ALWAYS</code> operate on jam
+        targets. Applying them to metatargets or concrete targets has no
+        effect.</p></td></tr>
+</table></div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.extender.overview.metatargets"></a>Metatargets</h4></div></div></div>
+<p>Metatarget is an object that records information specified
+        in Jamfile, such as metatarget kind, name, sources and properties,
+        and can be called with specific properties to generate concrete
+        targets. At the code level it is represented by an instance of
+        class derived from <code class="computeroutput">abstract-target</code>. 
+        <sup>[<a name="id3906715" href="#ftn.id3906715" class="footnote">13</a>]</sup>
+        </p>
+<p>The <code class="computeroutput">generate</code> method takes the build properties
+        (as an instance of the <code class="computeroutput">property-set</code> class) and returns
+        a list containing:</p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>As front element&#8212;Usage-requirements from this invocation
+          (an instance of <code class="computeroutput">property-set</code>)</p></li>
+<li class="listitem"><p>As subsequent elements&#8212;created concrete targets (
+          instances of the <code class="computeroutput">virtual-target</code> class.)</p></li>
+</ul></div>
+<p>It's possible to lookup a metataget by target-id using the 
+        <code class="computeroutput">targets.resolve-reference</code> function, and the
+        <code class="computeroutput">targets.generate-from-reference</code> function can both
+        lookup and generate a metatarget.</p>
+<p>The <code class="computeroutput">abstract-target</code> class has three immediate
+        derived classes:</p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p><code class="computeroutput">project-target</code> that
+          corresponds to a project and is not intended for further
+          subclassing. The <code class="computeroutput">generate</code> method of this
+          class builds all targets in the project that are not marked as
+          explicit.</p></li>
+<li class="listitem"><p><code class="computeroutput">main-target</code> corresponds to a target in a project
+          and contains one or more target alternatives. This class also should not be 
+          subclassed. The <code class="computeroutput">generate</code> method of this class selects 
+          an alternative to build, and calls the <code class="computeroutput">generate</code> method of that
+          alternative.</p></li>
+<li class="listitem"><p><code class="computeroutput">basic-target</code> corresponds to a
+          specific target alternative. This is base class, with a number of
+          derived classes.  The <code class="computeroutput">generate</code> method
+          processes the target requirements and requested build properties to
+          determine final properties for the target, builds all sources, and
+          finally calls the abstract <code class="computeroutput">construct</code> method with the list
+          of source virtual targets, and the final properties.
+          </p></li>
+</ul></div>
+<p>The instances of the <code class="computeroutput">project-target</code> and
+        <code class="computeroutput">main-target</code> classes are created
+        implicitly&#8212;when loading a new Jamfiles, or when a new target
+        alternative with as-yet unknown name is created.  The instances of the
+        classes derived from <code class="computeroutput">basic-target</code> are typically
+        created when Jamfile calls a <em class="firstterm">metatarget rule</em>,
+        such as such as <code class="computeroutput">exe</code>.
+        </p>
+<p>It it permissible to create a custom class derived from
+        <code class="computeroutput">basic-target</code> and create new metatarget rule
+        that creates instance of such target. However, in the majority
+        of cases, a specific subclass of <code class="computeroutput">basic-target</code>&#8212;
+        <code class="computeroutput">typed-target</code> is used. That class is associated
+        with a <em class="firstterm">type</em> and relays to <em class="firstterm">generators</em>
+        to construct concrete targets of that type. This process will be explained below.
+        When a new type is declared, a new metatarget rule is automatically defined.
+        That rule creates new instance of type-target, associated with that type.                
+        </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.extender.overview.targets"></a>Concrete targets</h4></div></div></div>
+<p>Concrete targets are represented by instance of classes derived
+        from <code class="computeroutput">virtual-target</code>. The most commonly used
+        subclass is <code class="computeroutput">file-target</code>. A file target is associated
+        with an action that creates it&#8212; an instance of the <code class="computeroutput">action</code>
+        class. The action, in turn, hold a list of source targets. It also holds the 
+        <code class="computeroutput">property-set</code> instance with the build properties that
+        should be used for the action.</p>
+<p>Here's an example of creating a target from another target, <code class="computeroutput">source</code></p>
+<pre class="programlisting">
+local a = [ new action $(source) : common.copy : $(property-set) ] ;
+local t = [ new file-target $(name) : CPP : $(project) : $(a) ] ;
+</pre>
+<p>The first line creates an instance of the <code class="computeroutput">action&gt;</code> class.
+        The first parameter is the list of sources. The second parameter is the name
+        a jam-level <a class="link" href="overview.html#bbv2.overview.jam_language.actions">action</a>.
+        The third parameter is the property-set applying to this action. The second line
+        creates a target. We specifie a name, a type and a project. We also pass the
+        action object created earlier.  If the action creates several targets, we can repeat
+        the second line several times.</p>
+<p>In some cases, code that creates concrete targets may be invoked more than
+        once with the same properties. Returning to different instance of <code class="computeroutput">file-target</code>
+        that correspond to the same file clearly will result in problems. Therefore, whenever
+        returning targets you should pass them via the <code class="computeroutput">virtual-target.register</code>
+        function, that will replace targets with previously created identical ones, as
+        necessary.<sup>[<a name="id3907057" href="#ftn.id3907057" class="footnote">14</a>]</sup>
+        Here are a couple of examples:
+</p>
+<pre class="programlisting">
+return [ virtual-target.register $(t) ] ;
+return [ sequence.transform virtual-target.register : $(targets) ] ;
+</pre>
+<p>
+        </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.extender.overview.generators"></a>Generators</h4></div></div></div>
+<p>In theory, every kind of metatarget in Boost.Build (like <code class="computeroutput">exe</code>, 
+        <code class="computeroutput">lib</code> or <code class="computeroutput">obj</code>) could be implemented
+        by writing a new metatarget class that, independently of the other code, figures
+        what files to produce and what commands to use. However, that would be rather inflexible.
+        For example, adding support for a new compiler would require editing several metatargets.
+        </p>
+<p>In practice, most files have specific types, and most tools
+        consume and produce files of specific type. To take advantage of this
+        fact, Boost.Build defines concept of target type and
+        <a class="indexterm" name="id3907117"></a>
+        <em class="firstterm">generators</em>, and has special metatarget class
+        <code class="computeroutput">typed-target</code>.  Target type is merely an
+        identifier. It is associated with a set of file extensions that
+        correspond to that type. Generator is an abstraction of a tool. It advertises
+        the types it produces and, if called with a set of input target, tries to construct
+        output targets of the advertised types. Finally, <code class="computeroutput">typed-target</code>
+        is associated with specific target type, and relays the generator (or generators)
+        for that type.
+        </p>
+<p>A generator is an instance of a class derived from <code class="computeroutput">generator</code>.
+        The <code class="computeroutput">generator</code> class itself is suitable for common cases.
+        You can define derived classes for custom scenarios.</p>
+</div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.extender.example"></a>Example: 1-to-1 generator</h3></div></div></div>
+<p>Say you're writing an application that generates C++ code. If
+      you ever did this, you know that it's not nice. Embedding large
+      portions of C++ code in string literals is very awkward. A much
+      better solution is:</p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem">
+            Write the template of the code to be generated, leaving
+            placeholders at the points that will change
+          </li>
+<li class="listitem">
+            Access the template in your application and replace
+            placeholders with appropriate text.
+          </li>
+<li class="listitem">Write the result.</li>
+</ol></div>
+<p>It's quite easy to achieve. You write special verbatim files that are
+      just C++, except that the very first line of the file contains the name of a
+      variable that should be generated. A simple tool is created that takes a
+      verbatim file and creates a cpp file with a single <code class="computeroutput">char*</code> variable
+      whose name is taken from the first line of the verbatim file and whose value
+      is the file's properly quoted content.</p>
+<p>Let's see what Boost.Build can do.</p>
+<p>First off, Boost.Build has no idea about "verbatim files". So, you must
+      register a new target type. The following code does it:</p>
+<pre class="programlisting">
+import type ;
+type.register VERBATIM : verbatim ;
+</pre>
+<p>The first parameter to <code class="computeroutput">type.register</code> gives
+      the name of the declared type. By convention, it's uppercase. The second
+      parameter is the suffix for files of this type. So, if Boost.Build sees
+      <code class="filename">code.verbatim</code> in a list of sources, it knows that it's of
+      type <code class="computeroutput">VERBATIM</code>.</p>
+<p>Next, you tell Boost.Build that the verbatim files can be
+      transformed into C++ files in one build step.  A
+      <em class="firstterm">generator</em> is a template for a build step that
+      transforms targets of one type (or set of types) into another.  Our
+      generator will be called <code class="computeroutput">verbatim.inline-file</code>; it
+      transforms <code class="computeroutput">VERBATIM</code> files into <code class="computeroutput">CPP</code> files:
+
+</p>
+<pre class="programlisting">
+import generators ;
+generators.register-standard verbatim.inline-file : VERBATIM : CPP ;
+</pre>
+<p>
+  </p>
+<p>Lastly, you have to inform Boost.Build about the shell
+       commands used to make that transformation.  That's done with an
+       <code class="computeroutput">actions</code> declaration.
+
+</p>
+<pre class="programlisting">
+actions inline-file
+{
+    "./inline-file.py" $(&lt;) $(&gt;)
+}
+</pre>
+<p>
+
+
+
+
+</p>
+<p>
+    Now, we're ready to tie it all together. Put all the code above in file
+    <code class="filename">verbatim.jam</code>, add <code class="computeroutput">import verbatim ;</code> to
+    <code class="filename">Jamroot.jam</code>, and it's possible to write the following
+    in your Jamfile:
+  </p>
+<pre class="programlisting">
+exe codegen : codegen.cpp class_template.verbatim usage.verbatim ;
+</pre>
+<p>
+    The listed verbatim files will be automatically converted into C++ source
+    files, compiled and then linked to the codegen executable.
+  </p>
+<p>
+    In subsequent sections, we will extend this example, and review all the
+    mechanisms in detail. The complete code is available in the
+    <code class="filename">example/customization</code> directory.
+  </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.extending.targets"></a>Target types</h3></div></div></div>
+<div class="toc"><dl><dt><span class="section"><a href="extender.html#bbv2.extending.scanners">Scanners</a></span></dt></dl></div>
+<p>The first thing we did in the <a class="link" href="extender.html#bbv2.extender.intro" title="Introduction">intruduction</a> was declaring a
+      new target type:
+</p>
+<pre class="programlisting">
+import type ;
+type.register VERBATIM : verbatim ;
+</pre>
+<p>
+        The type is the most important property of a target. Boost.Build can
+        automatically generate necessary build actions only because you
+        specify the desired type (using the different main target rules), and
+        because Boost.Build can guess the type of sources from their
+        extensions.
+      </p>
+<p>The first two parameters for the <code class="computeroutput">type.register</code> rule
+        are the name of new type and the list of extensions associated with
+        it. A file with an extension from the list will have the given target
+        type. In the case where a target of the declared type is generated
+        from other sources, the first specified extension will be used.
+      </p>
+<p>Sometimes you want to change the suffix used for generated targets
+      depending on build properties, such as toolset. For example, some compiler
+      uses extension <code class="literal">elf</code> for executable files. You can use the
+      <code class="computeroutput">type.set-generated-target-suffix</code> rule:
+</p>
+<pre class="programlisting">
+type.set-generated-target-suffix EXE : &lt;toolset&gt;elf : elf ;
+</pre>
+<p>
+    </p>
+<p>A new target type can be inherited from an existing one.
+</p>
+<pre class="programlisting">
+type.register PLUGIN : : SHARED_LIB ;
+</pre>
+<p>
+      The above code defines a new type derived from
+      <code class="computeroutput">SHARED_LIB</code>. Initially, the new type inherits all the
+      properties of the base type - in particular generators and suffix.
+      Typically, you'll change the new type in some way. For example, using
+      <code class="computeroutput">type.set-generated-target-suffix</code> you can set the suffix for
+      the new type. Or you can write special a generator for the new type. For
+      example, it can generate additional metainformation for the plugin.
+      In either way, the <code class="computeroutput">PLUGIN</code> type can be used whenever
+      <code class="computeroutput">SHARED_LIB</code> can. For example, you can directly link plugins
+      to an application.
+    </p>
+<p>A type can be defined as "main", in which case Boost.Build will
+      automatically declare a main target rule for building targets of that
+      type. More details can be found <a class="link" href="extender.html#bbv2.extending.rules.main-type">later</a>.
+    </p>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.extending.scanners"></a>Scanners</h4></div></div></div>
+<p>
+          Sometimes, a file can refer to other files via some include system. To
+          make Boost.Build track dependencies between included files, you need
+          to provide a scanner. The primary limitation is that only one scanner
+          can be assigned to a target type.
+        </p>
+<p>First, we need to declare a new class for the scanner:
+</p>
+<pre class="programlisting">
+class verbatim-scanner : common-scanner
+{
+    rule pattern ( )
+    {
+        return "//###include[ ]*\"([^\"]*)\"" ;
+    }
+}
+</pre>
+<p>
+          All the complex logic is in the <code class="computeroutput">common-scanner</code>
+          class, and you only need to override the method that returns
+          the regular expression to be used for scanning. The
+          parentheses in the regular expression indicate which part
+          of the string is the name of the included file.  Only the
+          first parenthesized group in the regular expression will be
+          recognized; if you can't express everything you want that
+          way, you can return multiple regular expressions, each of
+          which contains a parenthesized group to be matched.
+        </p>
+<p>After that, we need to register our scanner class:
+</p>
+<pre class="programlisting">
+scanner.register verbatim-scanner : include ;
+</pre>
+<p>
+            The value of the second parameter, in this case
+            <code class="computeroutput">include</code>, specifies the properties that contain the list
+            of paths that should be searched for the included files.
+         </p>
+<p>Finally, we assign the new scanner to the <code class="computeroutput">VERBATIM</code>
+        target type:
+</p>
+<pre class="programlisting">
+type.set-scanner VERBATIM : verbatim-scanner ;
+</pre>
+<p>
+          That's enough for scanning include dependencies.
+        </p>
+</div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.extending.tools"></a>Tools and generators</h3></div></div></div>
+<p>
+        This section will describe how Boost.Build can be extended to support
+        new tools.
+      </p>
+<p>For each additional tool, a Boost.Build object called generator
+        must be created. That object has specific types of targets that it
+        accepts and produces. Using that information, Boost.Build is able
+        to automatically invoke the generator. For example, if you declare a
+        generator that takes a target of the type <code class="literal">D</code> and
+        produces a target of the type <code class="literal">OBJ</code>, when placing a
+        file with extention <code class="literal">.d</code> in a list of sources will
+        cause Boost.Build to invoke your generator, and then to link the
+        resulting object file into an application. (Of course, this requires
+        that you specify that the <code class="literal">.d</code> extension corresponds
+        to the <code class="literal">D</code> type.)
+      </p>
+<p>Each generator should be an instance of a class derived from the
+        <code class="computeroutput">generator</code> class. In the simplest case, you don't need to
+        create a derived class, but simply create an instance of the
+        <code class="computeroutput">generator</code> class. Let's review the example we've seen in the
+        <a class="link" href="extender.html#bbv2.extender.intro" title="Introduction">introduction</a>.
+        
+</p>
+<pre class="programlisting">
+import generators ;
+generators.register-standard verbatim.inline-file : VERBATIM : CPP ;
+actions inline-file
+{
+    "./inline-file.py" $(&lt;) $(&gt;)
+}
+</pre>
+<p>
+      </p>
+<p>We declare a standard generator, specifying its id, the source type
+        and the target type. When invoked, the generator will create a target
+        of type <code class="literal">CPP</code> with a source target of
+        type <code class="literal">VERBATIM</code> as the only source. But what command
+        will be used to actually generate the file? In bjam, actions are
+        specified using named "actions" blocks and the name of the action
+        block should be specified when creating targets. By convention,
+        generators use the same name of the action block as their own id. So,
+        in above example, the "inline-file" actions block will be used to
+        convert the source into the target.
+      </p>
+<p>
+        There are two primary kinds of generators: standard and composing,
+        which are registered with the
+        <code class="computeroutput">generators.register-standard</code> and the
+        <code class="computeroutput">generators.register-composing</code> rules, respectively. For
+        example:
+</p>
+<pre class="programlisting">
+generators.register-standard verbatim.inline-file : VERBATIM : CPP ;
+generators.register-composing mex.mex : CPP LIB : MEX ;
+</pre>
+<p>
+        The first (standard) generator takes a <span class="emphasis"><em>single</em></span>
+        source of type <code class="computeroutput">VERBATIM</code> and produces a result. The second
+        (composing) generator takes any number of sources, which can have either
+        the <code class="computeroutput">CPP</code> or the <code class="computeroutput">LIB</code> type. Composing generators
+        are typically used for generating top-level target type. For example,
+        the first generator invoked when building an <code class="computeroutput">exe</code> target is
+        a composing generator corresponding to the proper linker.
+      </p>
+<p>You should also know about two specific functions for registering
+        generators: <code class="computeroutput">generators.register-c-compiler</code> and
+        <code class="computeroutput">generators.register-linker</code>. The first sets up header
+        dependecy scanning for C files, and the seconds handles various
+        complexities like searched libraries. For that reason, you should always
+        use those functions when adding support for compilers and linkers.
+      </p>
+<p>(Need a note about UNIX)</p>
+<h4>
+<a name="id3907794"></a>Custom generator classes</h4>
+<p>The standard generators allows you to specify source and target
+        types, an action, and a set of flags. If you need anything more complex,
+        
+        you need to create a new generator class with your own logic. Then,
+        you have to create an instance of that class and register it. Here's
+        an example how you can create your own generator class:
+</p>
+<pre class="programlisting">
+class custom-generator : generator
+{
+    rule __init__ ( * : * )
+    {
+        generator.__init__ $(1) : $(2) : $(3) : $(4) : $(5) : $(6) : $(7) : $(8) : $(9) ;
+    }
+
+}
+
+generators.register
+  [ new custom-generator verbatim.inline-file : VERBATIM : CPP ] ;
+</pre>
+<p>
+        This generator will work exactly like the
+        <code class="computeroutput">verbatim.inline-file</code> generator we've defined above, but
+        it's possible to customize the behaviour by overriding methods of the
+        <code class="computeroutput">generator</code> class.
+      </p>
+<p>There are two methods of interest. The <code class="computeroutput">run</code> method is
+        responsible for the overall process - it takes a number of source targets,
+        converts them to the right types, and creates the result. The
+        <code class="computeroutput">generated-targets</code> method is called when all sources are
+        converted to the right types to actually create the result.
+      </p>
+<p>The <code class="computeroutput">generated-targets</code> method can be overridden when you
+        want to add additional properties to the generated targets or use
+        additional sources. For a real-life example, suppose you have a program
+        analysis tool that should be given a name of executable and the list of
+        all sources. Naturally, you don't want to list all source files
+        manually. Here's how the <code class="computeroutput">generated-targets</code> method can find
+        the list of sources automatically:
+</p>
+<pre class="programlisting">
+class itrace-generator : generator {
+....
+    rule generated-targets ( sources + : property-set : project name ? )
+    {
+        local leaves ;
+        local temp = [ virtual-target.traverse $(sources[1]) : : include-sources ] ;
+        for local t in $(temp)
+        {
+            if ! [ $(t).action ]
+            {
+                leaves += $(t) ;
+            }
+        }
+        return [ generator.generated-targets $(sources) $(leafs)
+          : $(property-set) : $(project) $(name) ] ;
+    }
+}
+generators.register [ new itrace-generator nm.itrace : EXE : ITRACE ] ;
+</pre>
+<p>
+        The <code class="computeroutput">generated-targets</code> method will be called with a single
+        source target of type <code class="literal">EXE</code>. The call to
+        <code class="computeroutput">virtual-target.traverse</code> will return all targets the
+        executable depends on, and we further find files that are not
+        produced from anything. 
+        The found targets are added to the sources.
+      </p>
+<p>The <code class="computeroutput">run</code> method can be overriden to completely
+        customize the way the generator works. In particular, the conversion of
+        sources to the desired types can be completely customized. Here's
+        another real example. Tests for the Boost Python library usually
+        consist of two parts: a Python program and a C++ file. The C++ file is
+        compiled to Python extension that is loaded by the Python
+        program. But in the likely case that both files have the same name,
+        the created Python extension must be renamed. Otherwise, the Python
+        program will import itself, not the extension. Here's how it can be
+        done:
+</p>
+<pre class="programlisting">
+rule run ( project name ? : property-set : sources * )
+{
+    local python ;
+    for local s in $(sources)
+    {
+        if [ $(s).type ] = PY
+        {
+            python = $(s) ;
+        }
+    }
+    
+    local libs ;
+    for local s in $(sources)
+    {
+        if [ type.is-derived [ $(s).type ] LIB ]
+        {
+            libs += $(s) ;
+        }
+    }
+
+    local new-sources ;
+    for local s in $(sources)
+    {
+        if [ type.is-derived [ $(s).type ] CPP ]
+        {
+            local name = [ $(s).name ] ;    # get the target's basename
+            if $(name) = [ $(python).name ]
+            {
+                name = $(name)_ext ;        # rename the target
+            }
+            new-sources += [ generators.construct $(project) $(name) :
+              PYTHON_EXTENSION : $(property-set) : $(s) $(libs) ] ;
+        }
+    }
+
+    result = [ construct-result $(python) $(new-sources) : $(project) $(name)
+                 : $(property-set) ] ;
+}
+</pre>
+<p>
+        
+
+        First, we separate all source into python files, libraries and C++
+        sources. For each C++ source we create a separate Python extension by
+        calling <code class="computeroutput">generators.construct</code> and passing the C++ source
+        and the libraries. At this point, we also change the extension's name,
+        if necessary.
+      </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.extending.features"></a>Features</h3></div></div></div>
+<p>
+        Often, we need to control the options passed the invoked tools. This
+        is done with features. Consider an example:
+</p>
+<pre class="programlisting">
+# Declare a new free feature
+import feature : feature ;
+feature verbatim-options : : free ;
+
+# Cause the value of the 'verbatim-options' feature to be
+# available as 'OPTIONS' variable inside verbatim.inline-file
+import toolset : flags ;
+flags verbatim.inline-file OPTIONS &lt;verbatim-options&gt; ;
+
+# Use the "OPTIONS" variable
+actions inline-file
+{
+    "./inline-file.py" $(OPTIONS) $(&lt;) $(&gt;)
+}
+</pre>
+<p>
+        We first define a new feature. Then, the <code class="computeroutput">flags</code> invocation
+        says that whenever verbatin.inline-file action is run, the value of
+        the <code class="computeroutput">verbatim-options</code> feature will be added to the
+        <code class="computeroutput">OPTIONS</code> variable, and can be used inside the action body.
+        You'd need to consult online help (--help) to find all the features of
+        the <code class="computeroutput">toolset.flags</code> rule.
+        
+      </p>
+<p>
+      Although you can define any set of features and interpret their values
+      in any way, Boost.Build suggests the following coding standard for
+      designing features.
+    </p>
+<p>Most features should have a fixed set of values that is portable
+      (tool neutral) across the class of tools they are designed to work
+      with. The user does not have to adjust the values for a exact tool.  For
+      example, <code class="computeroutput">&lt;optimization&gt;speed</code> has the same meaning for
+      all C++ compilers and the user does not have to worry about the exact
+      options passed to the compiler's command line.
+    </p>
+<p>
+      Besides such portable features there are special 'raw' features that
+      allow the user to pass any value to the command line parameters for a
+      particular tool, if so desired. For example, the
+      <code class="computeroutput">&lt;cxxflags&gt;</code> feature allows you to pass any command line
+      options to a C++ compiler. The <code class="computeroutput">&lt;include&gt;</code> feature
+      allows you to pass any string preceded by <code class="computeroutput">-I</code> and the interpretation
+      is tool-specific.  (See <a class="xref" href="faq.html#bbv2.faq.external" title="Can I get capture external program output using a Boost.Jam variable?">the section called &#8220;
+      Can I get capture external program output using a Boost.Jam variable?
+    &#8221;</a> for an example of very smart usage of that
+      feature).  Of course one should always strive to use portable
+      features, but these are still be provided as a backdoor just to make
+      sure Boost.Build does not take away any control from the user.
+    </p>
+<p>
+      Using portable features is a good idea because:
+      </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>When a portable feature is given a fixed set of
+          values, you can build your project with two different
+          settings of the feature and Boost.Build will automatically
+          use two different directories for generated files.
+          Boost.Build does not try to separate targets built with
+          different raw options.
+            
+          </p></li>
+<li class="listitem"><p>Unlike with &#8220;raw&#8221; features, you don't need to use
+          specific command-line flags in your Jamfile, and it will be
+          more likely to work with other tools.
+          </p></li>
+</ul></div>
+<p>
+    </p>
+<h4>
+<a name="id3908076"></a>Steps for adding a feauture</h4>
+<p>Adding a feature requires three steps:
+
+        </p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem">
+<p>Declaring a feature. For that, the "feature.feature"
+              rule is used. You have to decide on the set of <a class="link" href="reference.html#bbv2.reference.features.attributes" title="Feature Attributes">feature
+              attributes</a>:
+
+              </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>if you want a feature value set for one target
+                to automaticaly propagate to its dependant targets then make it
+                &#8220;propagated&#8221;. </p></li>
+<li class="listitem"><p>if a feature does not have a fixed list of
+                values, it must be &#8220;free.&#8221;  For example, the <code class="computeroutput">include
+                </code> feature is a free feature.</p></li>
+<li class="listitem"><p>if a feature is used to refer to a path relative
+                to the Jamfile, it must be a &#8220;path&#8221; feature. Such features will
+                also get their values automatically converted to Boost Build's
+                internal path representation. For example, <code class="computeroutput">include</code>
+                is a path feature.</p></li>
+<li class="listitem"><p>if feature is used to refer to some target, it
+                must be a &#8220;dependency&#8221; feature. </p></li>
+</ul></div>
+<p>
+              </p>
+</li>
+<li class="listitem"><p>Representing the feature value in a
+          target-specific variable. Build actions are command
+          templates modified by Boost.Jam variable expansions.  The
+          <code class="computeroutput">toolset.flags</code> rule sets a target-specific
+          variable to the value of a feature.</p></li>
+<li class="listitem"><p>Using the variable. The variable set in step 2 can
+              be used in a build action to form command parameters or
+              files.</p></li>
+</ol></div>
+<p>
+      </p>
+<h4>
+<a name="id3908175"></a>Another example</h4>
+<p>Here's another example.
+        Let's see how we can make a feature that refers to a target. For example,
+        when linking dynamic libraries on Windows, one sometimes needs to
+        specify a "DEF file", telling what functions should be exported. It
+        would be nice to use this file like this:
+</p>
+<pre class="programlisting">
+        lib a : a.cpp : &lt;def-file&gt;a.def ;
+</pre>
+<p>
+
+        Actually, this feature is already supported, but anyway...
+        
+      </p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem">
+<p>Since the feature refers to a target, it must be "dependency".
+</p>
+<pre class="programlisting">
+feature def-file : : free dependency ;
+</pre>
+<p>
+            </p>
+</li>
+<li class="listitem">
+<p>One of the toolsets that cares about
+        
+        DEF files is msvc. The following line should be added to it.
+        
+
+</p>
+<pre class="programlisting">
+flags msvc.link DEF_FILE &lt;def-file&gt; ;
+</pre>
+<p>
+            
+            </p>
+</li>
+<li class="listitem">
+<p>Since the DEF_FILE variable is not used by the
+msvc.link action,
+
+we need to modify it to be:
+
+</p>
+<pre class="programlisting">
+actions link bind DEF_FILE
+{
+    $(.LD) .... /DEF:$(DEF_FILE) ....
+}
+</pre>
+<p>
+            </p>
+<p> Note the <code class="computeroutput">bind DEF_FILE</code> part. It tells
+          bjam to translate the internal target name in
+          <code class="varname">DEF_FILE</code> to a corresponding filename in
+          the <code class="computeroutput">link</code> action.  Without it the expansion of
+          <code class="computeroutput">$(DEF_FILE)</code> would be a strange symbol that is
+          not likely to make sense for the linker.
+          </p>
+<p>
+            We are almost done, but we should stop for a small workaround. Add the following
+            code to msvc.jam
+
+</p>
+<pre class="programlisting">
+rule link
+{
+    DEPENDS $(&lt;) : [ on $(&lt;) return $(DEF_FILE) ] ;
+}
+</pre>
+<p>
+
+
+            This is needed to accomodate some bug in bjam, which hopefully
+            will be fixed one day.
+            
+</p>
+</li>
+</ol></div>
+<h4>
+<a name="id3908286"></a>Variants and composite features.</h4>
+<p>Sometimes you want to create a shortcut for some set of
+        features. For example, <code class="computeroutput">release</code> is a value of
+        <code class="computeroutput">&lt;variant&gt;</code> and is a shortcut for a set of features.
+      </p>
+<p>It is possible to define your own build variants. For example:
+</p>
+<pre class="programlisting">
+variant crazy : &lt;optimization&gt;speed &lt;inlining&gt;off
+                &lt;debug-symbols&gt;on &lt;profiling&gt;on ;
+</pre>
+<p>
+        will define a new variant with the specified set of properties. You
+        can also extend an existing variant:
+</p>
+<pre class="programlisting">
+variant super_release : release : &lt;define&gt;USE_ASM ;
+</pre>
+<p>
+        In this case, <code class="computeroutput">super_release</code> will expand to all properties
+        specified by <code class="computeroutput">release</code>, and the additional one you've specified.
+      </p>
+<p>You are not restricted to using the <code class="computeroutput">variant</code> feature
+      only.
+      
+      Here's example that defines a brand new feature:
+</p>
+<pre class="programlisting">
+feature parallelism : mpi fake none : composite link-incompatible ;
+feature.compose &lt;parallelism&gt;mpi : &lt;library&gt;/mpi//mpi/&lt;parallelism&gt;none ;
+feature.compose &lt;parallelism&gt;fake : &lt;library&gt;/mpi//fake/&lt;parallelism&gt;none ;
+</pre>
+<p>
+
+        This will allow you to specify the value of feature
+        <code class="computeroutput">parallelism</code>, which will expand to link to the necessary
+        library.
+      </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.extending.rules"></a>Main target rules</h3></div></div></div>
+<p>
+      A main target rule (e.g &#8220;<code class="computeroutput">exe</code>&#8221;
+      Or &#8220;<code class="computeroutput">lib</code>&#8221;) creates a top-level target. It's quite likely that you'll want to declare your own and
+      there are two ways to do that.
+      
+    </p>
+<p><a name="bbv2.extending.rules.main-type"></a>The first way applies when
+
+      your target rule should just produce a target of specific type. In that case, a
+      rule is already defined for you! When you define a new type, Boost.Build
+      automatically defines a corresponding rule. The name of the rule is
+      obtained from the name of the type, by downcasing all letters and
+      replacing underscores with dashes.
+      
+      For example, if you create a module
+      <code class="filename">obfuscate.jam</code> containing:
+
+</p>
+<pre class="programlisting">
+import type ;
+type.register OBFUSCATED_CPP  : ocpp ;
+
+import generators ;
+generators.register-standard obfuscate.file : CPP : OBFUSCATED_CPP ;
+</pre>
+<p>
+      and import that module, you'll be able to use the rule "obfuscated-cpp"
+      in Jamfiles, which will convert source to the OBFUSCATED_CPP type.
+    </p>
+<p>
+      The second way is to write a wrapper rule that calls any of the existing
+      rules. For example, suppose you have only one library per directory and
+      want all cpp files in the directory to be compiled into that library. You
+      can achieve this effect using:
+</p>
+<pre class="programlisting">
+lib codegen : [ glob *.cpp ] ;
+</pre>
+<p>
+      If you want to make it even simpler, you could add the following
+      definition to the <code class="filename">Jamroot.jam</code> file:
+</p>
+<pre class="programlisting">
+rule glib ( name : extra-sources * : requirements * )
+{
+    lib $(name) : [ glob *.cpp ] $(extra-sources) : $(requirements) ;
+}
+</pre>
+<p>
+      allowing you to reduce the Jamfile to just
+</p>
+<pre class="programlisting">
+glib codegen ;
+</pre>
+<p>
+    </p>
+<p>
+      Note that because you can associate a custom generator with a target type,
+      the logic of building can be rather complicated. For example, the
+      <code class="computeroutput">boostbook</code> module declares a target type
+      <code class="computeroutput">BOOSTBOOK_MAIN</code> and a custom generator for that type. You can
+      use that as example if your main target rule is non-trivial.
+    </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.extending.toolset_modules"></a>Toolset modules</h3></div></div></div>
+<p>
+      If your extensions will be used only on one project, they can be placed in
+      a separate <code class="filename">.jam</code> file and imported by your
+      <code class="filename">Jamroot.jam</code>. If the extensions will be used on many
+      projects, users will thank you for a finishing touch.
+    </p>
+<p>The <code class="computeroutput">using</code> rule provides a standard mechanism
+    for loading and configuring extensions.  To make it work, your module
+    
+    should provide an <code class="computeroutput">init</code> rule. The rule will be called
+    with the same parameters that were passed to the
+    <code class="computeroutput">using</code> rule. The set of allowed parameters is
+    determined by you. For example, you can allow the user to specify
+    paths, tool versions, and other options.
+    
+    </p>
+<p>Here are some guidelines that help to make Boost.Build more
+      consistent:
+      </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>The <code class="computeroutput">init</code> rule should never fail. Even if
+          the user provided an incorrect path, you should emit a warning and go
+          on. Configuration may be shared between different machines, and
+          wrong values on one machine can be OK on another.
+          
+          </p></li>
+<li class="listitem">
+<p>Prefer specifying the command to be executed
+        to specifying the tool's installation path. First of all, this
+        gives more control: it's possible to specify
+</p>
+<pre class="programlisting">
+/usr/bin/g++-snapshot
+time g++
+
+</pre>
+<p>
+            as the command. Second, while some tools have a logical
+            "installation root", it's better if the user doesn't have to remember whether
+            a specific tool requires a full command or a path.
+            
+          </p>
+</li>
+<li class="listitem">
+<p>Check for multiple initialization. A user can try to
+            initialize the module several times. You need to check for this
+            and decide what to do. Typically, unless you support several
+            versions of a tool, duplicate initialization is a user error.
+            
+            If the
+            tool's version can be specified during initialization, make sure the
+            version is either always specified, or never specified (in which
+            case the tool is initialied only once). For example, if you allow:
+</p>
+<pre class="programlisting">
+using yfc ;
+using yfc : 3.3 ;
+using yfc : 3.4 ;
+</pre>
+<p>
+            Then it's not clear if the first initialization corresponds to
+            version 3.3 of the tool, version 3.4 of the tool, or some other
+            version. This can lead to building twice with the same version.
+            
+            </p>
+</li>
+<li class="listitem">
+<p>If possible, <code class="computeroutput">init</code> must be callable
+          with no parameters. In which case, it should try to autodetect all
+          the necessary information, for example, by looking for a tool in
+          <code class="envar">PATH</code> or in common installation locations. Often this
+          is possible and allows the user to simply write:
+</p>
+<pre class="programlisting">
+using yfc ;
+</pre>
+<p>
+          </p>
+</li>
+<li class="listitem"><p>Consider using facilities in the
+          <code class="computeroutput">tools/common</code> module. You can take a look at how
+          <code class="computeroutput">tools/gcc.jam</code> uses that module in the <code class="computeroutput">init</code> rule.
+          </p></li>
+</ul></div>
+<p>
+    </p>
+</div>
+<div class="footnotes">
+<br><hr width="100" align="left">
+<div class="footnote"><p><sup>[<a id="ftn.id3906715" href="#id3906715" class="para">13</a>] </sup>This name is historic, and will be eventuall changed to 
+        <code class="computeroutput">metatarget</code></p></div>
+<div class="footnote"><p><sup>[<a id="ftn.id3907057" href="#id3907057" class="para">14</a>] </sup>This create-then-register pattern is caused by limitations 
+        of the Boost.Jam language. Python port is likely to never create duplicate targets.</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 &#169; 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="reference.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="faq.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
diff --git a/doc/html/bbv2/faq.html b/doc/html/bbv2/faq.html
new file mode 100755
index 0000000000..36b118e56e
--- /dev/null
+++ b/doc/html/bbv2/faq.html
@@ -0,0 +1,531 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Frequently Asked Questions</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&#160;39.&#160;Boost.Build V2 User Manual">
+<link rel="prev" href="extender.html" title="Extender Manual">
+</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="extender.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>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="bbv2.faq"></a>Frequently Asked Questions</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="faq.html#id3908656">
+      How do I get the current value of feature in Jamfile?
+    </a></span></dt>
+<dt><span class="section"><a href="faq.html#id3908718">
+      I am getting a "Duplicate name of actual target" error. What does that
+      mean?
+    </a></span></dt>
+<dt><span class="section"><a href="faq.html#bbv2.faq.envar">
+      Accessing environment variables
+    </a></span></dt>
+<dt><span class="section"><a href="faq.html#id3908985">
+      How to control properties order?
+    </a></span></dt>
+<dt><span class="section"><a href="faq.html#id3909040">
+      How to control the library linking order on Unix?
+    </a></span></dt>
+<dt><span class="section"><a href="faq.html#bbv2.faq.external">
+      Can I get capture external program output using a Boost.Jam variable?
+    </a></span></dt>
+<dt><span class="section"><a href="faq.html#id3909184">
+      How to get the project root (a.k.a. Jamroot) location?
+    </a></span></dt>
+<dt><span class="section"><a href="faq.html#id3909210">
+      How to change compilation flags for one file?
+    </a></span></dt>
+<dt><span class="section"><a href="faq.html#bbv2.faq.dll-path">
+      Why are the <code class="literal">dll-path</code> and <code class="literal">hardcode-dll-paths
+      </code> properties useful?
+    </a></span></dt>
+<dt><span class="section"><a href="faq.html#bbv2.recipies.site-config">Targets in site-config.jam</a></span></dt>
+<dt><span class="section"><a href="faq.html#bbv2.faq.header-only-libraries">Header-only libraries</a></span></dt>
+</dl></div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3908656"></a>
+      How do I get the current value of feature in Jamfile?
+    </h3></div></div></div>
+<p>
+      This is not possible, since Jamfile does not have "current" value of any
+      feature, be it toolset, build variant or anything else. For a single
+      invocation of <code class="filename">bjam</code>, any given main target can be
+      built with several property sets. For example, user can request two build
+      variants on the command line. Or one library is built as shared when used
+      from one application, and as static when used from another. Each Jamfile
+      is read only once so generally there is no single value of a feature you
+      can access in Jamfile.
+    </p>
+<p>
+      A feature has a specific value only when building a target, and there are
+      two ways you can use that value:
+    </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+          Use conditional requirements or indirect conditional requirements. See
+          <a class="xref" href="overview.html#bbv2.overview.targets.requirements.conditional">the section called &#8220;Requirements&#8221;</a>.
+        </li>
+<li class="listitem">
+        Define a custom generator and a custom main target type. The custom
+        generator can do arbitrary processing or properties. See the <a class="xref" href="extender.html" title="Extender Manual">the section called &#8220;Extender Manual&#8221;</a>.
+      </li>
+</ul></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3908718"></a>
+      I am getting a "Duplicate name of actual target" error. What does that
+      mean?
+    </h3></div></div></div>
+<p>
+      The most likely case is that you are trying to compile the same file
+      twice, with almost the same, but differing properties. For example:
+</p>
+<pre class="programlisting">
+exe a : a.cpp : &lt;include&gt;/usr/local/include ;
+exe b : a.cpp ;
+</pre>
+<p>
+    </p>
+<p>
+      The above snippet requires two different compilations of
+      <code class="computeroutput">a.cpp</code>, which differ only in their <code class="literal">include</code>
+      property. Since the <code class="literal">include</code> feature is declared as
+      <code class="literal">free</code> Boost.Build does not create a separate build
+      directory for each of its values and those two builds would both produce
+      object files generated in the same build directory. Ignoring this and
+      compiling the file only once would be dangerous as different includes
+      could potentially cause completely different code to be compiled.
+    </p>
+<p>
+      To solve this issue, you need to decide if the file should be compiled
+      once or twice.
+    </p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem">
+<p>
+          To compile the file only once, make sure that properties are the same
+          for both target requests:
+</p>
+<pre class="programlisting">
+exe a : a.cpp : &lt;include&gt;/usr/local/include ;
+exe b : a.cpp : &lt;include&gt;/usr/local/include ;
+</pre>
+<p>
+          or:
+</p>
+<pre class="programlisting">
+alias a-with-include : a.cpp : &lt;include&gt;/usr/local/include ;
+exe a : a-with-include ;
+exe b : a-with-include ;
+</pre>
+<p>
+          or if you want the <code class="literal">includes</code> property not to affect
+          how any other sources added for the built <code class="computeroutput">a</code> and
+          <code class="computeroutput">b</code> executables would be compiled:
+</p>
+<pre class="programlisting">
+obj a-obj : a.cpp : &lt;include&gt;/usr/local/include ;
+exe a : a-obj ;
+exe b : a-obj ;
+</pre>
+<p>
+        </p>
+<p>
+          Note that in both of these cases the <code class="literal">include</code>
+          property will be applied only for building these object files and not
+          any other sources that might be added for targets <code class="computeroutput">a</code> and
+          <code class="computeroutput">b</code>.
+        </p>
+</li>
+<li class="listitem">
+<p>
+          To compile the file twice, you can tell Boost.Build to compile it to
+          two separate object files like so:
+</p>
+<pre class="programlisting">
+      obj a_obj : a.cpp : &lt;include&gt;/usr/local/include ;
+      obj b_obj : a.cpp ;
+      exe a : a_obj ;
+      exe b : b_obj ;
+</pre>
+<p>
+          or you can make the object file targets local to the main target:
+</p>
+<pre class="programlisting">
+      exe a : [ obj a_obj : a.cpp : &lt;include&gt;/usr/local/include ] ;
+      exe b : [ obj a_obj : a.cpp ] ;
+</pre>
+<p>
+          which will cause Boost.Build to actually change the generated object
+          file names a bit for you and thus avoid any conflicts.
+        </p>
+<p>
+          Note that in both of these cases the <code class="literal">include</code>
+          property will be applied only for building these object files and not
+          any other sources that might be added for targets <code class="computeroutput">a</code> and
+          <code class="computeroutput">b</code>.
+        </p>
+</li>
+</ol></div>
+<p>
+      A good question is why Boost.Build can not use some of the above
+      approaches automatically. The problem is that such magic would only help
+      in half of the cases, while in the other half it would be silently doing
+      the wrong thing. It is simpler and safer to ask the user to clarify his
+      intention in such cases.
+    </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.faq.envar"></a>
+      Accessing environment variables
+    </h3></div></div></div>
+<p>
+      Many users would like to use environment variables in Jamfiles, for
+      example, to control the location of external libraries. In many cases it
+      is better to declare those external libraries in the site-config.jam file,
+      as documented in the <a class="link" href="faq.html#bbv2.recipies.site-config" title="Targets in site-config.jam">recipes
+      section</a>. However, if the users already have the environment
+      variables set up, it may not be convenient for them to set up their
+      site-config.jam files as well and using the environment variables might be
+      reasonable.
+    </p>
+<p>
+      Boost.Jam automatically imports all environment variables into its
+      built-in .ENVIRON module so user can read them from there directly or by
+      using the helper os.environ rule. For example:
+</p>
+<pre class="programlisting">
+import os ;
+local unga-unga = [ os.environ UNGA_UNGA ] ;
+ECHO $(unga-unga) ;
+</pre>
+<p>
+      or a bit more realistic:
+</p>
+<pre class="programlisting">
+import os ;
+local SOME_LIBRARY_PATH = [ os.environ SOME_LIBRARY_PATH ] ;
+exe a : a.cpp : &lt;include&gt;$(SOME_LIBRARY_PATH) ;
+</pre>
+<p>
+    </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3908985"></a>
+      How to control properties order?
+    </h3></div></div></div>
+<p>
+      For internal reasons, Boost.Build sorts all the properties alphabetically.
+      This means that if you write:
+</p>
+<pre class="programlisting">
+exe a : a.cpp : &lt;include&gt;b &lt;include&gt;a ;
+</pre>
+<p>
+      then the command line with first mention the <code class="computeroutput">a</code> include
+      directory, and then <code class="computeroutput">b</code>, even though they are specified in the
+      opposite order. In most cases, the user does not care. But sometimes the
+      order of includes, or other properties, is important. For such cases, a
+      special syntax is provided:
+</p>
+<pre class="programlisting">
+exe a : a.cpp : &lt;include&gt;a&amp;&amp;b ;
+</pre>
+<p>
+    </p>
+<p>
+      The <code class="computeroutput">&amp;&amp;</code> symbols separate property values and specify
+      that their order should be preserved. You are advised to use this feature
+      only when the order of properties really matters and not as a convenient
+      shortcut. Using it everywhere might negatively affect performance.
+    </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3909040"></a>
+      How to control the library linking order on Unix?
+    </h3></div></div></div>
+<p>
+      On Unix-like operating systems, the order in which static libraries are
+      specified when invoking the linker is important, because by default, the
+      linker uses one pass though the libraries list. Passing the libraries in
+      the incorrect order will lead to a link error. Further, this behaviour is
+      often used to make one library override symbols from another. So,
+      sometimes it is necessary to force specific library linking order.
+    </p>
+<p>
+      Boost.Build tries to automatically compute the right order. The primary
+      rule is that if library <code class="computeroutput">a</code> "uses" library <code class="computeroutput">b</code>, then
+      library <code class="computeroutput">a</code> will appear on the command line before library
+      <code class="computeroutput">b</code>. Library <code class="computeroutput">a</code> is considered to use <code class="computeroutput">b</code>
+      if <code class="computeroutput">b</code> is present either in the <code class="computeroutput">a</code> library's
+      sources or its usage is listed in its requirements. To explicitly specify
+      the <code class="literal">use</code> relationship one can use the
+      <code class="literal">&lt;use&gt;</code> feature. For example, both of the following
+      lines will cause <code class="computeroutput">a</code> to appear before <code class="computeroutput">b</code> on the
+      command line:
+</p>
+<pre class="programlisting">
+lib a : a.cpp b ;
+lib a : a.cpp : &lt;use&gt;b ;
+</pre>
+<p>
+    </p>
+<p>
+      The same approach works for searched libraries as well:
+</p>
+<pre class="programlisting">
+lib z ;
+lib png : : &lt;use&gt;z ;
+exe viewer : viewer png z ;
+</pre>
+<p>
+    </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.faq.external"></a>
+      Can I get capture external program output using a Boost.Jam variable?
+    </h3></div></div></div>
+<p>
+      The <code class="literal">SHELL</code> builtin rule may be used for this purpose:
+</p>
+<pre class="programlisting">
+local gtk_includes = [ SHELL "gtk-config --cflags" ] ;
+</pre>
+<p>
+    </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3909184"></a>
+      How to get the project root (a.k.a. Jamroot) location?
+    </h3></div></div></div>
+<p>
+      You might want to use your project's root location in your Jamfiles. To
+      access it just declare a path constant in your Jamroot.jam file using:
+</p>
+<pre class="programlisting">
+path-constant TOP : . ;
+</pre>
+<p>
+      After that, the <code class="computeroutput">TOP</code> variable can be used in every Jamfile.
+    </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id3909210"></a>
+      How to change compilation flags for one file?
+    </h3></div></div></div>
+<p>
+      If one file must be compiled with special options, you need to explicitly
+      declare an <code class="computeroutput">obj</code> target for that file and then use that target
+      in your <code class="computeroutput">exe</code> or <code class="computeroutput">lib</code> target:
+</p>
+<pre class="programlisting">
+exe a : a.cpp b ;
+obj b : b.cpp : &lt;optimization&gt;off ;
+</pre>
+<p>
+      Of course you can use other properties, for example to specify specific
+      C/C++ compiler options:
+</p>
+<pre class="programlisting">
+exe a : a.cpp b ;
+obj b : b.cpp : &lt;cflags&gt;-g ;
+</pre>
+<p>
+      You can also use <a class="link" href="tutorial.html#bbv2.tutorial.conditions" title="Conditions and alternatives">conditional
+      properties</a> for finer control:
+</p>
+<pre class="programlisting">
+exe a : a.cpp b ;
+obj b : b.cpp : &lt;variant&gt;release:&lt;optimization&gt;off ;
+</pre>
+<p>
+    </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.faq.dll-path"></a>
+      Why are the <code class="literal">dll-path</code> and <code class="literal">hardcode-dll-paths
+      </code> properties useful?
+    </h3></div></div></div>
+<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>
+        This entry is specific to Unix systems.
+      </p></td></tr>
+</table></div>
+<p>
+      Before answering the questions, let us recall a few points about shared
+      libraries. Shared libraries can be used by several applications, or other
+      libraries, without physically including the library in the application
+      which can greatly decrease the total application size. It is also possible
+      to upgrade a shared library when the application is already installed.
+    </p>
+<p>
+      However, in order for application depending on shared libraries to be
+      started the OS may need to find the shared library when the application is
+      started. The dynamic linker will search in a system-defined list of paths,
+      load the library and resolve the symbols. Which means that you should
+      either change the system-defined list, given by the <code class="envar">LD_LIBRARY_PATH
+      </code> environment variable, or install the libraries to a system
+      location. This can be inconvenient when developing, since the libraries
+      are not yet ready to be installed, and cluttering system paths may be
+      undesirable. Luckily, on Unix there is another way.
+    </p>
+<p>
+      An executable can include a list of additional library paths, which will
+      be searched before system paths. This is excellent for development because
+      the build system knows the paths to all libraries and can include them in
+      the executables. That is done when the <code class="literal">hardcode-dll-paths
+      </code> feature has the <code class="literal">true</code> value, which is the
+      default. When the executables should be installed, the story is different.
+    </p>
+<p>
+      Obviously, installed executable should not contain hardcoded paths to your
+      development tree.  (The <code class="literal">install</code> rule explicitly disables the
+      <code class="literal">hardcode-dll-paths</code> feature for that reason.) However,
+      you can use the <code class="literal">dll-path</code> feature to add explicit paths
+      manually. For example:
+</p>
+<pre class="programlisting">
+install installed : application : &lt;dll-path&gt;/usr/lib/snake
+                                  &lt;location&gt;/usr/bin ;
+</pre>
+<p>
+      will allow the application to find libraries placed in the <code class="filename">
+      /usr/lib/snake</code> directory.
+    </p>
+<p>
+      If you install libraries to a nonstandard location and add an explicit
+      path, you get more control over libraries which will be used. A library of
+      the same name in a system location will not be inadvertently used. If you
+      install libraries to a system location and do not add any paths, the
+      system administrator will have more control. Each library can be
+      individually upgraded, and all applications will use the new library.
+    </p>
+<p>
+      Which approach is best depends on your situation. If the libraries are
+      relatively standalone and can be used by third party applications, they
+      should be installed in the system location. If you have lots of libraries
+      which can be used only by your application, it makes sense to install them
+      to a nonstandard directory and add an explicit path, like the example
+      above shows. Please also note that guidelines for different systems differ
+      in this respect. For example, the Debian GNU guidelines prohibit any
+      additional search paths while Solaris guidelines suggest that they should
+      always be used.
+    </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.recipies.site-config"></a>Targets in site-config.jam</h3></div></div></div>
+<p>
+      It is desirable to declare standard libraries available on a given system.
+      Putting target declaration in a specific project's Jamfile is not really
+      good, since locations of the libraries can vary between different
+      development machines and then such declarations would need to be
+      duplicated in different projects. The solution is to declare the targets
+      in Boost.Build's <code class="filename">site-config.jam</code> configuration file:
+</p>
+<pre class="programlisting">
+project site-config ;
+lib zlib : : &lt;name&gt;z ;
+</pre>
+<p>
+    </p>
+<p>
+      Recall that both <code class="filename">site-config.jam</code> and
+      <code class="filename">user-config.jam</code> are projects, and everything you can
+      do in a Jamfile you can do in those files as well. So, you declare a
+      project id and a target. Now, one can write:
+</p>
+<pre class="programlisting">
+exe hello : hello.cpp /site-config//zlib ;
+</pre>
+<p>
+      in any Jamfile.
+    </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.faq.header-only-libraries"></a>Header-only libraries</h3></div></div></div>
+<p>
+      In modern C++, libraries often consist of just header files, without any
+      source files to compile. To use such libraries, you need to add proper
+      includes and possibly defines to your project. But with a large number of
+      external libraries it becomes problematic to remember which libraries are
+      header only, and which ones you have to link to. However, with Boost.Build
+      a header-only library can be declared as Boost.Build target and all
+      dependents can use such library without having to remeber whether it is a
+      header-only library or not.
+    </p>
+<p>
+      Header-only libraries may be declared using the <code class="computeroutput">alias</code> rule,
+      specifying their include path as a part of its usage requirements, for
+      example:
+</p>
+<pre class="programlisting">
+alias my-lib
+    : # no sources
+    : # no build requirements
+    : # no default build
+    : &lt;include&gt;whatever ;
+</pre>
+<p>
+      The includes specified in usage requirements of <code class="computeroutput">my-lib</code> are
+      automatically added to all of its dependants' build properties. The
+      dependants need not care if <code class="computeroutput">my-lib</code> is a header-only or not,
+      and it is possible to later make <code class="computeroutput">my-lib</code> into a regular
+      compiled library without having to that its dependants' declarations.
+    </p>
+<p>
+      If you already have proper usage requirements declared for a project where
+      a header-only library is defined, you do not need to duplicate them for
+      the <code class="computeroutput">alias</code> target:
+</p>
+<pre class="programlisting">
+project my : usage-requirements &lt;include&gt;whatever ;
+alias mylib ;
+</pre>
+<p>
+    </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"><div class="copyright-footer">Copyright &#169; 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="extender.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>
+</div>
+</body>
+</html>
diff --git a/doc/html/bbv2/installation.html b/doc/html/bbv2/installation.html
new file mode 100644
index 0000000000..83e7f004c0
--- /dev/null
+++ b/doc/html/bbv2/installation.html
@@ -0,0 +1,79 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Installation</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&#160;39.&#160;Boost.Build V2 User Manual">
+<link rel="prev" href="../bbv2.html" title="Chapter&#160;39.&#160;Boost.Build V2 User Manual">
+<link rel="next" href="tutorial.html" title="Tutorial">
+</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="../bbv2.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="tutorial.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.installation"></a>Installation</h2></div></div></div>
+<p>
+      To install Boost.Build from an official release or a nightly build, as
+      available on the <a href="http://boost.org/boost-build2" target="_top">official web site</a>,
+      follow these steps:
+    </p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem">
+          Unpack the release. On the command line, go to the root of the
+          unpacked tree.
+        </li>
+<li class="listitem">
+          Run either <span class="command"><strong>.\bootstrap.bat</strong></span> (on Windows), or
+          <span class="command"><strong>./bootstrap.sh</strong></span> (on other operating systems).
+        </li>
+<li class="listitem">
+          Run 
+          <pre class="screen">./bjam install --prefix=<em class="replaceable"><code>PREFIX</code></em></pre>
+          where <em class="replaceable"><code>PREFIX</code></em> is a directory where you
+          want Boost.Build to be installed.
+        </li>
+<li class="listitem">
+          Optionally, add <code class="filename"><em class="replaceable"><code>PREFIX</code></em>/bin</code>
+          to your <code class="envar">PATH</code> environment variable.
+        </li>
+</ol></div>
+<p>If you are not using Boost.Build package, but rather the version
+    bundled with the Boost C++ Libraries, the above commands should be run
+    in the <code class="filename">tools/build/v2</code> directory.</p>
+<p>
+      Now that Boost.Build is installed, you can try some of examples. Copy
+      <code class="filename"><em class="replaceable"><code>PREFIX</code></em>/share/boost-build/examples/hello</code>
+      to a different directory, then change to that directory and run:
+</p>
+<pre class="screen"><code class="filename"><em class="replaceable"><code>PREFIX</code></em>/bin/bjam</code></pre>
+<p>
+      A simple executable should be built.
+    </p>
+</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 &#169; 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="../bbv2.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="tutorial.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
diff --git a/doc/html/bbv2/overview.html b/doc/html/bbv2/overview.html
new file mode 100755
index 0000000000..3bce75193a
--- /dev/null
+++ b/doc/html/bbv2/overview.html
@@ -0,0 +1,1474 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Overview</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&#160;39.&#160;Boost.Build V2 User Manual">
+<link rel="prev" href="tutorial.html" title="Tutorial">
+<link rel="next" href="tasks.html" title="Common tasks">
+</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="tutorial.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="tasks.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.overview"></a>Overview</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="overview.html#bbv2.overview.concepts">Concepts</a></span></dt>
+<dt><span class="section"><a href="overview.html#bbv2.overview.jam_language">Boost.Jam Language</a></span></dt>
+<dt><span class="section"><a href="overview.html#bbv2.overview.configuration">Configuration</a></span></dt>
+<dt><span class="section"><a href="overview.html#bbv2.overview.invocation">Invocation</a></span></dt>
+<dt><span class="section"><a href="overview.html#bbv2.overview.targets">Declaring Targets</a></span></dt>
+<dt><span class="section"><a href="overview.html#bbv2.overview.projects">Projects</a></span></dt>
+<dt><span class="section"><a href="overview.html#bbv2.overview.build_process">The Build Process</a></span></dt>
+</dl></div>
+<p>
+      This section will provide the information necessary to create your own
+      projects using Boost.Build. The information provided here is relatively
+      high-level, and <a class="xref" href="reference.html" title="Reference">the section called &#8220;Reference&#8221;</a> as well as the on-line
+      help system must be used to obtain low-level documentation (see <a class="xref" href="overview.html#bbv2.reference.init.options.help"><code class="option">--help</code></a>).
+    </p>
+<p>
+      Boost.Build actually consists of two parts - Boost.Jam, a build engine
+      with its own interpreted language, and Boost.Build itself, implemented in
+      Boost.Jam's language. The chain of events when you type
+      <span class="command"><strong>bjam</strong></span> on the command line is as follows:
+      </p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem"><p>
+            Boost.Jam tries to find Boost.Build and loads the top-level module.
+            The exact process is described in <a class="xref" href="reference.html#bbv2.reference.init" title="Initialization">the section called &#8220;Initialization&#8221;</a>
+          </p></li>
+<li class="listitem"><p>
+            The top-level module loads user-defined configuration files,
+            <code class="filename">user-config.jam</code> and <code class="filename">site-config.jam
+            </code>, which define available toolsets.
+          </p></li>
+<li class="listitem"><p>
+            The Jamfile in the current directory is read. That in turn might
+            cause reading of further Jamfiles. As a result, a tree of projects
+            is created, with targets inside projects.
+          </p></li>
+<li class="listitem"><p>
+            Finally, using the build request specified on the command line,
+            Boost.Build decides which targets should be built and how. That
+            information is passed back to Boost.Jam, which takes care of
+            actually running the scheduled build action commands.
+          </p></li>
+</ol></div>
+<p>
+    </p>
+<p>
+      So, to be able to successfully use Boost.Build, you need to know only four
+      things:
+      </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>
+            <a class="link" href="overview.html#bbv2.overview.configuration" title="Configuration">How to configure
+            Boost.Build</a>
+          </p></li>
+<li class="listitem"><p>
+            <a class="link" href="overview.html#bbv2.overview.targets" title="Declaring Targets">How to declare targets in
+              Jamfiles</a>
+          </p></li>
+<li class="listitem"><p>
+            <a class="link" href="overview.html#bbv2.overview.build_process" title="The Build Process">How the build process
+              works</a>
+          </p></li>
+<li class="listitem"><p>
+            Some Basics about the Boost.Jam language. See <a class="xref" href="overview.html#bbv2.overview.jam_language" title="Boost.Jam Language">the section called &#8220;Boost.Jam Language&#8221;</a>.
+          </p></li>
+</ul></div>
+<p>
+    </p>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.overview.concepts"></a>Concepts</h3></div></div></div>
+<p>Boost.Build has a few unique concepts that are introduced in this section. The best
+      way to explain the concepts is by comparison with more classical build tools.</p>
+<p>
+        When using any flavour of make, you directly specify <em class="firstterm">targets</em>
+        and commands that are used to create them from other target. The below example
+        creates <code class="filename">a.o</code> from <code class="filename">a.c</code> using a hardcoded
+        compiler invocation command.
+</p>
+<pre class="programlisting">
+a.o: a.c
+    g++ -o a.o -g a.c
+</pre>
+<p>
+        This is rather low-level description mechanism and it's hard to adjust commands, options,
+        and sets of created targets depending on the used compiler and operating system.        
+      </p>
+<p>
+        To improve portability, most modern build system provide a set of higher-level 
+        functions that can be used in build description files. Consider this example:
+</p>
+<pre class="programlisting">
+add_program ("a", "a.c")
+</pre>
+<p>
+        This is a function call that creates targets necessary to create executable file
+        from source file <code class="filename">a.c</code>. Depending on configured properties,
+        different commands line may be used. However, <code class="computeroutput">add_program</code> is higher-level,
+        but rather thin level. All targets are created immediately when build description
+        is parsed, which makes it impossible to perform multi-variant builds. Often, change
+        in any build property requires complete reconfiguration of the build tree.        
+      </p>
+<p>
+        In order to support true multivariant builds, Boost.Build introduces the concept of
+        <a class="indexterm" name="id3894430"></a>
+        <a class="indexterm" name="id3894441"></a>
+        <em class="firstterm">metatarget</em>&#8212;object that is created when build description
+        is parsed and can be later called with specific build properties to generate
+        actual targets. 
+      </p>
+<p>
+        Consider an example:
+</p>
+<pre class="programlisting">
+exe a : a.cpp ;
+</pre>
+<p>
+        When this declaration is parsed, Boost.Build creates a metatarget, but does not
+        yet decides what files must be created, or what commands must be used. After
+        all build files are parsed, Boost.Build considers properties requested on the
+        command line. Supposed you have invoked Boost.Build with:
+</p>
+<pre class="screen">
+bjam toolset=gcc toolset=msvc
+</pre>
+<p>
+        In that case, the metatarget will be called twice, once with <code class="computeroutput">toolset=gcc</code>
+        and once with <code class="computeroutput">toolset=msvc</code>. Both invocations will produce concrete
+        targets, that will have different extensions and use different command lines.
+      </p>
+<p>
+        Another key concept is 
+        <a class="indexterm" name="id3894500"></a>
+        <em class="firstterm">build property</em>. Build property is a variable
+        that affects the build process. It can be specified on the command line, and is
+        passed when calling a metatarget. While all build tools have a similar mechanism,
+        Boost.Build differs by requiring that all build properties are declared in advance,
+        and providing a large set of properties with portable semantics.
+      </p>
+<p>
+        The final concept is <a class="indexterm" name="id3894523"></a>
+        <em class="firstterm">property propagation</em>. Boost.Build does not require that every
+        metatarget is called with the same properties. Instead, the 
+        "top-level" metatargets are called with the properties specified on the command line.
+        Each metatarget can elect to augment or override some properties (in particular,
+        using the requirements mechanism, see <a class="xref" href="overview.html#bbv2.overview.targets.requirements" title="Requirements">the section called &#8220;Requirements&#8221;</a>).
+        Then, the dependency metatargets are called with modified properties and produce
+        concrete targets that are then used in build process. Of course, dependency metatargets
+        maybe in turn modify build properties and have dependencies of their own.
+      </p>
+<p>For more in-depth treatment of the requirements and concepts, you may refer 
+      to <a href="http://syrcose.ispras.ru/2009/files/04_paper.pdf" target="_top">SYRCoSE 2009 Boost.Build article</a>.
+      </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.overview.jam_language"></a>Boost.Jam Language</h3></div></div></div>
+<p>
+        This section will describe the basics of the Boost.Jam language&#8212;
+        just enough for writing Jamfiles. For more information, please see the
+        <a class="link" href="../">Boost.Jam</a> documentation.
+      </p>
+<p>
+        <a class="link" href="../">Boost.Jam</a> has an interpreted, procedural
+        language. On the lowest level, a <a class="link" href="../">Boost.Jam
+        </a> program consists of variables and <a class="indexterm" name="id3894614"></a> <em class="firstterm">rules</em> (Jam term for
+        function). They are grouped into modules&#8212;there is one global
+        module and a number of named modules. Besides that, a <a class="link" href="../">Boost.Jam</a> program contains classes and class
+        instances.
+      </p>
+<p>
+        Syntantically, a <a class="link" href="../">Boost.Jam</a> program
+        consists of two kind of elements&#8212;keywords (which have a special
+        meaning to <a class="link" href="../">Boost.Jam</a>) and literals.
+        Consider this code:
+</p>
+<pre class="programlisting">
+a = b ;
+</pre>
+<p>
+        which assigns the value <code class="literal">b</code> to the variable <code class="literal">a
+        </code>. Here, <code class="literal">=</code> and <code class="literal">;</code> are
+        keywords, while <code class="literal">a</code> and <code class="literal">b</code> are
+        literals.
+        </p>
+<div class="warning"><table border="0" summary="Warning">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td>
+<th align="left">Warning</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+            All syntax elements, even keywords, must be separated by spaces. For
+            example, omitting the space character before <code class="literal">;</code>
+            will lead to a syntax error.
+          </p></td></tr>
+</table></div>
+<p>
+        If you want to use a literal value that is the same as some keyword, the
+        value can be quoted:
+</p>
+<pre class="programlisting">
+a = "=" ;
+</pre>
+<p>
+      </p>
+<p>
+        All variables in <a class="link" href="../">Boost.Jam</a> have the same
+        type&#8212;list of strings. To define a variable one assigns a value to
+        it, like in the previous example. An undefined variable is the same as a
+        variable with an empty value. Variables can be accessed using the
+        <code class="computeroutput">$(<em class="replaceable"><code>variable</code></em>)</code> syntax. For example:
+</p>
+<pre class="programlisting">
+a = $(b) $(c) ;
+</pre>
+<p>
+      </p>
+<p>
+        Rules are defined by specifying the rule name, the parameter names, and
+        the allowed value list size for each parameter.
+</p>
+<pre class="programlisting">
+rule <em class="replaceable"><code>example</code></em>
+ (
+     <em class="replaceable"><code>parameter1</code></em> :
+     <em class="replaceable"><code>parameter2 ?</code></em> :
+     <em class="replaceable"><code>parameter3 +</code></em> :
+     <em class="replaceable"><code>parameter4 *</code></em>
+ )
+ {
+    # rule body
+ }
+ </pre>
+<p>
+        When this rule is called, the list passed as the first argument must
+        have exactly one value. The list passed as the second argument can
+        either have one value of be empty. The two remaining arguments can be
+        arbitrarily long, but the third argument may not be empty.
+      </p>
+<p>
+        The overview of <a class="link" href="../">Boost.Jam</a> language
+        statements is given below:
+</p>
+<pre class="programlisting">
+helper 1 : 2 : 3 ;
+x = [ helper 1 : 2 : 3 ] ;
+</pre>
+<p>
+        This code calls the named rule with the specified arguments. When the
+        result of the call must be used inside some expression, you need to add
+        brackets around the call, like shown on the second line.
+</p>
+<pre class="programlisting">
+if cond { statements } [ else { statements } ]
+</pre>
+<p>
+        This is a regular if-statement. The condition is composed of:
+        </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>
+              Literals (true if at least one string is not empty)
+            </p></li>
+<li class="listitem"><p>
+              Comparisons: <code class="computeroutput">a <em class="replaceable"><code>operator</code></em> b</code>
+              where <em class="replaceable"><code>operator</code></em> is one of
+              <code class="computeroutput">=</code>, <code class="computeroutput">!=</code>, <code class="computeroutput">&lt;</code>,
+              <code class="computeroutput">&gt;</code>, <code class="computeroutput">&lt;=</code> or <code class="computeroutput">&gt;=</code>. The
+              comparison is done pairwise between each string in the left and
+              the right arguments.
+            </p></li>
+<li class="listitem"><p>
+              Logical operations: <code class="computeroutput">! a</code>, <code class="computeroutput">a &amp;&amp; b</code>,
+              <code class="computeroutput">a || b</code>
+            </p></li>
+<li class="listitem"><p>
+              Grouping: <code class="computeroutput">( cond )</code>
+            </p></li>
+</ul></div>
+<p>
+</p>
+<pre class="programlisting">
+for var in list { statements }
+</pre>
+<p>
+        Executes statements for each element in list, setting the variable
+        <code class="varname">var</code> to the element value.
+</p>
+<pre class="programlisting">
+while cond { statements }
+</pre>
+<p>
+        Repeatedly execute statements while cond remains true upon entry.
+</p>
+<pre class="programlisting">
+return values ;
+</pre>
+<p>
+        This statement should be used only inside a rule and assigns
+        <code class="computeroutput">values</code> to the return value of the rule.
+        </p>
+<div class="warning"><table border="0" summary="Warning">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td>
+<th align="left">Warning</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+            The <code class="computeroutput">return</code> statement does not exit the rule. For
+            example:
+</p>
+<pre class="programlisting">
+rule test ( )
+{
+   if 1 = 1
+   {
+      return "reasonable" ;
+   }
+   return "strange" ;
+}
+</pre>
+<p>
+            will return <code class="literal">strange</code>, not
+            <code class="literal">reasonable</code>.
+          </p>
+</td></tr>
+</table></div>
+<p>
+</p>
+<pre class="programlisting">
+import <em class="replaceable"><code>module</code></em> ;
+import <em class="replaceable"><code>module</code></em> : <em class="replaceable"><code>rule</code></em> ;
+</pre>
+<p>
+        The first form imports the specified bjam module. All rules from that
+        module are made available using the qualified name: <code class="computeroutput"><em class="replaceable"><code>
+        module</code></em>.<em class="replaceable"><code>rule</code></em></code>. The second
+        form imports the specified rules only, and they can be called using
+        unqualified names.
+      </p>
+<p><a name="bbv2.overview.jam_language.actions"></a>
+        Sometimes, you'd need to specify the actual command lines to be used
+        when creating targets. In jam language, you use named actions to do
+        this. For example:
+</p>
+<pre class="programlisting">
+actions create-file-from-another
+{
+    create-file-from-another $(&lt;) $(&gt;)
+}
+</pre>
+<p>
+        This specifies a named action called <code class="literal">
+        create-file-from-another</code>. The text inside braces is the
+        command to invoke. The <code class="literal">$(&lt;)</code> variable will be
+        expanded to a list of generated files, and the <code class="literal">$(&gt;)
+        </code> variable will be expanded to a list of source files.
+      </p>
+<p>
+        To flexibly adjust the command line, you can define a rule with the same
+        name as the action and taking three parameters -- targets, sources and
+        properties. For example:
+</p>
+<pre class="programlisting">
+rule create-file-from-another ( targets * : sources * : properties * )
+{
+   if &lt;variant&gt;debug in $(properties)
+   {
+       OPTIONS on $(targets) = --debug ;
+   }
+}
+actions create-file-from-another
+{
+    create-file-from-another $(OPTIONS) $(&lt;) $(&gt;)
+}
+</pre>
+<p>
+        In this example, the rule checks if certain build property is specified.
+        If so, it sets variable <code class="varname">OPIONS</code> that is then used
+        inside the action. Note that the variables set "on a target" will be
+        visible only inside actions building that target, not globally. Were
+        they set globally, using variable named <code class="varname">OPTIONS</code> in
+        two unrelated actions would be impossible.
+      </p>
+<p>
+        More details can be found in Jam reference, <a class="xref" href="../jam/language.html#jam.language.rules" title="Rules">the section called &#8220;Rules&#8221;</a>.
+      </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.overview.configuration"></a>Configuration</h3></div></div></div>
+<p>
+      On startup, Boost.Build searches and reads two configuration files: 
+      <code class="filename">site-config.jam</code> and <code class="filename">user-config.jam</code>.
+      The first one is usually installed and maintained by system administrator, and
+      the second is for user to modify.  You can edit the one in the top-level
+      directory of Boost.Build installation or create a copy in your home
+      directory and edit the copy.  The following table explains where both files
+      are searched.
+    </p>
+<div class="table">
+<a name="bbv2.reference.init.config"></a><p class="title"><b>Table&#160;39.1.&#160;Search paths for configuration files</b></p>
+<div class="table-contents"><table class="table" summary="Search paths for configuration files">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>&#160;</th>
+<th>site-config.jam</th>
+<th>user-config.jam</th>
+</tr></thead>
+<tbody>
+<tr>
+<td>Linux</td>
+<td>
+              <p><code class="computeroutput">/etc</code></p>
+              <p><code class="computeroutput">$HOME</code></p>
+              <p><code class="computeroutput">$BOOST_BUILD_PATH</code></p>
+            </td>
+<td>
+              <p><code class="computeroutput">$HOME</code></p>
+              <p><code class="computeroutput">$BOOST_BUILD_PATH</code></p>
+            </td>
+</tr>
+<tr>
+<td>Windows</td>
+<td>
+              <p><code class="computeroutput">%SystemRoot%</code></p>
+              <p><code class="computeroutput">%HOMEDRIVE%%HOMEPATH%</code></p>
+              <p><code class="computeroutput">%HOME%</code></p>
+              <p><code class="computeroutput">%BOOST_BUILD_PATH%</code></p>
+            </td>
+<td>
+              <p><code class="computeroutput">%HOMEDRIVE%%HOMEPATH%</code></p>
+              <p><code class="computeroutput">%HOME%</code></p>
+              <p><code class="computeroutput">%BOOST_BUILD_PATH%</code></p>
+            </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><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>
+        You can use the <span class="command"><strong>--debug-configuration</strong></span> option to
+        find which configuration files are actually loaded.
+      </p></td></tr>
+</table></div>
+<p>
+      Usually, <code class="filename">user-config.jam</code> just defines available compilers
+      and other tools (see <a class="xref" href="faq.html#bbv2.recipies.site-config" title="Targets in site-config.jam">the section called &#8220;Targets in site-config.jam&#8221;</a> for more advanced
+      usage). A tool is configured using the following syntax:
+    </p>
+<pre class="programlisting">
+using <em class="replaceable"><code>tool-name</code></em> : ... ;
+</pre>
+<p>
+      The <code class="computeroutput">using</code> rule is given a name of tool, and
+      will make that tool available to Boost.Build. For example,
+</p>
+<pre class="programlisting">
+using gcc ;
+</pre>
+<p> will make the <a href="http://gcc.gnu.org" target="_top">GCC</a> compiler available.
+    </p>
+<p>
+      All the supported tools are documented in <a class="xref" href="reference.html#bbv2.reference.tools" title="Builtin tools">the section called &#8220;Builtin tools&#8221;</a>,
+      including the specific options they take. Some general notes that apply to most
+      C++ compilers are below.
+    </p>
+<p>
+      For all the C++ compiler toolsets Boost.Build supports
+      out-of-the-box, the list of parameters to
+      <code class="computeroutput">using</code> is the same: <em class="parameter"><code>toolset-name</code></em>, <em class="parameter"><code>version</code></em>, <em class="parameter"><code>invocation-command</code></em>, and <em class="parameter"><code>options</code></em>.
+    </p>
+<p>If you have a single compiler, and the compiler executable
+      </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>has its &#8220;usual name&#8221; and is in the
+      <code class="envar">PATH</code>, or</p></li>
+<li class="listitem"><p>was installed in a standard &#8220;installation
+      directory&#8221;, or</p></li>
+<li class="listitem"><p>can be found using a global system like the Windows
+      registry.</p></li>
+</ul></div>
+<p>
+    it can be configured by simply:</p>
+<pre class="programlisting">
+using <em class="replaceable"><code>tool-name</code></em> ;
+</pre>
+<p>If the compiler is installed in a custom directory, you should provide the
+    command that invokes the compiler, for example:</p>
+<pre class="programlisting">
+using gcc : : g++-3.2 ;
+using msvc : : "Z:/Programs/Microsoft Visual Studio/vc98/bin/cl" ;
+</pre>
+<p>
+      Some Boost.Build toolsets will use that path to take additional actions
+      required before invoking the compiler, such as calling vendor-supplied
+      scripts to set up its required environment variables. When compiler
+      executables for C and C++ are different, path to the C++ compiler
+      executable must be specified. The command can
+      be any command allowed by the operating system. For example:
+</p>
+<pre class="programlisting">
+using msvc : : echo Compiling &amp;&amp; foo/bar/baz/cl ;
+</pre>
+<p>
+      will work.
+    </p>
+<p>
+      To configure several versions of a toolset, simply invoke the
+      <code class="computeroutput">using</code> rule multiple times:
+</p>
+<pre class="programlisting">
+using gcc : 3.3 ;
+using gcc : 3.4 : g++-3.4 ;
+using gcc : 3.2 : g++-3.2 ;
+</pre>
+<p>
+      Note that in the first call to <code class="computeroutput">using</code>, the
+      compiler found in the <code class="envar">PATH</code> will be used, and there is no
+      need to explicitly specify the command.
+    </p>
+<p>
+      Many of toolsets have an <em class="parameter"><code>options</code></em>
+      parameter to fine-tune the configuration. All of
+      Boost.Build's standard compiler toolsets accept four options
+      <code class="varname">cflags</code>, <code class="varname">cxxflags</code>, 
+      <code class="varname">compileflags</code> and <code class="varname">linkflags</code> as <em class="parameter"><code>options</code></em> specifying flags that will be
+      always passed to the corresponding tools. Values of the
+      <code class="varname">cflags</code> feature are passed directly to the C
+      compiler, values of the <code class="varname">cxxflags</code> feature are
+      passed directly to the C++ compiler, and values of the
+      <code class="varname">compileflags</code> feature are passed to both. For
+      example, to configure a <span class="command"><strong>gcc</strong></span> toolset so that it
+      always generates 64-bit code you could write:
+</p>
+<pre class="programlisting">
+        using gcc : 3.4 : : &lt;compileflags&gt;-m64 &lt;linkflags&gt;-m64 ;
+</pre>
+<p>
+    </p>
+<div class="warning"><table border="0" summary="Warning">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td>
+<th align="left">Warning</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+        Although the syntax used to specify toolset options is very similar
+        to syntax used to specify requirements in Jamfiles, the toolset options
+        are not the same as features. Don't try to specify a feature value
+        in toolset initialization.
+      </p></td></tr>
+</table></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.overview.invocation"></a>Invocation</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="overview.html#bbv2.overview.invocation.examples">Examples</a></span></dt>
+<dt><span class="section"><a href="overview.html#bbv2.overview.invocation.options">Options</a></span></dt>
+<dt><span class="section"><a href="overview.html#bbv2.overview.invocation.properties">Properties</a></span></dt>
+<dt><span class="section"><a href="overview.html#bbv2.overview.invocation.targets">Targets</a></span></dt>
+</dl></div>
+<p>To invoke Boost.Build, type <span class="command"><strong>bjam</strong></span> on the command line. Three kinds
+      of command-line tokens are accepted, in any order:</p>
+<div class="variablelist"><dl>
+<dt><span class="term">options</span></dt>
+<dd><p>Options start with either dash, or two dashes.  The standard options
+          are listed below, and each project may add additional options</p></dd>
+<dt><span class="term">properties</span></dt>
+<dd><p>Properties specify details of what you want to build (e.g. debug
+          or release variant).  Syntactically, all command line tokens with equal sign in them
+          are considered to specify properties.  In the simplest form, property looks like
+          <span class="command"><strong><em class="replaceable"><code>feature</code></em>=<em class="replaceable"><code>value</code></em></strong></span>
+          </p></dd>
+<dt><span class="term">target</span></dt>
+<dd><p>All tokens that are neither options nor properties specify 
+          what targets to build.  The available targets entirely depend on the project
+          you are building.</p></dd>
+</dl></div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.overview.invocation.examples"></a>Examples</h4></div></div></div>
+<p>To build all targets defined in Jamfile in the current directory with default properties, run:
+</p>
+<pre class="screen">
+bjam
+</pre>
+<p>
+        </p>
+<p>To build specific targets, specify them on the command line:
+</p>
+<pre class="screen">
+bjam lib1 subproject//lib2
+</pre>
+<p>
+        </p>
+<p>To request a certain value for some property, add <code class="literal">
+        <em class="replaceable"><code>property</code></em>=<em class="replaceable"><code>value</code></em></code> to the command line:
+</p>
+<pre class="screen">
+bjam toolset=gcc variant=debug optimization=space
+</pre>
+<p>
+        </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.overview.invocation.options"></a>Options</h4></div></div></div>
+<p>Boost.Build recognizes the following command line options.</p>
+<div class="variablelist"><dl>
+<dt>
+<a name="bbv2.reference.init.options.help"></a><span class="term"><code class="option">--help</code></span>
+</dt>
+<dd><p>Invokes the online help system. This prints general
+              information on how to use the help system with additional
+              --help* options.
+              </p></dd>
+<dt><span class="term"><code class="option">--clean</code></span></dt>
+<dd><p>Cleans all targets in the current directory and
+              in any subprojects. Note that unlike the <code class="literal">clean</code>
+              target in make, you can use <code class="literal">--clean</code>
+              together with target names to clean specific targets.</p></dd>
+<dt><span class="term"><code class="option">--clean-all</code></span></dt>
+<dd><p>Cleans all targets,
+              no matter where they are defined. In particular, it will clean targets
+              in parent Jamfiles, and targets defined under other project roots.
+              </p></dd>
+<dt><span class="term"><code class="option">--build-dir</code></span></dt>
+<dd>
+<p>Changes build directories for all project roots being built. When
+              this option is specified, all Jamroot files should declare project name.
+              The build directory for the project root will be computed by concatanating
+              the value of the <code class="option">--build-dir</code> option, the project name
+              specified in Jamroot, and the build dir specified in Jamroot
+              (or <code class="literal">bin</code>, if none is specified).
+              </p>
+<p>The option is primarily useful when building from read-only
+              media, when you can't modify Jamroot.
+              </p>
+</dd>
+<dt><span class="term"><code class="option">--version</code></span></dt>
+<dd><p>Prints information on Boost.Build and Boost.Jam
+              versions.
+              </p></dd>
+<dt><span class="term"><code class="option">-a</code></span></dt>
+<dd><p>Causes all files to be rebuilt.</p></dd>
+<dt><span class="term"><code class="option">-n</code></span></dt>
+<dd><p>Do no execute the commands, only print them.</p></dd>
+<dt><span class="term"><code class="option">-q</code></span></dt>
+<dd><p>Stop at first error, as opposed to continuing to build targets
+              that don't depend on the failed ones.</p></dd>
+<dt><span class="term"><code class="option">-j <em class="replaceable"><code>N</code></em></code></span></dt>
+<dd><p>Run up to <em class="replaceable"><code>N</code></em> commands in parallel.</p></dd>
+<dt><span class="term"><code class="option">--debug-configuration</code></span></dt>
+<dd><p>Produces debug information about loading of Boost.Build
+              and toolset files.</p></dd>
+<dt><span class="term"><code class="option">--debug-building</code></span></dt>
+<dd><p>Prints what targets are being built and with what properties.
+              </p></dd>
+<dt><span class="term"><code class="option">--debug-generators</code></span></dt>
+<dd><p>Produces debug output from generator search process.
+              Useful for debugging custom generators.
+              </p></dd>
+<dt><span class="term"><code class="option">--ignore-config</code></span></dt>
+<dd><p>Do not load <code class="literal">site-config.jam</code> and
+              <code class="literal">user-config.jam</code> configuration files.
+              </p></dd>
+<dt><span class="term"><code class="option">-d0</code></span></dt>
+<dd><p>Supress all informational messages.</p></dd>
+<dt><span class="term"><code class="option">-d <em class="replaceable"><code>N</code></em></code></span></dt>
+<dd>
+<p>Enable cummulative debugging levels from 1 to n. Values are: 
+              </p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem">Show the actions taken for building targets, as they are executed (the default).</li>
+<li class="listitem">Show "quiet" actions and display all action text, as they are executed.</li>
+<li class="listitem">Show dependency analysis, and target/source timestamps/paths.</li>
+<li class="listitem">Show arguments and timming of shell invocations.</li>
+<li class="listitem">Show rule invocations and variable expansions.</li>
+<li class="listitem">Show directory/header file/archive scans, and attempts at binding to targets.</li>
+<li class="listitem">Show variable settings.</li>
+<li class="listitem">Show variable fetches, variable expansions, and evaluation of '"if"' expressions.</li>
+<li class="listitem">Show variable manipulation, scanner tokens, and memory usage.</li>
+<li class="listitem">Show profile information for rules, both timing and memory.</li>
+<li class="listitem">Show parsing progress of Jamfiles.</li>
+<li class="listitem">Show graph of target dependencies.</li>
+<li class="listitem">Show change target status (fate).</li>
+</ol></div>
+<p>
+              </p>
+</dd>
+<dt><span class="term"><code class="option">-d +<em class="replaceable"><code>N</code></em></code></span></dt>
+<dd><p>Enable debugging level <em class="replaceable"><code>N</code></em>.</p></dd>
+<dt><span class="term"><code class="option">-o <em class="replaceable"><code>file</code></em></code></span></dt>
+<dd><p>Write the updating actions to the specified file instead of running them.
+              </p></dd>
+<dt><span class="term"><code class="option">-s <em class="replaceable"><code>var</code></em>=<em class="replaceable"><code>value</code></em></code></span></dt>
+<dd><p>Set the variable <em class="replaceable"><code>var</code></em> to
+              <em class="replaceable"><code>value</code></em> in the global scope of the jam
+              language interpreter, overriding variables imported from the
+              environment.
+              </p></dd>
+</dl></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.overview.invocation.properties"></a>Properties</h4></div></div></div>
+<p>In the simplest case, the build is performed with a single set of properties,
+        that you specify on the command line with elements in the form
+        <span class="command"><strong><em class="replaceable"><code>feature</code></em>=<em class="replaceable"><code>value</code></em></strong></span>.
+        The complete list of features can be found in <a class="xref" href="reference.html#bbv2.overview.builtins.features" title="Builtin features">the section called &#8220;Builtin features&#8221;</a>. 
+        The most common features are summarized below.</p>
+<div class="table">
+<a name="id3896181"></a><p class="title"><b>Table&#160;39.2.&#160;</b></p>
+<div class="table-contents"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>Feature</th>
+<th>Allowed values</th>
+<th>Notes</th>
+</tr></thead>
+<tbody>
+<tr>
+<td>variant</td>
+<td>debug,release</td>
+<td>&#160;</td>
+</tr>
+<tr>
+<td>link</td>
+<td>shared,static</td>
+<td>Determines if Boost.Build creates shared or static libraries</td>
+</tr>
+<tr>
+<td>threading</td>
+<td>single,multi</td>
+<td>Cause the produced binaries to be thread-safe.  This requires proper support in the source code itself.</td>
+</tr>
+<tr>
+<td>address-model</td>
+<td>32,64</td>
+<td>Explicitly request either 32-bit or 64-bit code generation. This typically
+                requires that your compiler is appropriately configured. Please refer to
+                <a class="xref" href="reference.html#bbv2.reference.tools.compilers" title="C++ Compilers">the section called &#8220;C++ Compilers&#8221;</a> and your compiler documentation
+                in case of problems.</td>
+</tr>
+<tr>
+<td>toolset</td>
+<td>(Depends on configuration)</td>
+<td>The C++ compiler to use. See <a class="xref" href="reference.html#bbv2.reference.tools.compilers" title="C++ Compilers">the section called &#8220;C++ Compilers&#8221;</a> for a detailed list.</td>
+</tr>
+<tr>
+<td>include</td>
+<td>(Arbitrary string)</td>
+<td>Additional include paths for C and C++ compilers.</td>
+</tr>
+<tr>
+<td>define</td>
+<td>(Arbitrary string)</td>
+<td>Additional macro definitions for C and C++ compilers. The string should be either
+                <code class="computeroutput">SYMBOL</code> or <code class="computeroutput">SYMBOL=VALUE</code>
+</td>
+</tr>
+<tr>
+<td>cxxflags</td>
+<td>(Arbitrary string)</td>
+<td>Custom options to pass to the C++ compiler.</td>
+</tr>
+<tr>
+<td>cflags</td>
+<td>(Arbitrary string)</td>
+<td>Custom options to pass to the C compiler.</td>
+</tr>
+<tr>
+<td>linkflags</td>
+<td>(Arbitrary string)</td>
+<td>Custom options to pass to the C++ linker.</td>
+</tr>
+<tr>
+<td>runtime-link</td>
+<td>shared,static</td>
+<td>Determines if shared or static version of C and C++ runtimes should be used.</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break">
+
+        If you have more than one version of a given C++ toolset (e.g. configured in
+        <code class="filename">user-config.jam</code>, or autodetected, as happens with msvc), you can
+        request the specific version by passing 
+        <code class="computeroutput"><em class="replaceable"><code>toolset</code></em>-<em class="replaceable"><code>version</code></em></code> as
+        the value of the <code class="computeroutput">toolset</code> feature, for example <code class="computeroutput">toolset=msvc-8.0</code>.
+
+
+        <p>
+          If a feature has a fixed set of values it can be specified more than 
+          once on the command line. 
+          In which case, everything will be built several times --
+          once for each specified value of a feature.  For example, if you use
+        </p>
+<pre class="screen">
+bjam link=static link=shared threading=single threading=multi
+</pre>
+<p>
+          Then a total of 4 builds will be performed.  For convenience, 
+          instead of specifying all requested values of a feature in separate command line elements,
+          you can separate the values with commands, for example:
+        </p>
+<pre class="screen">
+bjam link=static,shared threading=single,multi
+</pre>
+<p>
+          The comma has special meaning only if the feature has a fixed set of values, so
+        </p>
+<pre class="screen">
+bjam include=static,shared
+</pre>
+<p>is not treated specially.</p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.overview.invocation.targets"></a>Targets</h4></div></div></div>
+<p>All command line elements that are neither options nor properties are the names of the
+        targets to build. See <a class="xref" href="reference.html#bbv2.reference.ids" title="Target identifiers and references">the section called &#8220;Target identifiers and references&#8221;</a>. If no target is specified,
+        the project in the current directory is built.</p>
+</div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.overview.targets"></a>Declaring Targets</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="overview.html#id3896594">Name</a></span></dt>
+<dt><span class="section"><a href="overview.html#id3896750">Sources</a></span></dt>
+<dt><span class="section"><a href="overview.html#bbv2.overview.targets.requirements">Requirements</a></span></dt>
+<dt><span class="section"><a href="overview.html#id3897336">Default Build</a></span></dt>
+<dt><span class="section"><a href="overview.html#id3897364">Additional Information</a></span></dt>
+</dl></div>
+<p><a name="bbv2.overview.targets.main"></a>
+        A <em class="firstterm">Main target</em> is a user-defined named
+        entity that can be built, for example an executable file.
+        Declaring a main target is usually done using one of the main
+        target rules described in <a class="xref" href="reference.html#bbv2.reference.rules" title="Builtin rules">the section called &#8220;Builtin rules&#8221;</a>.  The user can also declare
+        custom main target rules as shown in <a class="xref" href="extender.html#bbv2.extending.rules" title="Main target rules">the section called &#8220;Main target rules&#8221;</a>.
+      </p>
+<a class="indexterm" name="id3896541"></a><p>Most main target rules in Boost.Build have the same common
+      signature:</p>
+<a class="indexterm" name="id3896555"></a><a name="bbv2.main-target-rule-syntax"></a><pre class="programlisting">
+rule <em class="replaceable"><code>rule-name</code></em> (
+     main-target-name :
+     sources + :
+     requirements * :
+     default-build * :
+     usage-requirements * )
+</pre>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+            <em class="parameter"><code>main-target-name</code></em> is the name used
+            to request the target on command line and to use it from
+            other main targets. A main target name may contain
+            alphanumeric characters, dashes
+            (&#8216;<code class="computeroutput">-</code>&#8217;), and underscores
+            (&#8216;<code class="computeroutput">_</code>&#8217;).
+          </li>
+<li class="listitem">
+            <em class="parameter"><code>sources</code></em> is the list of source files and other main
+            targets that must be combined.
+          </li>
+<li class="listitem">
+            <em class="parameter"><code>requirements</code></em> is the list of properties that must always
+            be present when this main target is built.
+          </li>
+<li class="listitem">
+            <em class="parameter"><code>default-build</code></em> is the list of properties that will be used
+            unless some other value of the same feature is already
+            specified, e.g. on the command line or by propagation from a dependent target.
+          </li>
+<li class="listitem">
+            <em class="parameter"><code>usage-requirements</code></em> is the list of properties that will be
+            propagated to all main targets that use this one, i.e. to all its
+            dependents.
+          </li>
+</ul></div>
+<p>
+        Some main target rules have a different list of parameters as explicitly
+        stated in their documentation.
+      </p>
+<p>The actual requirements for a target are obtained by refining
+      requirements of the project where a target is declared with the
+      explicitly specified requirements. The same is true for
+      usage-requirements. More details can be found in
+      <a class="xref" href="reference.html#bbv2.reference.variants.proprefine" title="Property refinement">the section called &#8220;Property refinement&#8221;</a>
+      </p>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3896594"></a>Name</h4></div></div></div>
+<p>The name of main target has two purposes. First, it's used to refer to this target from
+        other targets and from command line. Second, it's used to compute the names of the generated files.
+        Typically, filenames are obtained from main target name by appending system-dependent suffixes and
+        prefixes.
+        </p>
+<p>The name of a main target can contain alphanumeric characters,
+        dashes, undescores and dots. The entire
+        name is significant when resolving references from other targets. For determining filenames, only the
+        part before the first dot is taken. For example:</p>
+<pre class="programlisting">
+obj test.release : test.cpp : &lt;variant&gt;release ;
+obj test.debug : test.cpp : &lt;variant&gt;debug ;
+</pre>
+<p>will generate two files named <code class="filename">test.obj</code> (in two different directories), not
+        two files named <code class="filename">test.release.obj</code> and <code class="filename">test.debug.obj</code>.
+        </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3896750"></a>Sources</h4></div></div></div>
+<p>The list of sources specifies what should be processed to
+        get the resulting targets. Most of the time, it's just a list of
+        files. Sometimes, you'll want to automatically construct the
+        list of source files rather than having to spell it out
+        manually, in which case you can use the
+        <code class="computeroutput">glob</code> rule. Here are two examples:</p>
+<pre class="programlisting">
+exe a : a.cpp ;           # a.cpp is the only source file
+exe b : [ glob *.cpp ] ;  # all .cpp files in this directory are sources
+</pre>
+<p>
+        Unless you specify a file with an absolute path, the name is
+        considered relative to the source directory&#8202;&#8212;&#8202;which is typically
+        the directory where the Jamfile is located, but can be changed as
+        described in <a class="xref" href="overview.html#bbv2.overview.projects.attributes.projectrule">the section called &#8220;Projects&#8221;</a>.
+        </p>
+<p>
+          
+          The list of sources can also refer to other main targets. Targets in
+          the same project can be referred to by name, while targets in other
+          projects must be qualified with a directory or a symbolic project
+          name. The directory/project name is separated from the target name by
+          a double forward slash. There is no special syntax to distinguish the
+          directory name from the project name&#8212;the part before the double
+          slash is first looked up as project name, and then as directory name.
+          For example:
+        </p>
+<pre class="programlisting">
+lib helper : helper.cpp ;
+exe a : a.cpp helper ;
+# Since all project ids start with slash, ".." is a directory name.
+exe b : b.cpp ..//utils ;
+exe c : c.cpp /boost/program_options//program_options ;
+</pre>
+<p>
+          The first exe uses the library defined in the same project. The second
+          one uses some target (most likely a library) defined by a Jamfile one
+          level higher. Finally, the third target uses a <a href="http://boost.org" target="_top">C++ Boost</a> library, referring to it using
+          its absolute symbolic name. More information about target references
+          can be found in <a class="xref" href="tutorial.html#bbv2.tutorial.libs" title="Dependent Targets">the section called &#8220;Dependent Targets&#8221;</a> and <a class="xref" href="reference.html#bbv2.reference.ids" title="Target identifiers and references">the section called &#8220;Target identifiers and references&#8221;</a>.
+        </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.overview.targets.requirements"></a>Requirements</h4></div></div></div>
+<a class="indexterm" name="id3896849"></a><p>Requirements are the properties that should always be present when
+        building a target. Typically, they are includes and defines:
+</p>
+<pre class="programlisting">
+exe hello : hello.cpp : &lt;include&gt;/opt/boost &lt;define&gt;MY_DEBUG ;
+</pre>
+<p>
+        There is a number of other features, listed in
+        <a class="xref" href="reference.html#bbv2.overview.builtins.features" title="Builtin features">the section called &#8220;Builtin features&#8221;</a>. For example if
+        a library can only be built statically, or a file can't be compiled
+        with optimization due to a compiler bug, one can use
+</p>
+<pre class="programlisting">
+lib util : util.cpp : &lt;link&gt;static ;
+obj main : main.cpp : &lt;optimization&gt;off ;
+</pre>
+<p>
+        </p>
+<p><a name="bbv2.overview.targets.requirements.conditional"></a>Sometimes, particular relationships need to be maintained
+        among a target's build properties. This can be achieved with
+        <em class="firstterm">conditional
+        requirements</em>. For example, you might want to set
+        specific <code class="computeroutput">#defines</code> when a library is built as shared,
+        or when a target's <code class="computeroutput">release</code> variant is built in
+        release mode.
+</p>
+<pre class="programlisting">
+lib network : network.cpp
+    : <span class="bold"><strong>&lt;link&gt;shared:&lt;define&gt;NEWORK_LIB_SHARED</strong></span>
+     &lt;variant&gt;release:&lt;define&gt;EXTRA_FAST
+    ;
+</pre>
+<p>
+
+        In the example above, whenever <code class="filename">network</code> is
+        built with <code class="computeroutput">&lt;link&gt;shared</code>,
+        <code class="computeroutput">&lt;define&gt;NEWORK_LIB_SHARED</code> will be in its
+        properties, too.
+        </p>
+<p>You can use several properties in the condition, for example:
+</p>
+<pre class="programlisting">
+lib network : network.cpp
+    : &lt;toolset&gt;gcc,&lt;optimization&gt;speed:&lt;define&gt;USE_INLINE_ASSEMBLER
+    ;
+</pre>
+<p>
+        </p>
+<p><a name="bbv2.overview.targets.requirements.indirect"></a>
+          A more powerful variant of conditional requirements
+          is <em class="firstterm">indirect conditional requirements</em>.
+          You can provide a rule that will be called with the current build properties and can compute additional properties
+          to be added. For example:
+</p>
+<pre class="programlisting">
+lib network : network.cpp
+    : &lt;conditional&gt;@my-rule
+    ;
+rule my-rule ( properties * )
+{
+    local result ;
+    if &lt;toolset&gt;gcc &lt;optimization&gt;speed in $(properties)
+    {
+        result += &lt;define&gt;USE_INLINE_ASSEMBLER ;
+    }
+    return $(result) ;
+}
+</pre>
+<p>
+        This example is equivalent to the previous one, but for complex cases, indirect conditional
+        requirements can be easier to write and understand.
+        </p>
+<p>Requirements explicitly specified for a target are usually
+        combined with the requirements specified for the containing project. You
+        can cause a target to completely ignore specific project's requirement
+        using the syntax by adding a minus sign before a property, for example:
+</p>
+<pre class="programlisting">
+exe main : main.cpp : <span class="bold"><strong>-&lt;define&gt;UNNECESSARY_DEFINE</strong></span> ;
+</pre>
+<p>
+        This syntax is the only way to ignore free properties from a parent,
+        such as defines. It can be also useful for ordinary properties. Consider
+        this example:
+</p>
+<pre class="programlisting">
+project test : requirements &lt;threading&gt;multi ;
+exe test1 : test1.cpp ;
+exe test2 : test2.cpp : &lt;threading&gt;single ;
+exe test3 : test3.cpp : -&lt;threading&gt;multi ;
+</pre>
+<p>
+        Here, <code class="computeroutput">test1</code> inherits project requirements and will always
+        be built in multi-threaded mode. The <code class="computeroutput">test2</code> target
+        <span class="emphasis"><em>overrides</em></span> project's requirements and will
+        always be built in single-threaded mode. In contrast, the
+        <code class="computeroutput">test3</code> target <span class="emphasis"><em>removes</em></span> a property
+        from project requirements and will be built either in single-threaded or
+        multi-threaded mode depending on which variant is requested by the
+        user.</p>
+<p>Note that the removal of requirements is completely textual:
+        you need to specify exactly the same property to remove it.</p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3897336"></a>Default Build</h4></div></div></div>
+<p>The <code class="varname">default-build</code> parameter
+        is a set of properties to be used if the build request does
+        not otherwise specify a value for features in the set. For example:
+</p>
+<pre class="programlisting">
+exe hello : hello.cpp : : &lt;threading&gt;multi ;
+</pre>
+<p>
+        would build a multi-threaded target unless the user
+        explicitly requests a single-threaded version. The difference between
+        requirements and default-build is that requirements cannot be
+        overridden in any way.
+        </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3897364"></a>Additional Information</h4></div></div></div>
+<p>
+          The ways a target is built can be so different that
+          describing them using conditional requirements would be
+          hard. For example, imagine that a library actually uses
+          different source files depending on the toolset used to build
+          it. We can express this situation using <em class="firstterm">target
+          alternatives</em>:
+</p>
+<pre class="programlisting">
+lib demangler : dummy_demangler.cpp ;                      # alternative 1
+lib demangler : demangler_gcc.cpp : &lt;toolset&gt;gcc ;   # alternative 2
+lib demangler : demangler_msvc.cpp : &lt;toolset&gt;msvc ; # alternative 3
+</pre>
+<p>
+          In the example above, when built with <code class="literal">gcc</code>
+          or <code class="literal">msvc</code>, <code class="filename">demangler</code>
+          will use a source file specific to the toolset.  Otherwise, it
+          will use a generic source file,
+          <code class="filename">dummy_demangler.cpp</code>.
+        </p>
+<p>It is possible to declare a target inline, i.e. the "sources"
+        parameter may include calls to other main rules. For example:</p>
+<pre class="programlisting">
+exe hello : hello.cpp
+    [ obj helpers : helpers.cpp : &lt;optimization&gt;off ] ;</pre>
+<p>
+           Will cause "helpers.cpp" to be always compiled without
+           optimization. When referring to an inline main target, its declared
+           name must be prefixed by its parent target's name and two dots. In
+           the example above, to build only helpers, one should run
+           <code class="computeroutput">bjam hello..helpers</code>.
+         </p>
+<p>When no target is requested on the command line, all targets in the
+         current project will be built. If a target should be built only by
+         explicit request, this can be expressed by the
+         <code class="computeroutput">explicit</code> rule:
+         </p>
+<pre class="programlisting">
+explicit install_programs ;</pre>
+<p>
+         </p>
+</div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.overview.projects"></a>Projects</h3></div></div></div>
+<p>As mentioned before, targets are grouped into projects,
+      and each Jamfile is a separate project. Projects are useful
+      because they allow us to group related targets together, define
+      properties common to all those targets, and assign a symbolic
+      name to the project that can be used in referring to its
+      targets.
+      </p>
+<p>Projects are named using the
+      <code class="computeroutput">project</code> rule, which has the
+      following syntax:
+</p>
+<pre class="programlisting">
+project <em class="replaceable"><code>id</code></em> : <em class="replaceable"><code>attributes</code></em> ;
+</pre>
+<p>
+        Here, <em class="replaceable"><code>attributes</code></em> is a sequence of
+        rule arguments, each of which begins with an attribute-name
+        and is followed by any number of build properties. The list
+        of attribute names along with its handling is also shown in
+        the table below. For example, it is possible to write:
+</p>
+<pre class="programlisting">
+project tennis
+    : requirements &lt;threading&gt;multi
+    : default-build release
+    ;
+</pre>
+<p>
+      </p>
+<p>The possible attributes are listed below.</p>
+<p><span class="emphasis"><em>Project id</em></span> is a short way to denote a project, as
+        opposed to the Jamfile's pathname. It is a hierarchical path,
+        unrelated to filesystem, such as "boost/thread". <a class="link" href="reference.html#bbv2.reference.ids" title="Target identifiers and references">Target references</a> make use of project ids to
+        specify a target.</p>
+<p><span class="emphasis"><em>Source location</em></span> specifies the directory where sources
+        for the project are located.</p>
+<p><span class="emphasis"><em>Project requirements</em></span> are requirements that apply to
+        all the targets in the projects as well as all subprojects.</p>
+<p><span class="emphasis"><em>Default build</em></span> is the build request that should be
+        used when no build request is specified explicitly.</p>
+<p><a name="bbv2.overview.projects.attributes.projectrule"></a>
+        The default values for those attributes are
+        given in the table below.
+
+        </p>
+<div class="table">
+<a name="id3897577"></a><p class="title"><b>Table&#160;39.3.&#160;</b></p>
+<div class="table-contents"><table class="table" summary="">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>Attribute</th>
+<th>Name</th>
+<th>Default value</th>
+<th>Handling by the <code class="computeroutput">project</code>
+                rule</th>
+</tr></thead>
+<tbody>
+<tr>
+<td>Project id</td>
+<td>none</td>
+<td>none</td>
+<td>Assigned from the first parameter of the 'project' rule.
+                  It is assumed to denote absolute project id.</td>
+</tr>
+<tr>
+<td>Source location</td>
+<td><code class="literal">source-location</code></td>
+<td>The location of jamfile for the project</td>
+<td>Sets to the passed value</td>
+</tr>
+<tr>
+<td>Requirements</td>
+<td><code class="literal">requirements</code></td>
+<td>The parent's requirements</td>
+<td>The parent's requirements are refined with the passed
+                  requirement and the result is used as the project
+                  requirements.</td>
+</tr>
+<tr>
+<td>Default build</td>
+<td><code class="literal">default-build</code></td>
+<td>none</td>
+<td>Sets to the passed value</td>
+</tr>
+<tr>
+<td>Build directory</td>
+<td><code class="literal">build-dir</code></td>
+<td>Empty if the parent has no build directory set.
+                Otherwise, the parent's build directory with the
+                relative path from parent to the current project
+                appended to it.
+                </td>
+<td>Sets to the passed value, interpreted as relative to the
+                  project's location.</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<p><br class="table-break">
+        </p>
+<p>Besides defining projects and main targets, Jamfiles
+      often invoke various utility rules. For the full list of rules
+      that can be directly used in Jamfile see
+      <a class="xref" href="reference.html#bbv2.reference.rules" title="Builtin rules">the section called &#8220;Builtin rules&#8221;</a>.
+      </p>
+<p>Each subproject inherits attributes, constants and rules
+      from its parent project, which is defined by the nearest
+      Jamfile in an ancestor directory above
+      the subproject.  The top-level project is declared in a file
+      called <code class="filename">Jamroot</code> rather than
+      <code class="filename">Jamfile</code>.  When loading a project,
+      Boost.Build looks for either <code class="filename">Jamroot</code> or
+      <code class="computeroutput">Jamfile</code>.  They are handled identically, except
+      that if the file is called <code class="filename">Jamroot</code>, the
+      search for a parent project is not performed.
+      </p>
+<p>Even when building in a subproject directory, parent
+      project files are always loaded before those of their
+      subprojects, so that every definition made in a parent project
+      is always available to its children. The loading order of any
+      other projects is unspecified.  Even if one project refers to
+      another via the <code class="computeroutput">use-project</code> or a target reference,
+      no specific order should be assumed.
+      </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>Giving the root project the special name
+        &#8220;<code class="filename">Jamroot</code>&#8221; ensures that
+        Boost.Build won't misinterpret a directory above it as the
+        project root just because the directory contains a Jamfile.
+        
+        </p></td></tr>
+</table></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.overview.build_process"></a>The Build Process</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="overview.html#bbv2.overview.build_request">Build Request</a></span></dt>
+<dt><span class="section"><a href="overview.html#id3897894">Building a main target</a></span></dt>
+<dt><span class="section"><a href="overview.html#id3898010">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 &#8220;metatarget.&#8221;
+      
+      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"><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>
+        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></td></tr>
+</table></div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.overview.build_request"></a>Build Request</h4></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 class="link" href="reference.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 class="xref" href="overview.html#bbv2.overview.invocation" title="Invocation">the section called &#8220;Invocation&#8221;</a>.
+      </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3897894"></a>Building a main target</h4></div></div></div>
+<p>When you request, directly or indirectly, a build of a main target
+        with specific requirements, the following steps are done. Some brief
+        explanation is provided, and more details are given in <a class="xref" href="reference.html#bbv2.reference.buildprocess" title="Build process">the section called &#8220;Build process&#8221;</a>.
+        </p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem"><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 class="listitem"><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 class="listitem"><p>Determining "common" properties.
+          
+              The build request
+              is <a class="link" href="reference.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 class="listitem"><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 class="link" href="reference.html#bbv2.reference.ids" title="Target identifiers and references">target references</a>. For each
+              reference, we take all <a class="link" href="reference.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 class="listitem"><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 class="listitem"><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 class="listitem"><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>
+<p>
+      </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3898010"></a>Building a Project</h4></div></div></div>
+<p>Often, a user builds a complete project, not just one main
+      target. In fact, invoking <span class="command"><strong>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>
+</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 &#169; 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="tutorial.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="tasks.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
diff --git a/doc/html/bbv2/reference.html b/doc/html/bbv2/reference.html
new file mode 100755
index 0000000000..8748c815c2
--- /dev/null
+++ b/doc/html/bbv2/reference.html
@@ -0,0 +1,1850 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Reference</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&#160;39.&#160;Boost.Build V2 User Manual">
+<link rel="prev" href="tasks.html" title="Common tasks">
+<link rel="next" href="extender.html" title="Extender Manual">
+</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="tasks.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="extender.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.reference"></a>Reference</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="reference.html#bbv2.reference.general">General information</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.rules">Builtin rules</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.overview.builtins.features">Builtin features</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools">Builtin tools</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.buildprocess">Build process</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.definitions">Definitions</a></span></dt>
+</dl></div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.reference.general"></a>General information</h3></div></div></div>
+<div class="toc"><dl><dt><span class="section"><a href="reference.html#bbv2.reference.init">Initialization</a></span></dt></dl></div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.reference.init"></a>Initialization</h4></div></div></div>
+<p>bjam's first job upon startup is to load the Jam code that
+        implements the build system. To do this, it searches for a file
+        called <code class="filename">boost-build.jam</code>, first in the invocation directory, then
+        in its parent and so forth up to the filesystem root, and finally
+        in the directories specified by the environment variable
+        BOOST_BUILD_PATH. When found, the file is interpreted, and should
+        specify the build system location by calling the boost-build
+        rule:</p>
+<pre class="programlisting">
+rule boost-build ( location ? )
+</pre>
+<p>
+        If location is a relative path, it is treated as relative to
+        the directory of <code class="filename">boost-build.jam</code>. The directory specified by
+        that location and the directories in BOOST_BUILD_PATH are then searched for
+        a file called <code class="filename">bootstrap.jam</code>, which is expected to
+        bootstrap the build system. This arrangement allows the build
+        system to work without any command-line or environment variable
+        settings. For example, if the build system files were located in a
+        directory "build-system/" at your project root, you might place a
+        <code class="filename">boost-build.jam</code> at the project root containing:
+
+</p>
+<pre class="programlisting">
+boost-build build-system ;
+</pre>
+<p>
+
+        In this case, running bjam anywhere in the project tree will
+        automatically find the build system.</p>
+<p>The default <code class="filename">bootstrap.jam</code>, after loading some standard
+        definitions, loads two <code class="filename">site-config.jam</code> and <code class="filename">user-config.jam</code>.</p>
+</div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.reference.rules"></a>Builtin rules</h3></div></div></div>
+<p>This section contains the list of all rules that
+    can be used in Jamfile&#8212;both rules that define new
+    targets and auxiliary rules.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">exe</code></span></dt>
+<dd><p>Creates an executable file. See
+        <a class="xref" href="tasks.html#bbv2.tasks.programs" title="Programs">the section called &#8220;Programs&#8221;</a>.</p></dd>
+<dt><span class="term"><code class="literal">lib</code></span></dt>
+<dd><p>Creates an library file. See
+        <a class="xref" href="tasks.html#bbv2.tasks.libraries" title="Libraries">the section called &#8220;Libraries&#8221;</a>.</p></dd>
+<dt><span class="term"><code class="literal">install</code></span></dt>
+<dd><p>Installs built targets and other files. See
+        <a class="xref" href="tasks.html#bbv2.tasks.installing" title="Installing">the section called &#8220;Installing&#8221;</a>.</p></dd>
+<dt><span class="term"><code class="literal">alias</code></span></dt>
+<dd><p>Creates an alias for other targets. See
+        <a class="xref" href="tasks.html#bbv2.tasks.alias" title="Alias">the section called &#8220;Alias&#8221;</a>.</p></dd>
+<dt><span class="term"><code class="literal">unit-test</code></span></dt>
+<dd><p>Creates an executable that will be automatically run. See
+        <a class="xref" href="tasks.html#bbv2.builtins.testing" title="Testing">the section called &#8220;Testing&#8221;</a>.</p></dd>
+<dt>
+<span class="term"><code class="literal">compile</code>, </span><span class="term"><code class="literal">compile-fail</code>, </span><span class="term"><code class="literal">link</code>, </span><span class="term"><code class="literal">link-fail</code>, </span><span class="term"><code class="literal">run</code>, </span><span class="term"><code class="literal">run-fail</code></span>
+</dt>
+<dd><p>Specialized rules for testing. See
+        <a class="xref" href="tasks.html#bbv2.builtins.testing" title="Testing">the section called &#8220;Testing&#8221;</a>.</p></dd>
+<dt><span class="term"><code class="literal">obj</code></span></dt>
+<dd><p>Creates an object file. Useful when a single source
+        file must be compiled with special properties.</p></dd>
+<dt><span class="term"><code class="literal">preprocessed</code></span></dt>
+<dd><p>Creates an preprocessed source file. The arguments follow the
+        <a class="link" href="overview.html#bbv2.main-target-rule-syntax">common syntax</a>.</p></dd>
+<dt><span class="term"><code class="literal">glob</code></span></dt>
+<dd>
+<p>The <code class="computeroutput">glob</code> rule takes a list shell pattern
+        and returns the list of files in the project's source directory that
+        match the pattern. For example:
+        </p>
+<pre class="programlisting">
+lib tools : [ glob *.cpp ] ;
+        </pre>
+<p>
+        It is possible to also pass a second argument&#8212;the list of
+        exclude patterns. The result will then include the list of
+        files patching any of include patterns, and not matching any
+        of the exclude patterns. For example:
+        </p>
+<pre class="programlisting">
+lib tools : [ glob *.cpp : file_to_exclude.cpp bad*.cpp ] ;
+        </pre>
+<p>
+        </p>
+</dd>
+<dt>
+<a name="bbv2.reference.glob-tree"></a><span class="term"><code class="literal">glob-tree</code></span>
+</dt>
+<dd>
+<p>The <code class="computeroutput">glob-tree</code> is similar to the
+        <code class="computeroutput">glob</code> except that it operates recursively from
+        the directory of the containing Jamfile. For example:
+        </p>
+<pre class="programlisting">
+ECHO [ glob-tree *.cpp : .svn ] ;
+        </pre>
+<p>
+        will print the names of all C++ files in your project. The
+        <code class="literal">.svn</code> exclude pattern prevents the
+        <code class="computeroutput">glob-tree</code> rule from entering administrative
+        directories of the Subversion version control system.
+        </p>
+</dd>
+<dt><span class="term"><code class="literal">project</code></span></dt>
+<dd><p>Declares project id and attributes, including
+        project requirements. See <a class="xref" href="overview.html#bbv2.overview.projects" title="Projects">the section called &#8220;Projects&#8221;</a>.
+        </p></dd>
+<dt><span class="term"><code class="literal">use-project</code></span></dt>
+<dd><p>Assigns a symbolic project ID to a project at
+        a given path. This rule must be better documented!
+        </p></dd>
+<dt><span class="term"><code class="literal">explicit</code></span></dt>
+<dd><p>The <code class="literal">explicit</code> rule takes a single
+        parameter&#8212;a list of target names. The named targets will
+        be marked explicit, and will be built only if they are explicitly
+        requested on the command line, or if their dependents are built.
+        Compare this to ordinary targets, that are built implicitly when
+        their containing project is built.</p></dd>
+<dt><span class="term"><code class="literal">always</code></span></dt>
+<dd>
+<p>The <code class="literal">always</code> funciton takes a single
+        parameter&#8212;a list of metatarget names. The top-level targets produced
+        by the named metatargets will be always considered out of date. Consider this example:
+        </p>
+<pre class="programlisting">
+exe hello : hello.cpp ;
+exe bye : bye.cpp ;
+always hello ;
+</pre>
+<p>If a build of <code class="filename">hello</code> is requested, then the binary will
+        always be relinked. The object files will not be recompiled, though. Note that if
+        a build of <code class="filename">hello</code> is not requested, for example you specify just
+        <code class="filename">bye</code> on the command line, <code class="filename">hello</code> will not
+        be relinked.</p>
+</dd>
+<dt><span class="term"><code class="literal">constant</code></span></dt>
+<dd>
+<p>Sets project-wide constant. Takes two
+        parameters: variable name and a value and makes the specified
+        variable name accessible in this Jamfile and any child Jamfiles.
+        For example:
+        </p>
+<pre class="programlisting">
+constant VERSION : 1.34.0 ;
+        </pre>
+<p>
+        </p>
+</dd>
+<dt><span class="term"><code class="literal">path-constant</code></span></dt>
+<dd>
+<p>Same as <code class="literal">constant</code> except that
+        the value is treated as path relative to Jamfile location. For example,
+        if <span class="command"><strong>bjam</strong></span> is invoked in the current directory,
+        and Jamfile in <code class="filename">helper</code> subdirectory has:
+        </p>
+<pre class="programlisting">
+path-constant DATA : data/a.txt ;
+        </pre>
+<p>
+        then the variable <code class="varname">DATA</code> will be set to
+        <code class="literal">helper/data/a.txt</code>, and if <span class="command"><strong>bjam</strong></span>
+        is invoked from the <code class="filename">helper</code> directory, then
+        the variable <code class="varname">DATA</code> will be set to
+        <code class="literal">data/a.txt</code>.
+        </p>
+</dd>
+<dt><span class="term"><code class="literal">build-project</code></span></dt>
+<dd><p>Cause some other project to be built. This rule
+        takes a single parameter&#8212;a directory name relative to
+        the containing Jamfile. When the containing Jamfile is built,
+        the project located at that directory will be built as well.
+        At the moment, the parameter to this rule should be a directory
+        name. Project ID or general target references are not allowed.
+        </p></dd>
+<dt><span class="term"><code class="literal">test-suite</code></span></dt>
+<dd><p>This rule is deprecated and equivalent to
+        <code class="computeroutput">alias</code>.</p></dd>
+</dl></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.overview.builtins.features"></a>Builtin features</h3></div></div></div>
+<p>This section documents the features that are built-in into
+    Boost.Build. For features with a fixed set of values, that set is
+    provided, with the default value listed first.</p>
+<a class="indexterm" name="id3900672"></a><div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">variant</code></span></dt>
+<dd>
+<p>
+            A feature combining several low-level features, making it easy to
+            request common build configurations.
+          </p>
+<p>
+            <span class="bold"><strong>Allowed values:</strong></span>
+            <code class="literal">debug</code>, <code class="literal">release</code>,
+            <code class="literal">profile</code>.
+          </p>
+<p>
+            The value <code class="literal">debug</code> expands to
+          </p>
+<pre class="programlisting">
+&lt;optimization&gt;off &lt;debug-symbols&gt;on &lt;inlining&gt;off &lt;runtime-debugging&gt;on
+</pre>
+<p>
+            The value <code class="literal">release</code> expands to
+          </p>
+<pre class="programlisting">
+&lt;optimization&gt;speed &lt;debug-symbols&gt;off &lt;inlining&gt;full &lt;runtime-debugging&gt;off
+</pre>
+<p>
+            The value <code class="literal">profile</code> expands to the same as
+            <code class="literal">release</code>, plus:
+          </p>
+<pre class="programlisting">
+&lt;profiling&gt;on &lt;debug-symbols&gt;on
+</pre>
+<p>
+            Users can define their own build variants using the
+            <code class="computeroutput">variant</code> rule from the <code class="computeroutput">common</code> module.
+          </p>
+<p>
+            <span class="bold"><strong>Note:</strong></span> Runtime debugging is on in
+            debug builds to suit the expectations of people used to various
+            IDEs.
+            
+          </p>
+</dd>
+<dt>
+<a name="bbv2.overview.builtins.features.link"></a><span class="term"><code class="literal">link</code></span>
+</dt>
+<dd>
+<p><span class="bold"><strong>Allowed values:</strong></span> <code class="literal">shared</code>,
+            <code class="literal">static</code></p>
+<p class="simpara">
+            A feature controling how libraries are built.
+          </p>
+</dd>
+<dt>
+<a name="bbv2.overview.builtins.features.runtime-link"></a><span class="term"><code class="literal">runtime-link</code></span>
+</dt>
+<dd>
+<p><span class="bold"><strong>Allowed values:</strong></span> <code class="literal">shared</code>,
+            <code class="literal">static</code></p>
+<p class="simpara">
+            Controls if a static or shared C/C++ runtime should be used. There
+            are some restrictions how this feature can be used, for example
+            on some compilers an application using static runtime should
+            not use shared libraries at all, and on some compilers,
+            mixing static and shared runtime requires extreme care.  Check
+            your compiler documentation for more details.
+          </p>
+</dd>
+<dt><span class="term"><code class="literal">threading</code></span></dt>
+<dd>
+<p><span class="bold"><strong>Allowed values:</strong></span> <code class="literal">single</code>,
+            <code class="literal">multi</code></p>
+<p class="simpara">
+            Controls if the project should be built in multi-threaded mode.  This feature does not
+            necessary change code generation in the compiler, but it causes the compiler to link
+            to additional or different runtime libraries, and define additional preprocessor 
+            symbols (for example, <code class="computeroutput">_MT</code> on Windows and <code class="computeroutput">_REENTRANT</code> on Linux). 
+            How those symbols affect the compiled code depends on the code itself.
+          </p>
+</dd>
+<dt><span class="term"><code class="literal">source</code></span></dt>
+<dd>
+            The <code class="computeroutput">&lt;source&gt;X</code> feature has the same effect on
+            building a target as putting X in the list of sources. It is useful
+            when you want to add the same source to all targets in the project
+            (you can put &lt;source&gt; in requirements) or to conditionally
+            include a source (using conditional requirements, see <a class="xref" href="tutorial.html#bbv2.tutorial.conditions" title="Conditions and alternatives">the section called &#8220;Conditions and alternatives&#8221;</a>). See also the <code class="computeroutput">&lt;library&gt;
+            </code> feature.
+          </dd>
+<dt><span class="term"><code class="literal">library</code></span></dt>
+<dd>
+            This feature is almost equivalent to the <code class="computeroutput">&lt;source&gt;</code>
+            feature, except that it takes effect only for linking. When you want
+            to link all targets in a Jamfile to certain library, the
+            <code class="computeroutput">&lt;library&gt;</code> feature is preferred over
+            <code class="computeroutput">&lt;source&gt;X</code> -- the latter will add the library to
+            all targets, even those that have nothing to do with libraries.
+          </dd>
+<dt><span class="term"><a name="bbv2.builtin.features.dependency"></a>
+          <code class="literal">dependency</code></span></dt>
+<dd>
+            Introduces a dependency on the target named by the value of this
+            feature (so it will be brought up-to-date whenever the target being
+            declared is). The dependency is not used in any other way.
+
+            
+          </dd>
+<dt><span class="term"><a name="bbv2.builtin.features.use"></a>
+          <code class="literal">use</code></span></dt>
+<dd>
+            Introduces a dependency on the target named by the value of this
+            feature (so it will be brought up-to-date whenever the target being
+            declared is), and adds its usage requirements to the build
+            properties
+            
+            of the target being declared. The dependency is not used in any
+            other way. The primary use case is when you want the usage
+            requirements (such as <code class="computeroutput">#include</code> paths) of some library
+            to be applied, but do not want to link to it.
+            
+          </dd>
+<dt><span class="term"><a name="bbv2.reference.features.dll-path"></a>
+        <code class="literal">dll-path</code></span></dt>
+<dd>
+            Specify an additional directory where the system should
+            look for shared libraries when the executable or shared
+            library is run. This feature only affects Unix
+            compilers. Plase see <a class="xref" href="faq.html#bbv2.faq.dll-path" title="Why are the dll-path and hardcode-dll-paths properties useful?">the section called &#8220;
+      Why are the <code class="literal">dll-path</code> and <code class="literal">hardcode-dll-paths
+      </code> properties useful?
+    &#8221;</a>
+            in <a class="xref" href="faq.html" title="Frequently Asked Questions">the section called &#8220;Frequently Asked Questions&#8221;</a> for details.
+          </dd>
+<dt><span class="term"><code class="literal">hardcode-dll-paths</code></span></dt>
+<dd>
+<p class="simpara">
+            Controls automatic generation of dll-path properties.
+          </p>
+<p><span class="bold"><strong>Allowed values:</strong></span>
+            <code class="literal">true</code>, <code class="literal">false</code>.  This property is
+            specific to Unix systems. If an executable is built with
+            <code class="computeroutput">&lt;hardcode-dll-paths&gt;true</code>, the generated binary
+            will contain the list of all the paths to the used shared libraries.
+            As the result, the executable can be run without changing system
+            paths to shared libraries or installing the libraries to system
+            paths. This  is very
+            convenient during development. Plase see the <a class="link" href="faq.html#bbv2.faq.dll-path" title="Why are the dll-path and hardcode-dll-paths properties useful?">FAQ entry</a> for details. Note that on Mac
+            OSX, the paths are unconditionally hardcoded by the linker, and it
+            is not possible to disable that behaviour.</p>
+</dd>
+<dt>
+<span class="term"><code class="literal">cflags</code>, </span><span class="term"><code class="literal">cxxflags</code>, </span><span class="term"><code class="literal">linkflags</code></span>
+</dt>
+<dd>
+            The value of those features is passed without modification to the
+            corresponding tools. For <code class="computeroutput">cflags</code> that is both the C and
+            C++ compilers, for <code class="computeroutput">cxxflags</code> that is the C++ compiler
+            and for <code class="computeroutput">linkflags</code> that is the linker. The features are
+            handy when you are trying to do something special that cannot be
+            achieved by a higher-level feature in Boost.Build.
+          </dd>
+<dt><span class="term"><code class="literal">include</code></span></dt>
+<dd>
+            Specifies an additional include path that is to be passed to C and
+            C++ compilers.
+          </dd>
+<dt><span class="term"><code class="literal">define</code></span></dt>
+<dd>
+            Specifies an preprocessor symbol that should be defined on the command
+            line. You may either specify just the symbol, which will be defined
+            without any value, or both the symbol and the value, separated by
+            equal sign.
+          </dd>
+<dt><span class="term"><code class="literal">warnings</code></span></dt>
+<dd>
+            The <code class="computeroutput">&lt;warnings&gt;</code> feature controls the warning level
+            of compilers. It has the following values:
+            <div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p><code class="computeroutput">off</code> - disables all warnings.</p></li>
+<li class="listitem"><p><code class="computeroutput">on</code> - enables default warning level for the tool.</p></li>
+<li class="listitem"><p><code class="computeroutput">all</code> - enables all warnings.</p></li>
+</ul></div>
+            Default value is <code class="computeroutput">all</code>.
+          </dd>
+<dt><span class="term"><code class="literal">warnings-as-errors</code></span></dt>
+<dd>
+            The <code class="computeroutput">&lt;warnings-as-errors&gt;</code> makes it possible to
+            treat warnings as errors and abort compilation on a warning. The
+            value <code class="computeroutput">on</code> enables this behaviour. The default value is
+            <code class="computeroutput">off</code>.
+          </dd>
+<dt><span class="term"><code class="literal">build</code></span></dt>
+<dd>
+<p><span class="bold"><strong>Allowed values:</strong></span> <code class="literal">no</code></p>
+<p>
+            The <code class="computeroutput">build</code> feature is used to conditionally disable
+            build of a target. If <code class="computeroutput">&lt;build&gt;no</code> is in properties
+            when building a target, build of that target is skipped. Combined
+            with conditional requirements this allows you to skip building some
+            target in configurations where the build is known to fail.
+          </p>
+</dd>
+<dt><span class="term"><code class="literal">tag</code></span></dt>
+<dd>
+<p>The <code class="literal">tag</code> feature is used to customize
+        the name of the generated files. The value should have the form:
+</p>
+<pre class="programlisting">@<em class="replaceable"><code>rulename</code></em></pre>
+<p> where
+        <em class="replaceable"><code>rulename</code></em> should be a name of a rule with the
+        following signature:
+</p>
+<pre class="programlisting">rule tag ( name : type ? : property-set )</pre>
+<p>
+        The rule will be called for each target with the default name computed
+        by Boost.Build, the type of the target, and property set. The rule can
+        either return a string that must be used as the name of the target, or
+        an empty string, in which case the default name will be used.
+        </p>
+<p>Most typical use of the <code class="literal">tag</code> feature is to
+        encode build properties, or library version in library target names. You
+        should take care to return non-empty string from the tag rule only for
+        types you care about &#8212; otherwise, you might end up modifying
+        names of object files, generated header file and other targets for which
+        changing names does not make sense.</p>
+</dd>
+<dt><span class="term"><code class="literal">debug-symbols</code></span></dt>
+<dd>
+<p><span class="bold"><strong>Allowed values:</strong></span> <code class="literal">on</code>, <code class="literal">off</code>.</p>
+<p>The <code class="literal">debug-symbols</code> feature specifies if
+          produced object files, executables and libraries should include
+          debug information.
+          Typically, the value of this feature is implicitly set by the
+          <code class="literal">variant</code> feature, but it can be explicitly
+          specified by the user. The most common usage is to build
+          release variant with debugging information.</p>
+</dd>
+<dt><span class="term"><code class="literal">target-os</code></span></dt>
+<dd>
+<a name="bbv2.reference.features.target-os"></a><p>
+            The operating system for which the code is to be generated. The
+            compiler you used should be the compiler for that operating
+            system. This option causes Boost.Build to use naming conventions
+            suitable for that operating system, and adjust build process
+            accordingly. For example, with gcc, it controls if import
+            libraries are produced for shared libraries or not.                       
+          </p>
+<p>The complete list of possible values for this feature is: 
+            aix, bsd, cygwin, darwin, freebsd, hpux, iphone, linux, netbsd,
+            openbsd, osf, qnx, qnxnto, sgi, solaris, unix, unixware, windows.
+          </p>
+<p>See <a class="xref" href="tasks.html#bbv2.tasks.crosscompile" title="Cross-compilation">the section called &#8220;Cross-compilation&#8221;</a> for details of
+          crosscompilation</p>
+</dd>
+<dt><span class="term"><code class="literal">architecture</code></span></dt>
+<dd><p>The <code class="literal">architecture</code> features specifies
+          the general processor familty to generate code for.</p></dd>
+<dt><span class="term"><code class="literal">instruction-set</code></span></dt>
+<dd>
+<p>
+            <span class="bold"><strong>Allowed values:</strong></span> depend on the used
+            toolset.
+          </p>
+<p>The <code class="literal">instruction-set</code> specifies for which
+          specific instruction set the code should be generated.  The
+          code in general might not run on processors with older/different
+          instruction sets.</p>
+<p>While Boost.Build allows a large set of possible values
+          for this features, whether a given value works depends on which
+          compiler you use. Please see
+          <a class="xref" href="reference.html#bbv2.reference.tools.compilers" title="C++ Compilers">the section called &#8220;C++ Compilers&#8221;</a> for details.
+          </p>
+</dd>
+<dt><span class="term"><code class="literal">address-model</code></span></dt>
+<dd>
+<p><span class="bold"><strong>Allowed values:</strong></span> <code class="literal">32</code>, <code class="literal">64</code>.</p>
+<p>The <code class="literal">address-model</code> specifies if 32-bit or
+          64-bit code should be generated by the compiler. Whether this feature
+          works depends on the used compiler, its version, how the compiler is
+          configured, and the values of the <code class="literal">architecture</code>
+          <code class="literal">instruction-set</code>
+          features. Please see <a class="xref" href="reference.html#bbv2.reference.tools.compilers" title="C++ Compilers">the section called &#8220;C++ Compilers&#8221;</a>
+          for details.</p>
+</dd>
+<dt><span class="term"><code class="literal">c++-template-depth</code></span></dt>
+<dd>
+<p>
+            <span class="bold"><strong>Allowed values:</strong></span> Any positive
+            integer.
+          </p>
+<p>
+            This feature allows configuring a C++ compiler with the maximal
+            template instantiation depth parameter. Specific toolsets may or may
+            not provide support for this feature depending on whether their
+            compilers provide a corresponding command-line option.
+          </p>
+<p>
+            <span class="bold"><strong>Note:</strong></span> Due to some internal details
+            in the current Boost Build implementation it is not possible to have
+            features whose valid values are all positive integer. As a
+            workaround a large set of allowed values has been defined for this
+            feature and, if a different one is needed, user can easily add it by
+            calling the feature.extend rule.
+          </p>
+</dd>
+<dt><span class="term"><code class="literal">embed-manifest</code></span></dt>
+<dd>
+<a class="indexterm" name="id3901864"></a><a class="indexterm" name="id3901873"></a><p>
+            <span class="bold"><strong>Allowed values:</strong></span> on, off.
+          </p>
+<p>This feature is specific to the msvc toolset (see
+          <a class="xref" href="reference.html#bbv2.reference.tools.compiler.msvc" title="Microsoft Visual C++">the section called &#8220;Microsoft Visual C++&#8221;</a>),
+          and controls whether the manifest files should be embedded inside
+          executables and shared libraries, or placed alongside them.  This
+          feature corresponds to the IDE option found in the project settings dialog,
+          under <span class="guimenu">Configuration Properties</span> &#8594; <span class="guisubmenu">Manifest Tool</span> &#8594; <span class="guisubmenu">Input and Output</span> &#8594; <span class="guimenuitem">Embed manifest</span>.
+          </p>
+</dd>
+</dl></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.reference.tools"></a>Builtin tools</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compilers">C++ Compilers</a></span></dt>
+<dt><span class="section"><a href="reference.html#id3904546">Third-party libraries</a></span></dt>
+<dt><span class="section"><a href="reference.html#id3904659">Documentation tools</a></span></dt>
+</dl></div>
+<p>Boost.Build comes with support for a large number of C++ compilers,
+      and other tools. This section documents how to use those tools.</p>
+<p>Before using any tool, you must declare your intention, and possibly
+      specify additional information about the tool's configuration. This is
+      done by calling the <code class="computeroutput">using</code> rule, typically in your
+      <code class="filename">user-config.jam</code>, for example:</p>
+<pre class="programlisting">
+using gcc ;
+</pre>
+<p>additional parameters can be passed just like for other rules, for example:</p>
+<pre class="programlisting">
+using gcc : 4.0 : g++-4.0 ;
+</pre>
+<p>The options that can be passed to each tool are documented in the
+      subsequent sections.</p>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.reference.tools.compilers"></a>C++ Compilers</h4></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.gcc">GNU C++</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.darwin">Apple Darwin gcc</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.msvc">Microsoft Visual C++</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.intel">Intel C++</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.acc">HP aC++ compiler</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.borland">Borland C++ Compiler</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.como">Comeau C/C++ Compiler</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.cw">Code Warrior</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.dmc">Digital Mars C/C++ Compiler</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.hp_cxx">HP C++ Compiler for Tru64 Unix</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.sun">Sun Studio</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.vacpp">IBM Visual Age</a></span></dt>
+</dl></div>
+<p>This section lists all Boost.Build modules that support C++
+          compilers and documents how each one can be initialized.  The name
+          of support module for compiler is also the value for
+          the <code class="computeroutput">toolset</code> feature that can be used to explicitly
+          request that compiler. </p>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.compiler.gcc"></a>GNU C++</h5></div></div></div>
+<p>The <code class="computeroutput">gcc</code> module supports the
+          <a href="http://gcc.gnu.org" target="_top">GNU C++ compiler</a>
+          on Linux, a number of Unix-like system including SunOS and on Windows 
+          (either <a href="http://www.cygwin.com" target="_top">Cygwin</a> or 
+          <a href="http://www.mingw.org" target="_top">MinGW</a>). On Mac OSX, it is recommended
+          to use system gcc, see <a class="xref" href="reference.html#bbv2.reference.tools.compiler.darwin" title="Apple Darwin gcc">the section called &#8220;Apple Darwin gcc&#8221;</a>.
+          </p>
+<p>The <code class="computeroutput">gcc</code> module is initialized using the following
+          syntax:</p>
+<pre class="programlisting">
+using gcc : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
+<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
+<p>
+          If the version is not explicitly specified, it will be
+          automatically detected by running the compiler with the <code class="computeroutput">-v</code>
+          option. If the command is not specified, the <span class="command"><strong>g++</strong></span>
+          binary will be searched in <code class="envar">PATH</code>.</p>
+<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">cflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C sources.</p></dd>
+<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">compileflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling both C and C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">linkflags</code></span></dt>
+<dd><p>Specifies additional command line options that will be
+      passed to the linker.</p></dd>
+<dt><span class="term"><code class="literal">root</code></span></dt>
+<dd><p>Specifies root directory of the compiler installation.
+      This option is necessary only if it is not possible to detect this
+      information from the compiler command&#8212;for example if the specified
+      compiler command is a user script.</p></dd>
+<dt><span class="term"><code class="literal">rc</code></span></dt>
+<dd><p>Specifies the resource compiler command
+                that will be used with the version of gcc that is being
+                configured. This setting makes sense only for Windows and only
+                if you plan to use resource files. By
+                default <span class="command"><strong>windres</strong></span> will be used.</p></dd>
+<dt><span class="term"><code class="literal">rc-type</code></span></dt>
+<dd><p>Specifies the type of resource compiler. The value can
+                be either <code class="computeroutput">windres</code> for msvc resource compiler,
+                or <code class="computeroutput">rc</code> for borland's resource compiler.</p></dd>
+</dl></div>
+<a class="indexterm" name="id3902285"></a>
+
+          In order to compile 64-bit applications, you have to specify
+          <code class="computeroutput">address-model=64</code>, and the <code class="computeroutput">instruction-set</code>
+          feature should refer to a 64 bit processor. Currently, those
+          include <code class="literal">nocona</code>, <code class="literal">opteron</code>,
+          <code class="literal">athlon64</code> and <code class="literal">athlon-fx</code>.
+
+        </div>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.compiler.darwin"></a>Apple Darwin gcc</h5></div></div></div>
+<p>The <code class="computeroutput">darwin</code> module supports the version of gcc that is
+          modified and provided by Apple. The configuration is essentially identical
+          to that of the gcc module.
+          </p>
+<p>
+          <a class="indexterm" name="id3902356"></a>
+          The darwin toolset can generate so called "fat"
+          binaries&#8212;binaries that can run support more than one
+          architecture, or address mode. To build a binary that can run both
+          on Intel and PowerPC processors, specify
+          <code class="computeroutput">architecture=combined</code>. To build a binary that can run
+          both in 32-bit and 64-bit modes, specify
+          <code class="computeroutput">address-model=32_64</code>. If you specify both of those
+          properties, a "4-way" fat binary will be generated.
+          </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.compiler.msvc"></a>Microsoft Visual C++</h5></div></div></div>
+<p>The <code class="computeroutput">msvc</code> module supports the
+          <a href="http://msdn.microsoft.com/visualc/" target="_top">Microsoft Visual
+          C++</a> command-line tools on Microsoft Windows. The supported
+          products and versions of command line tools are listed below:</p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>Visual Studio 2010&#8212;10.0</p></li>
+<li class="listitem"><p>Visual Studio 2008&#8212;9.0</p></li>
+<li class="listitem"><p>Visual Studio 2005&#8212;8.0</p></li>
+<li class="listitem"><p>Visual Studio .NET 2003&#8212;7.1</p></li>
+<li class="listitem"><p>Visual Studio .NET&#8212;7.0</p></li>
+<li class="listitem"><p>Visual Studio 6.0, Service Pack 5&#8212;6.5</p></li>
+</ul></div>
+<p>The <code class="computeroutput">msvc</code> module is initialized using the following
+          syntax:</p>
+<pre class="programlisting">
+using msvc : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;
+          </pre>
+<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
+<p>If the version is not explicitly specified, the most recent
+          version found in the registry will be used instead. If the special
+          value <code class="computeroutput">all</code> is passed as the version, all versions found in
+          the registry will be configured. If a version is specified, but the
+          command is not, the compiler binary will be searched in standard
+          installation paths for that version, followed by <code class="envar">PATH</code>.
+          </p>
+<p>The compiler command should be specified using forward slashes,
+          and quoted.</p>
+<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">cflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C sources.</p></dd>
+<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">compileflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling both C and C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">linkflags</code></span></dt>
+<dd><p>Specifies additional command line options that will be
+      passed to the linker.</p></dd>
+<dt><span class="term"><code class="literal">assembler</code></span></dt>
+<dd><p>The command that compiles assembler sources. If
+              not specified, <span class="command"><strong>ml</strong></span> will be used. The command
+              will be invoked after the setup script was executed and adjusted
+              the <code class="envar">PATH</code> variable.</p></dd>
+<dt><span class="term"><code class="literal">compiler</code></span></dt>
+<dd><p>The command that compiles C and C++ sources. If
+              not specified, <span class="command"><strong>cl</strong></span> will be used. The command
+              will be invoked after the setup script was executed and adjusted
+              the <code class="envar">PATH</code> variable.</p></dd>
+<dt><span class="term"><code class="literal">compiler-filter</code></span></dt>
+<dd><p>Command through which to pipe the output of
+              running the compiler. For example to pass the output to STLfilt.
+              </p></dd>
+<dt><span class="term"><code class="literal">idl-compiler</code></span></dt>
+<dd><p>The command that compiles Microsoft COM interface
+              definition files. If not specified, <span class="command"><strong>midl</strong></span> will
+              be used. The command will be invoked after the setup script was
+              executed and adjusted the <code class="envar">PATH</code> variable.</p></dd>
+<dt><span class="term"><code class="literal">linker</code></span></dt>
+<dd><p>The command that links executables and dynamic
+              libraries. If not specified, <span class="command"><strong>link</strong></span> will be used.
+              The command will be invoked after the setup script was executed
+              and adjusted the <code class="envar">PATH</code> variable.</p></dd>
+<dt><span class="term"><code class="literal">mc-compiler</code></span></dt>
+<dd><p>The command that compiles Microsoft message
+              catalog files. If not specified, <span class="command"><strong>mc</strong></span> will be
+              used. The command will be invoked after the setup script was
+              executed and adjusted the <code class="envar">PATH</code> variable.</p></dd>
+<dt><span class="term"><code class="literal">resource-compiler</code></span></dt>
+<dd><p>The command that compiles resource files. If not
+              specified, <span class="command"><strong>rc</strong></span> will be used. The command will be
+              invoked after the setup script was executed and adjusted the
+              <code class="envar">PATH</code> variable.</p></dd>
+<dt><span class="term"><code class="literal">setup</code></span></dt>
+<dd><p>The filename of the global environment setup
+              script to run before invoking any of the tools defined in this
+              toolset. Will not be used in case a target platform specific
+              script has been explicitly specified for the current target
+              platform. Used setup script will be passed the target platform
+              identifier (x86, x86_amd64, x86_ia64, amd64 or ia64) as a
+              arameter. If not specified a default script is chosen based on the
+              used compiler binary, e.g. <span class="command"><strong>vcvars32.bat</strong></span> or
+              <span class="command"><strong>vsvars32.bat</strong></span>.</p></dd>
+<dt>
+<span class="term"><code class="literal">setup-amd64</code>, </span><span class="term"><code class="literal">setup-i386</code>, </span><span class="term"><code class="literal">setup-ia64</code></span>
+</dt>
+<dd><p>The filename of the target platform specific
+              environment setup script to run before invoking any of the tools
+              defined in this toolset. If not specified the global environment
+              setup script is used.</p></dd>
+</dl></div>
+<div class="section">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="v2.reference.tools.compiler.msvc.64"></a>64-bit support</h6></div></div></div>
+<a class="indexterm" name="id3902833"></a><p>Starting with version 8.0, Microsoft Visual Studio can
+            generate binaries for 64-bit processor, both 64-bit flavours of x86
+            (codenamed AMD64/EM64T), and Itanium (codenamed IA64). In addition,
+            compilers that are itself run in 64-bit mode, for better
+            performance, are provided. The complete list of compiler
+            configurations are as follows (we abbreviate AMD64/EM64T to just
+            AMD64):</p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>32-bit x86 host, 32-bit x86 target</p></li>
+<li class="listitem"><p>32-bit x86 host, 64-bit AMD64 target</p></li>
+<li class="listitem"><p>32-bit x86 host, 64-bit IA64 target</p></li>
+<li class="listitem"><p>64-bit AMD64 host, 64-bit AMD64 target</p></li>
+<li class="listitem"><p>64-bit IA64 host, 64-bit IA64 target</p></li>
+</ul></div>
+<p>
+            The 32-bit host compilers can be always used, even on 64-bit
+            Windows. On the contrary, 64-bit host compilers require both 64-bit
+            host processor and 64-bit Windows, but can be faster. By default,
+            only 32-bit host, 32-bit target compiler is installed, and
+            additional compilers need to be installed explicitly.
+            </p>
+<p>To use 64-bit compilation you should:</p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem"><p>Configure you compiler as usual. If you provide a
+              path to the compiler explicitly, provide the path to the 32-bit
+              compiler. If you try to specify the path to any of 64-bit
+              compilers, configuration will not work.</p></li>
+<li class="listitem"><p>When compiling, use <code class="computeroutput">address-model=64</code>,
+              to generate AMD64 code.</p></li>
+<li class="listitem"><p>To generate IA64 code, use
+              <code class="computeroutput">architecture=ia64</code></p></li>
+</ol></div>
+<p>The (AMD64 host, AMD64 target) compiler will be used
+            automatically when you are generating AMD64 code and are running
+            64-bit Windows on AMD64. The (IA64 host, IA64 target) compiler will
+            never be used, since nobody has an IA64 machine to test.</p>
+<p>It is believed that AMD64 and EM64T targets are essentially
+            compatible. The compiler options <code class="computeroutput">/favor:AMD64</code> and
+            <code class="computeroutput">/favor:EM64T</code>, which are accepted only by AMD64
+            targeting compilers, cause the generated code to be tuned to a
+            specific flavor of 64-bit x86. Boost.Build will make use of those
+            options depending on the value of the<code class="computeroutput">instruction-set</code>
+            feature.</p>
+</div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.compiler.intel"></a>Intel C++</h5></div></div></div>
+<p>The <code class="computeroutput">intel-linux</code> and <code class="computeroutput">intel-win</code> modules
+          support the Intel C++ command-line compiler&#8212;the <a href="http://www.intel.com/software/products/compilers/clin/index.htm" target="_top">Linux</a>
+          and <a href="http://www.intel.com/cd/software/products/asmo-na/eng/compilers/284527.htm" target="_top">
+          Windows</a> versions respectively.</p>
+<p>The module is initialized using the following syntax:</p>
+<pre class="programlisting">
+using intel-linux : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
+<p>or</p>
+<pre class="programlisting">
+using intel-win : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
+<p>respectively.</p>
+<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
+<p>
+          If compiler command is not specified, then Boost.Build will
+          look in <code class="envar">PATH</code> for an executable <span class="command"><strong>icpc</strong></span>
+          (on Linux), or <span class="command"><strong>icc.exe</strong></span> (on Windows).
+          </p>
+<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">cflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C sources.</p></dd>
+<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">compileflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling both C and C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">linkflags</code></span></dt>
+<dd><p>Specifies additional command line options that will be
+      passed to the linker.</p></dd>
+</dl></div>
+<p>The Linux version supports the following additional options:</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">root</code></span></dt>
+<dd><p>Specifies root directory of the compiler installation.
+      This option is necessary only if it is not possible to detect this
+      information from the compiler command&#8212;for example if the specified
+      compiler command is a user script.</p></dd>
+</dl></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.compiler.acc"></a>HP aC++ compiler</h5></div></div></div>
+<p>The <code class="computeroutput">acc</code> module supports the
+<a href="http://h21007.www2.hp.com/dspp/tech/tech_TechSoftwareDetailPage_IDX/1,1703,1740,00.html" target="_top">HP aC++ compiler</a>
+          for the HP-UX operating system.</p>
+<p>The module is initialized using the following
+          syntax:</p>
+<pre class="programlisting">
+using acc : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
+<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
+<p>
+            If the command is not specified, the <span class="command"><strong>aCC</strong></span>
+          binary will be searched in <code class="envar">PATH</code>.</p>
+<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">cflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C sources.</p></dd>
+<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">compileflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling both C and C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">linkflags</code></span></dt>
+<dd><p>Specifies additional command line options that will be
+      passed to the linker.</p></dd>
+</dl></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.compiler.borland"></a>Borland C++ Compiler</h5></div></div></div>
+<p>The <code class="computeroutput">borland</code> module supports the command line
+          C++ compiler included in
+          <a href="http://www.borland.com/us/products/cbuilder/index.html" target="_top">C++ Builder 2006</a>
+          product and earlier version of it, running on Microsoft Windows.</p>
+<p>The supported products are listed below. The version reported
+          by the command lines tools is also listed for reference.:</p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>C++ Builder 2006&#8212;5.8.2</p></li>
+<li class="listitem"><p>CBuilderX&#8212;5.6.5, 5.6.4 (depending on release)</p></li>
+<li class="listitem"><p>CBuilder6&#8212;5.6.4</p></li>
+<li class="listitem"><p>Free command line tools&#8212;5.5.1</p></li>
+</ul></div>
+<p>The module is initialized using the following syntax:</p>
+<pre class="programlisting">
+using borland : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
+<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
+<p>If the command is not specified, Boost.Build will search for
+          a binary named <span class="command"><strong>bcc32</strong></span> in <code class="envar">PATH</code>.</p>
+<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">cflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C sources.</p></dd>
+<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">compileflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling both C and C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">linkflags</code></span></dt>
+<dd><p>Specifies additional command line options that will be
+      passed to the linker.</p></dd>
+</dl></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.compiler.como"></a>Comeau C/C++ Compiler</h5></div></div></div>
+<p>The <code class="computeroutput">como-linux</code> and the <code class="computeroutput">como-win</code>
+          modules supports the
+          <a href="http://www.comeaucomputing.com/" target="_top">Comeau C/C++ Compiler</a>
+          on Linux and Windows respectively.</p>
+<p>The module is initialized using the following syntax:</p>
+<pre class="programlisting">
+using como-linux : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
+<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
+<p>If the command is not specified, Boost.Build will search for
+          a binary named <span class="command"><strong>como</strong></span> in
+          <code class="envar">PATH</code>.</p>
+<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">cflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C sources.</p></dd>
+<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">compileflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling both C and C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">linkflags</code></span></dt>
+<dd><p>Specifies additional command line options that will be
+      passed to the linker.</p></dd>
+</dl></div>
+<p>Before using the Windows version of the compiler, you need to
+          setup necessary environment variables per compiler's documentation. In
+          particular, the <code class="envar">COMO_XXX_INCLUDE</code> variable should be
+          set, where <code class="envar">XXX</code> corresponds to the used backend C
+          compiler.</p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.compiler.cw"></a>Code Warrior</h5></div></div></div>
+<p>The <code class="computeroutput">cw</code> module support CodeWarrior compiler,
+          originally produced by Metrowerks and presently developed by
+          Freescale. Boost.Build supports only the versions of the compiler that
+          target x86 processors. All such versions were released by Metrowerks
+          before aquisition and are not sold any longer. The last version known
+          to work is 9.4.</p>
+<p>The module is initialized using the following syntax:</p>
+<pre class="programlisting">
+using cw : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
+<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
+<p>If the command is not specified, Boost.Build will search for a
+          binary named <span class="command"><strong>mwcc</strong></span> in default installation paths and
+          in <code class="envar">PATH</code>.</p>
+<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">cflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C sources.</p></dd>
+<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">compileflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling both C and C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">linkflags</code></span></dt>
+<dd><p>Specifies additional command line options that will be
+      passed to the linker.</p></dd>
+<dt><span class="term"><code class="literal">root</code></span></dt>
+<dd><p>Specifies root directory of the compiler installation.
+      This option is necessary only if it is not possible to detect this
+      information from the compiler command&#8212;for example if the specified
+      compiler command is a user script.</p></dd>
+<dt><span class="term"><code class="literal">setup</code></span></dt>
+<dd><p>The command that sets up environment variables
+              prior to invoking the compiler. If not specified,
+              <span class="command"><strong>cwenv.bat</strong></span> alongside the compiler binary
+              will be used.</p></dd>
+<dt><span class="term"><code class="literal">compiler</code></span></dt>
+<dd><p>The command that compiles C and C++ sources.
+              If not specified, <span class="command"><strong>mwcc</strong></span> will be used. The
+              command will be invoked after the setup script was
+              executed and adjusted the <code class="envar">PATH</code> variable.</p></dd>
+<dt><span class="term"><code class="literal">linker</code></span></dt>
+<dd><p>The command that links executables and dynamic
+              libraries.
+              If not specified, <span class="command"><strong>mwld</strong></span> will be used. The
+              command will be invoked after the setup script was
+              executed and adjusted the <code class="envar">PATH</code> variable.</p></dd>
+</dl></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.compiler.dmc"></a>Digital Mars C/C++ Compiler</h5></div></div></div>
+<p>The <code class="computeroutput">dmc</code> module supports the
+          <a href="http://www.digitalmars.com/" target="_top">Digital Mars C++ compiler.</a>
+          </p>
+<p>The module is initialized using the following syntax:</p>
+<pre class="programlisting">
+using dmc : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
+<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
+<p>If the command is not specified, Boost.Build will search for
+          a binary named <span class="command"><strong>dmc</strong></span> in
+          <code class="envar">PATH</code>.</p>
+<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">cflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C sources.</p></dd>
+<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">compileflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling both C and C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">linkflags</code></span></dt>
+<dd><p>Specifies additional command line options that will be
+      passed to the linker.</p></dd>
+</dl></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.compiler.hp_cxx"></a>HP C++ Compiler for Tru64 Unix</h5></div></div></div>
+<p>The <code class="computeroutput">hp_cxx</code> modules supports the
+          <a href="http://h30097.www3.hp.com/cplus/?jumpid=reg_R1002_USEN" target="_top">
+            HP C++ Compiler</a> for Tru64 Unix.</p>
+<p>The module is initialized using the following syntax:</p>
+<pre class="programlisting">
+using hp_cxx : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
+<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
+<p>If the command is not specified, Boost.Build will search for
+          a binary named <span class="command"><strong>hp_cxx</strong></span> in <code class="envar">PATH</code>.</p>
+<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">cflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C sources.</p></dd>
+<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">compileflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling both C and C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">linkflags</code></span></dt>
+<dd><p>Specifies additional command line options that will be
+      passed to the linker.</p></dd>
+</dl></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.compiler.sun"></a>Sun Studio</h5></div></div></div>
+<p>The <code class="computeroutput">sun</code> module supports the
+          <a href="http://developers.sun.com/sunstudio/index.jsp" target="_top">
+          Sun Studio</a> C++ compilers for the Solaris OS.</p>
+<p>The module is initialized using the following syntax:</p>
+<pre class="programlisting">
+using sun : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
+<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
+<p>If the command is not specified, Boost.Build will search for
+          a binary named <span class="command"><strong>CC</strong></span>
+          in <code class="filename">/opt/SUNWspro/bin</code> and in
+          <code class="envar">PATH</code>.</p>
+<p>When using this compiler on complex C++ code, such as the
+          <a href="http://boost.org" target="_top">Boost C++ library</a>, it is
+          recommended to specify the following options when intializing the
+          <code class="computeroutput">sun</code> module:
+          </p>
+<pre class="screen">
+-library=stlport4 -features=tmplife -features=tmplrefstatic
+          </pre>
+<p> See the <a href="http://blogs.sun.com/sga/entry/command_line_options" target="_top">
+          Sun C++ Frontend Tales</a> for details.</p>
+<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">cflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C sources.</p></dd>
+<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">compileflags</code></span></dt>
+<dd><p>Specifies additional compiler flags that will be used when
+      compiling both C and C++ sources.</p></dd>
+<dt><span class="term"><code class="literal">linkflags</code></span></dt>
+<dd><p>Specifies additional command line options that will be
+      passed to the linker.</p></dd>
+</dl></div>
+<a class="indexterm" name="id3904464"></a>
+          Starting with Sun Studio 12, you can create 64-bit applications
+          by using the <code class="computeroutput">address-model=64</code> property.
+
+        </div>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.compiler.vacpp"></a>IBM Visual Age</h5></div></div></div>
+<p>The <code class="computeroutput">vacpp</code> module supports the
+          <a href="http://www.ibm.com/software/ad/vacpp" target="_top">IBM Visual
+          Age</a> C++ Compiler, for the AIX operating system. Versions
+          7.1 and 8.0 are known to work.</p>
+<p>The module is initialized using the following
+          syntax:</p>
+<pre class="programlisting">
+using vacpp ;</pre>
+<p>The module does not accept any initialization options. The
+          compiler should be installed in the <code class="filename">/usr/vacpp/bin</code>
+          directory.</p>
+<p>Later versions of Visual Age are known as XL C/C++. They
+          were not tested with the the <code class="computeroutput">vacpp</code> module.</p>
+</div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3904546"></a>Third-party libraries</h4></div></div></div>
+<div class="toc"><dl><dt><span class="section"><a href="reference.html#bbv2.reference.tools.libraries.stlport">STLport library</a></span></dt></dl></div>
+<p>Boost.Build provides special support for some
+        third-party C++ libraries, documented below.</p>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.libraries.stlport"></a>STLport library</h5></div></div></div>
+<a class="indexterm" name="id3904568"></a><p>The <a href="http://stlport.org" target="_top">STLport</a> library
+          is an alternative implementation of C++ runtime library. Boost.Build
+          supports using that library on Windows platfrom.  Linux is
+          hampered by different naming of libraries in each STLport
+          version and is not officially supported.</p>
+<p>Before using STLport, you need to configure it in
+          <code class="filename">user-config.jam</code> using the following syntax:
+          </p>
+<pre class="programlisting">
+using stlport : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : <em class="replaceable"><code>header-path</code></em> : [<span class="optional"><em class="replaceable"><code>library-path</code></em></span>] ;
+</pre>
+<p>
+          Where <em class="replaceable"><code>version</code></em> is the version of
+          STLport, for example <code class="literal">5.1.4</code>,
+          <em class="replaceable"><code>headers</code></em> is the location where
+          STLport headers can be found, and <em class="replaceable"><code>libraries</code></em>
+          is the location where STLport libraries can be found.
+          The version should always be provided, and the library path should
+          be provided if you're using STLport's implementation of
+          iostreams. Note that STLport 5.* always uses its own iostream
+          implementation, so the library path is required.
+          </p>
+<p>When STLport is configured, you can build with STLport by
+          requesting <code class="literal">stdlib=stlport</code> on the command line.
+          </p>
+</div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id3904659"></a>Documentation tools</h4></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.doc.xsltproc">xsltproc</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.doc.boostbook">boostbook</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.doc.doxygen">doxygen</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.doc.quickbook">quickbook</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.tools.doc.fop">fop</a></span></dt>
+</dl></div>
+<p>Boost.Build support for the Boost documentation tools is
+        documented below.
+        </p>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.doc.xsltproc"></a>xsltproc</h5></div></div></div>
+<a class="indexterm" name="id3904681"></a><p>To use xsltproc, you first need to configure it using the following syntax:</p>
+<pre class="programlisting">
+using xsltproc : [<span class="optional"><em class="replaceable"><code>xsltproc</code></em></span>] ;
+</pre>
+<p>
+          Where <em class="replaceable"><code>xsltproc</code></em> is the xsltproc executable.
+          If <em class="replaceable"><code>xsltproc</code></em> is not specified, and the
+          variable XSLTPROC is set, the value of XSLTPROC will be used.
+          Otherwise, xsltproc will be searched for in PATH.
+          </p>
+<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">xsl:param</code></span></dt>
+<dd><p>Values should have the form
+                <em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em></p></dd>
+<dt><span class="term"><code class="literal">xsl:path</code></span></dt>
+<dd><p>Sets an additional search path for xi:include elements.</p></dd>
+<dt><span class="term"><code class="literal">catalog</code></span></dt>
+<dd><p>A catalog file used to rewrite remote URL's to a local copy.</p></dd>
+</dl></div>
+<p>The xsltproc module provides the following rules.  Note that
+          these operate on jam targets and are intended to be used by another
+          toolset, such as boostbook, rather than directly by users.
+          </p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">xslt</code></span></dt>
+<dd>
+<pre class="programlisting">
+rule xslt ( target : source stylesheet : properties * )
+</pre>
+<p>Runs xsltproc to create a single output file.</p>
+</dd>
+<dt><span class="term"><code class="literal">xslt-dir</code></span></dt>
+<dd>
+<pre class="programlisting">
+rule xslt-dir ( target : source stylesheet : properties * : dirname )
+</pre>
+<p>Runs xsltproc to create multiple outputs in a directory.
+                <code class="literal">dirname</code> is unused, but exists for
+                historical reasons.  The output directory is determined from the
+                target.
+                </p>
+</dd>
+</dl></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.doc.boostbook"></a>boostbook</h5></div></div></div>
+<a class="indexterm" name="id3904905"></a><p>To use boostbook, you first need to configure it using the following syntax:</p>
+<pre class="programlisting">
+using boostbook : [<span class="optional"><em class="replaceable"><code>docbook-xsl-dir</code></em></span>] : [<span class="optional"><em class="replaceable"><code>docbook-dtd-dir</code></em></span>] : [<span class="optional"><em class="replaceable"><code>boostbook-dir</code></em></span>] ;
+</pre>
+<p>
+          <em class="replaceable"><code>docbook-xsl-dir</code></em> is the DocBook XSL stylesheet
+          directory. If not provided, we use DOCBOOK_XSL_DIR from the environment
+          (if available) or look in standard locations.  Otherwise, we let the
+          XML processor load the stylesheets remotely.
+          </p>
+<p>
+          <em class="replaceable"><code>docbook-dtd-dir</code></em> is the DocBook DTD directory.
+          If not provided, we use DOCBOOK_DTD_DIR From the environment (if
+          available) or look in standard locations.  Otherwise, we let the XML
+          processor load the DTD remotely.
+          </p>
+<p>
+          <em class="replaceable"><code>boostbook-dir</code></em> is the BoostBook directory
+          with the DTD and XSL subdirs.
+          </p>
+<p>The boostbook module depends on xsltproc.  For pdf or ps output,
+          it also depends on fop.
+          </p>
+<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">format</code></span></dt>
+<dd>
+<p>
+                  <span class="bold"><strong>Allowed values:</strong></span>
+                  <code class="literal">html</code>, <code class="literal">xhtml</code>,
+                  <code class="literal">htmlhelp</code>, <code class="literal">onehtml</code>,
+                  <code class="literal">man</code>, <code class="literal">pdf</code>,
+                  <code class="literal">ps</code>, <code class="literal">docbook</code>,
+                  <code class="literal">fo</code>, <code class="literal">tests</code>.
+                </p>
+<p>The <code class="literal">format</code> feature determines the type
+                of output produced by the boostbook rule.</p>
+</dd>
+</dl></div>
+<p>The boostbook module defines a rule for creating a target
+          following the common syntax.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">boostbook</code></span></dt>
+<dd>
+<pre class="programlisting">
+rule boostbook ( target-name : sources * : requirements * : default-build * )
+</pre>
+<p>Creates a boostbook target.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.doc.doxygen"></a>doxygen</h5></div></div></div>
+<a class="indexterm" name="id3905208"></a><p>To use doxygen, you first need to configure it using the following syntax:</p>
+<pre class="programlisting">
+using doxygen : [<span class="optional"><em class="replaceable"><code>name</code></em></span>] ;
+</pre>
+<p>
+          <em class="replaceable"><code>name</code></em> is the doxygen command.
+          If it is not specified, it will be found in the PATH.
+          </p>
+<p>The doxygen module depends on the boostbook module when
+          generating BoostBook XML.
+          </p>
+<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">doxygen:param</code></span></dt>
+<dd><p>All the values of <code class="literal">doxygen:param</code>
+                 are added to the doxyfile.</p></dd>
+<dt><span class="term"><code class="literal">prefix</code></span></dt>
+<dd><p>Specifies the common prefix of all headers
+                when generating BoostBook XML.  Everything before
+                this will be stripped off.
+                </p></dd>
+<dt><span class="term"><code class="literal">reftitle</code></span></dt>
+<dd><p>Specifies the title of the library-reference section,
+                when generating BoostBook XML.</p></dd>
+<dt><span class="term"><code class="literal">doxygen:xml-imagedir</code></span></dt>
+<dd>
+<p>When generating BoostBook XML, specifies the
+                directory in which to place the images generated
+                from LaTex formulae.</p>
+<div class="warning"><table border="0" summary="Warning">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td>
+<th align="left">Warning</th>
+</tr>
+<tr><td align="left" valign="top"><p>The path is interpreted relative to the
+                current working directory, not relative to the Jamfile.
+                This is necessary to match the behavior of BoostBook.
+                </p></td></tr>
+</table></div>
+</dd>
+</dl></div>
+<p>The doxygen module defines a rule for creating a target
+          following the common syntax.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><code class="literal">doxygen</code></span></dt>
+<dd>
+<pre class="programlisting">
+rule doxygen ( target : sources * : requirements * : default-build * : usage-requirements * )
+</pre>
+<p>Creates a doxygen target.  If the target name
+                ends with .html, then this will generate an html
+                directory.  Otherwise it will generate BoostBook XML.
+                </p>
+</dd>
+</dl></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.doc.quickbook"></a>quickbook</h5></div></div></div>
+<a class="indexterm" name="id3905432"></a><p>The quickbook module provides a generator to convert from
+          Quickbook to BoostBook XML.</p>
+<p>To use quickbook, you first need to configure it using the following syntax:</p>
+<pre class="programlisting">
+using quickbook : [<span class="optional"><em class="replaceable"><code>command</code></em></span>] ;
+</pre>
+<p>
+          <em class="replaceable"><code>command</code></em> is the quickbook executable.
+          If it is not specified, Boost.Build will compile it from source.
+          If it is unable to find the source it will search for a quickbook
+          executable in PATH.
+          </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.tools.doc.fop"></a>fop</h5></div></div></div>
+<a class="indexterm" name="id3905480"></a><p>The fop module provides generators to convert from
+          XSL formatting objects to Postscript and PDF.</p>
+<p>To use fop, you first need to configure it using the following syntax:</p>
+<pre class="programlisting">
+using fop : [<span class="optional"><em class="replaceable"><code>fop-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>java-home</code></em></span>] : [<span class="optional"><em class="replaceable"><code>java</code></em></span>] ;
+</pre>
+<p>
+          <em class="replaceable"><code>fop-command</code></em> is the command to run fop.
+          If it is not specified, Boost.Build will search for it in PATH and
+          FOP_HOME.
+          </p>
+<p>
+          Either <em class="replaceable"><code>java-home</code></em> or
+          <em class="replaceable"><code>java</code></em>
+          can be used to specify where to find java.
+          </p>
+</div>
+</div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.reference.buildprocess"></a>Build process</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="reference.html#bbv2.reference.buildprocess.alternatives">Alternative selection</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.buildprocess.common">Determining common properties</a></span></dt>
+</dl></div>
+<p>The general overview of the build process was given in the
+      <a class="link" href="overview.html#bbv2.overview.build_process" title="The Build Process">user documentation</a>.
+      This section provides additional details, and some specific rules.
+    </p>
+<p>To recap, building a target with specific properties includes the
+      following steps:
+      </p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem"><p>applying default build,</p></li>
+<li class="listitem"><p>selecting the main target alternative to use,
+          </p></li>
+<li class="listitem"><p>determining "common" properties,</p></li>
+<li class="listitem"><p>building targets referred by the sources list and
+            dependency properties,</p></li>
+<li class="listitem"><p>adding the usage requirements produces when building
+            dependencies to the "common" properties,</p></li>
+<li class="listitem"><p>building the target using generators,</p></li>
+<li class="listitem"><p>computing the usage requirements to be returned.</p></li>
+</ol></div>
+<p>
+    </p>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.reference.buildprocess.alternatives"></a>Alternative selection</h4></div></div></div>
+<p>When there are several alternatives, one of them must be
+        selected. The process is as follows:</p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem">
+            For each alternative <span class="emphasis"><em>condition</em></span> is defined as
+            the set of base properties in requirements. [Note: it might be
+            better to specify the condition explicitly, as in conditional
+            requirements].
+          </li>
+<li class="listitem">
+            An alternative is viable only if all properties in condition
+            are present in build request.
+          </li>
+<li class="listitem">
+            If there's one viable alternative, it's choosen. Otherwise,
+            an attempt is made to find one best alternative. An alternative
+            a is better than another alternative b, iff the set of properties
+            in b's condition is a strict subset of the set of properities of
+            'a's condition. If there's one viable alternative, which is
+            better than all others, it's selected. Otherwise, an error is
+            reported.
+          </li>
+</ol></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.reference.buildprocess.common"></a>Determining common properties</h4></div></div></div>
+<p>The "common" properties is a somewhat artificial term. Those are
+        the intermediate property set from which both the build request for
+        dependencies and properties for building the target are derived.
+      </p>
+<p>Since default build and alternatives are already handled, we have
+        only two inputs: build requests and requirements. Here are the rules
+        about common properties.
+      </p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem"><p>Non-free feature can have only one
+            value</p></li>
+<li class="listitem"><p>A non-conditional property in requirement in always
+            present in common properties.</p></li>
+<li class="listitem"><p>A property in build request is present in
+            common properties, unless (2) tells otherwise.</p></li>
+<li class="listitem"><p>If either build request, or requirements (non-conditional
+            or conditional) include an expandable property (either composite,
+            or property with specified subfeature value), the behaviour is
+            equivalent to explicitly adding all expanded properties to build
+            request or requirements.</p></li>
+<li class="listitem"><p>If requirements include a conditional property, and
+            condiiton of this property is true in context of common
+            properties, then the conditional property should be in common
+            properties as well.</p></li>
+<li class="listitem"><p>If no value for a feature is given by other rules
+            here, it has default value in common properties.</p></li>
+</ol></div>
+<p>Those rules are declarative, they don't specify how to compute the
+        common properties. However, they provide enough information for the
+        user. The important point is the handling of conditional
+        requirements. The condition can be satisfied either by property in
+        build request, by non-conditional requirements, or even by another
+        conditional property. For example, the following example works as
+        expected:
+</p>
+<pre class="programlisting">
+exe a : a.cpp
+      : &lt;toolset&gt;gcc:&lt;variant&gt;release
+        &lt;variant&gt;release:&lt;define&gt;FOO ;
+</pre>
+<p>
+      </p>
+</div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.reference.definitions"></a>Definitions</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="reference.html#bbv2.reference.features">Features and properties</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.variants">Build Variants</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.variants.proprefine">Property refinement</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.variants.propcond">Conditional properties</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.ids">Target identifiers and references</a></span></dt>
+</dl></div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.reference.features"></a>Features and properties</h4></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="reference.html#bbv2.reference.features.validity">Property Validity</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.features.attributes">Feature Attributes</a></span></dt>
+<dt><span class="section"><a href="reference.html#bbv2.reference.features.declaration">Feature Declaration</a></span></dt>
+</dl></div>
+<p>A <span class="emphasis"><em>feature</em></span> is a normalized (toolset-independent)
+        aspect of a build configuration, such as whether inlining is
+        enabled. Feature names may not contain the '<code class="literal">&gt;</code>'
+        character.</p>
+<p>Each feature in a build configuration has one or more
+        associated <span class="emphasis"><em>value</em></span>s. Feature values for non-free features
+        may not contain the '<code class="literal">&lt;</code>', '<code class="literal">:</code>', or
+        '<code class="literal">=</code>' characters. Feature values for free features may not
+        contain the '<code class="literal">&lt;</code>' character.</p>
+<p>A <span class="emphasis"><em>property</em></span> is a (feature,value) pair, expressed as
+        &lt;feature&gt;value.</p>
+<p>A <span class="emphasis"><em>subfeature</em></span> is a feature that only exists in the
+        presence of its parent feature, and whose identity can be derived
+        (in the context of its parent) from its value. A subfeature's
+        parent can never be another subfeature. Thus, features and their
+        subfeatures form a two-level hierarchy.</p>
+<p>A <span class="emphasis"><em>value-string</em></span> for a feature <span class="bold"><strong>F</strong></span> is a string of
+        the form
+        <code class="literal">value-subvalue1-subvalue2</code>...<code class="literal">-subvalueN</code>, where
+        <code class="literal">value</code> is a legal value for <span class="bold"><strong>F</strong></span> and
+        <code class="literal">subvalue1</code>...<code class="literal">subvalueN</code> are legal values of some
+        of <span class="bold"><strong>F</strong></span>'s subfeatures. For example, the properties
+        <code class="literal">&lt;toolset&gt;gcc &lt;toolset-version&gt;3.0.1</code> can be
+        expressed more conscisely using a value-string, as
+        <code class="literal">&lt;toolset&gt;gcc-3.0.1</code>.</p>
+<p>A <span class="emphasis"><em>property set</em></span> is a set of properties (i.e. a
+        collection without duplicates), for instance:
+        <code class="literal">&lt;toolset&gt;gcc &lt;runtime-link&gt;static</code>.</p>
+<p>A <span class="emphasis"><em>property path</em></span> is a property set whose elements have
+        been joined into a single string separated by slashes. A property
+        path representation of the previous example would be
+        <code class="literal">&lt;toolset&gt;gcc/&lt;runtime-link&gt;static</code>.</p>
+<p>A <span class="emphasis"><em>build specification</em></span> is a property set that fully
+        describes the set of features used to build a target.</p>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.features.validity"></a>Property Validity</h5></div></div></div>
+<p>
+          For <a class="link" href="reference.html#bbv2.reference.features.attributes.free">free</a>
+            features, all values are valid. For all other features,
+          the valid values are explicitly specified, and the build
+          system will report an error for the use of an invalid
+          feature-value. Subproperty validity may be restricted so
+          that certain values are valid only in the presence of
+          certain other subproperties. For example, it is possible
+          to specify that the <code class="computeroutput">&lt;gcc-target&gt;mingw</code>
+          property is only valid in the presence of
+          <code class="computeroutput">&lt;gcc-version&gt;2.95.2</code>.
+        </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.features.attributes"></a>Feature Attributes</h5></div></div></div>
+<p>Each feature has a collection of zero or more of the following
+          attributes. Feature attributes are low-level descriptions of how the
+          build system should interpret a feature's values when they appear in
+          a build request. We also refer to the attributes of properties, so
+          that an <span class="emphasis"><em>incidental</em></span> property, for example, is
+          one whose feature has the <span class="emphasis"><em>incidental</em></span>
+          attribute.</p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+<p><span class="emphasis"><em>incidental</em></span></p>
+<p>Incidental features are assumed not to affect build
+              products at all. As a consequence, the build system may use
+              the same file for targets whose build specification differs
+              only in incidental features. A feature that controls a
+              compiler's warning level is one example of a likely
+              incidental feature.</p>
+<p>Non-incidental features are assumed to affect build
+              products, so the files for targets whose build specification
+              differs in non-incidental features are placed in different
+              directories as described in "target paths" below. [ where? ]
+            </p>
+</li>
+<li class="listitem">
+<p>
+              <a name="bbv2.reference.features.attributes.propagated"></a>
+              <span class="emphasis"><em>propagated</em></span>
+            </p>
+<p>Features of this kind are
+              propagated to dependencies. That is, if a <a class="link" href="overview.html#bbv2.overview.targets.main">main target</a> is built using a
+              propagated
+              property, the build systems attempts to use the same property
+              when building any of its dependencies as part of that main
+              target. For instance, when an optimized exectuable is
+              requested, one usually wants it to be linked with optimized
+              libraries. Thus, the <code class="literal">&lt;optimization&gt;</code> feature is
+              propagated.</p>
+</li>
+<li class="listitem">
+<p>
+              <a name="bbv2.reference.features.attributes.free"></a>
+              <span class="emphasis"><em>free</em></span>
+            </p>
+<p>Most features have a finite set of allowed values, and can
+              only take on a single value from that set in a given build
+              specification. Free features, on the other hand, can have
+              several values at a time and each value can be an arbitrary
+              string. For example, it is possible to have several
+              preprocessor symbols defined simultaneously:</p>
+<pre class="programlisting">
+&lt;define&gt;NDEBUG=1 &lt;define&gt;HAS_CONFIG_H=1
+</pre>
+</li>
+<li class="listitem">
+<p><span class="emphasis"><em>optional</em></span></p>
+<p>An optional feature is a feature that is not required to
+              appear in a build specification. Every non-optional non-free
+              feature has a default value that is used when a value for
+              the feature is not otherwise specified, either in a target's
+              requirements or in the user's build request. [A feature's
+              default value is given by the first value listed in the
+              feature's declaration. -- move this elsewhere - dwa]</p>
+</li>
+<li class="listitem">
+<p><span class="emphasis"><em>symmetric</em></span></p>
+<p>A symmetric feature's default value is not automatically
+              included in <a class="link" href="reference.html#bbv2.reference.variants" title="Build Variants">build variants</a>.  Normally
+              a feature only generates a subvariant directory when its
+              value differs from the value specified by the build variant,
+              leading to an assymmetric subvariant directory structure for
+              certain values of the feature. A symmetric feature, when
+              relevant to the toolset, always generates a corresponding
+              subvariant directory.</p>
+</li>
+<li class="listitem">
+<p><span class="emphasis"><em>path</em></span></p>
+<p>The value of a path feature specifies a path. The path is
+              treated as relative to the directory of Jamfile where path
+              feature is used and is translated appropriately by the build
+              system when the build is invoked from a different
+              directory</p>
+</li>
+<li class="listitem">
+<p><span class="emphasis"><em>implicit</em></span></p>
+<p>Values of implicit features alone identify the feature.
+              For example, a user is not required to write
+              "&lt;toolset&gt;gcc", but can simply write "gcc". Implicit
+              feature names also don't appear in variant paths, although
+              the values do. Thus: bin/gcc/... as opposed to
+              bin/toolset-gcc/.... There should typically be only a few
+              such features, to avoid possible name clashes.</p>
+</li>
+<li class="listitem">
+<p><span class="emphasis"><em>composite</em></span></p>
+<p>Composite features actually correspond to groups of
+              properties. For example, a build variant is a composite
+              feature. When generating targets from a set of build
+              properties, composite features are recursively expanded and
+              <span class="emphasis"><em>added</em></span> to the build property set, so rules can find
+              them if necessary. Non-composite non-free features override
+              components of composite features in a build property set.</p>
+</li>
+<li class="listitem">
+<p><span class="emphasis"><em>dependency</em></span></p>
+<p>The value of a dependency feature is a target reference.
+              When used for building of a main target, the value of
+              dependency feature is treated as additional dependency.</p>
+<p>For example, dependency features allow to state that
+              library A depends on library B. As the result, whenever an
+              application will link to A, it will also link to B.
+              Specifying B as dependency of A is different from adding B to
+              the sources of A. </p>
+</li>
+</ul></div>
+<p>Features that are neither free nor incidental are called
+          <span class="emphasis"><em>base</em></span> features.</p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="bbv2.reference.features.declaration"></a>Feature Declaration</h5></div></div></div>
+<p>The low-level feature declaration interface is the
+          <code class="literal">feature</code> rule from the
+          <code class="literal">feature</code> module:
+
+</p>
+<pre class="programlisting">
+rule feature ( name : allowed-values * : attributes * )
+</pre>
+<p>
+
+          A feature's allowed-values may be extended with the
+          <code class="computeroutput">feature.extend</code> rule.
+        </p>
+</div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.reference.variants"></a>Build Variants</h4></div></div></div>
+<p>
+        A build variant, or (simply variant) is a special kind of composite
+        feature that automatically incorporates the default values of
+        features that . Typically you'll want at least two separate
+        variants: one for debugging, and one for your release code. [
+        Volodya says: "Yea, we'd need to mention that it's a composite
+        feature and describe how they are declared, in pacticular that
+        default values of non-optional features are incorporated into
+        build variant automagically. Also, do we wan't some variant
+        inheritance/extension/templates. I don't remember how it works in
+        V1, so can't document this for V2.". Will clean up soon -DWA ]
+      </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.reference.variants.proprefine"></a>Property refinement</h4></div></div></div>
+<p>When a target with certain properties is requested, and that
+        target requires some set of properties, it is needed to find the
+        set of properties to use for building. This process is called
+        <span class="emphasis"><em>property refinement</em></span> and is performed by these rules</p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem">
+            Each property in the required set is added to the original
+            property set
+          </li>
+<li class="listitem">
+            If the original property set includes property with a different
+            value of non free feature, that property is removed.
+          </li>
+</ol></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.reference.variants.propcond"></a>Conditional properties</h4></div></div></div>
+<p>Sometime it's desirable to apply certain requirements only for
+        a specific combination of other properties. For example, one of
+        compilers that you use issues a pointless warning that you want to
+        suppress by passing a command line option to it. You would not
+        want to pass that option to other compilers. Conditional
+        properties allow you to do just that. Their syntax is:</p>
+<pre class="programlisting">
+        property ( "," property ) * ":" property
+      </pre>
+<p>
+        For example, the problem above would be solved by:
+
+</p>
+<pre class="programlisting">
+exe hello : hello.cpp : &lt;toolset&gt;yfc:&lt;cxxflags&gt;-disable-pointless-warning ;
+</pre>
+<p>
+      </p>
+<p>The syntax also allows several properties in the condition, for
+        example:
+</p>
+<pre class="programlisting">
+exe hello : hello.cpp : &lt;os&gt;NT,&lt;toolset&gt;gcc:&lt;link&gt;static ;
+</pre>
+<p>
+      </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.reference.ids"></a>Target identifiers and references</h4></div></div></div>
+<p><span class="emphasis"><em>Target identifier</em></span> is used to denote a
+        target. The syntax is:</p>
+<pre class="programlisting">
+target-id -&gt; (project-id | target-name | file-name )
+              | (project-id | directory-name) "//" target-name
+project-id -&gt; path
+target-name -&gt; path
+file-name -&gt; path
+directory-name -&gt; path
+</pre>
+<p>
+        This grammar allows some elements to be recognized as either
+
+        </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+              project id (at this point, all project ids start with slash).
+            </li>
+<li class="listitem">
+              name of target declared in current Jamfile (note that target
+              names may include slash).
+            </li>
+<li class="listitem">
+              a regular file, denoted by absolute name or name relative to
+              project's sources location.
+            </li>
+</ul></div>
+<p>
+
+        To determine the real meaning a check is made if project-id
+        by the specified name exists, and then if main target of that
+        name exists. For example, valid target ids might be:
+
+</p>
+<pre class="screen">
+a                                    -- target in current project
+lib/b.cpp                            -- regular file
+/boost/thread                        -- project "/boost/thread"
+/home/ghost/build/lr_library//parser -- target in specific project
+</pre>
+<p>
+
+      </p>
+<p><span class="bold"><strong>Rationale:</strong></span>Target is separated from project by special
+        separator (not just slash), because:</p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+            It emphasises that projects and targets are different things.
+          </li>
+<li class="listitem">
+            It allows to have main target names with slashes.
+
+            
+          </li>
+</ul></div>
+<p><a name="bbv2.reference.targets.references"></a>
+        <span class="emphasis"><em>Target reference</em></span> is used to
+        specify a source target, and may additionally specify desired
+        properties for that target. It has this syntax:</p>
+<pre class="programlisting">
+target-reference -&gt; target-id [ "/" requested-properties ]
+requested-properties -&gt; property-path
+</pre>
+<p>
+        For example,
+
+        </p>
+<pre class="programlisting">
+          exe compiler : compiler.cpp libs/cmdline/&lt;optimization&gt;space ;
+        </pre>
+<p>
+
+        would cause the version of <code class="literal">cmdline</code> library,
+        optimized for space, to be linked in even if the
+        <code class="literal">compiler</code> executable is build with optimization for
+        speed.
+      </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 &#169; 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="tasks.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="extender.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
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&#160;39.&#160;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 &#8220;Declaring Targets&#8221;</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
+          : &lt;threading&gt;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 &#8220;Installing&#8221;</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 &lt;link&gt; 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 : : &lt;name&gt;z &lt;search&gt;/home/ghost ;
+lib compress : : &lt;file&gt;/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 : : &lt;variant&gt;release &lt;file&gt;/pool/release/a.so ;
+lib a : : &lt;variant&gt;debug &lt;file&gt;/pool/debug/a.so ;
+lib b : : &lt;variant&gt;release &lt;file&gt;/pool/release/b.so ;
+lib b : : &lt;variant&gt;debug &lt;file&gt;/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 : : &lt;name&gt;z ;
+lib gui : : &lt;name&gt;gui ;
+lib db : : &lt;name&gt;db ;
+lib aux : : &lt;name&gt;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 : &lt;name&gt;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 : &lt;use&gt;b : : &lt;library&gt;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 : : : &lt;include&gt;. ;
+</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 : &lt;link&gt;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 : : : :  &lt;include&gt;/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 : : : &lt;include&gt;/library/include1 ;
+lib library2 : library2.cpp : : : &lt;include&gt;/library/include2 ;
+alias static_libraries : library1 library2 : &lt;link&gt;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 : &lt;location&gt;/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 :
+    &lt;variant&gt;release:&lt;location&gt;dist/release
+    &lt;variant&gt;debug:&lt;location&gt;dist/debug ;
+install dist2 : hello helpers : &lt;location&gt;$(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
+           : &lt;install-dependencies&gt;on &lt;install-type&gt;EXE
+             &lt;install-type&gt;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">&lt;install-source-root&gt;</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
+    : &lt;location&gt;/tmp &lt;install-source-root&gt;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>&lt;testing.launcher&gt;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 &#8220;Extender Manual&#8221;</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 $(&lt;) $(&gt;)
+}
+</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 &#8220;Boost.Jam Language&#8221;</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 &#8212; 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">&lt;implicit-dependency&gt;
+      </code> [ link ] feature must be used, for example:
+</p>
+<pre class="programlisting">
+lib parser : parser.y ;
+exe app : app.cpp : &lt;implicit-dependency&gt;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 &#8220;Configuration&#8221;</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 &#8220;64-bit support&#8221;</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 &#8220;Feature Attributes&#8221;</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 &#169; 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>
diff --git a/doc/html/bbv2/tutorial.html b/doc/html/bbv2/tutorial.html
new file mode 100755
index 0000000000..7273c7eaf0
--- /dev/null
+++ b/doc/html/bbv2/tutorial.html
@@ -0,0 +1,736 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Tutorial</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&#160;39.&#160;Boost.Build V2 User Manual">
+<link rel="prev" href="installation.html" title="Installation">
+<link rel="next" href="overview.html" title="Overview">
+</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="installation.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../bbv2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="overview.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="bbv2.tutorial"></a>Tutorial</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.hello">Hello, world</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.properties">Properties</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.hierarchy">Project Hierarchies</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.libs">Dependent Targets</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.linkage">Static and shared libaries</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.conditions">Conditions and alternatives</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.prebuilt">Prebuilt targets</a></span></dt>
+</dl></div>
+<p>
+    This section will guide you though the most basic features of Boost.Build
+    V2. We will start with the &#8220;Hello, world&#8221; example, learn how
+    to use libraries, and finish with testing and installing features.
+  </p>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.tutorial.hello"></a>Hello, world</h3></div></div></div>
+<p>
+      The simplest project that Boost.Build can construct is stored in
+      <code class="filename">example/hello/</code> directory. The project is described by
+      a file called <code class="filename">Jamroot</code> that contains:
+
+</p>
+<pre class="programlisting">
+exe hello : hello.cpp ;
+</pre>
+<p>
+
+      Even with this simple setup, you can do some interesting things. First of
+      all, just invoking <span class="command"><strong>bjam</strong></span> will build the <code class="filename">hello
+      </code> executable by compiling and linking <code class="filename">hello.cpp
+      </code>. By default, debug variant is built. Now, to build the release
+      variant of <code class="filename">hello</code>, invoke
+
+</p>
+<pre class="screen">
+bjam release
+</pre>
+<p>
+
+      Note that debug and release variants are created in different directories,
+      so you can switch between variants or even build multiple variants at
+      once, without any unnecessary recompilation. Let us extend the example by
+      adding another line to our project's <code class="filename">Jamroot</code>:
+
+</p>
+<pre class="programlisting">
+exe hello2 : hello.cpp ;
+</pre>
+<p>
+
+      Now let us build both the debug and release variants of our project again:
+
+</p>
+<pre class="screen">
+bjam debug release
+</pre>
+<p>
+
+      Note that two variants of <code class="filename">hello2</code> are linked. Since we
+      have already built both variants of <code class="filename">hello</code>, hello.cpp
+      will not be recompiled; instead the existing object files will just be
+      linked into the corresponding variants of <code class="filename">hello2</code>. Now
+      let us remove all the built products:
+
+</p>
+<pre class="screen">
+bjam --clean debug release
+</pre>
+<p>
+
+      It is also possible to build or clean specific targets. The following two
+      commands, respectively, build or clean only the debug version of
+      <code class="filename">hello2</code>.
+
+</p>
+<pre class="screen">
+bjam hello2
+bjam --clean hello2
+</pre>
+<p>
+    </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.tutorial.properties"></a>Properties</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.properties.requirements">Build Requests and Target Requirements</a></span></dt>
+<dt><span class="section"><a href="tutorial.html#bbv2.tutorial.properties.project_attributes">Project Attributes</a></span></dt>
+</dl></div>
+<p>
+      To portably represent aspects of target configuration such as
+      debug and release variants, or single- and multi-threaded
+      builds, Boost.Build uses <em class="firstterm">features</em> with
+      associated <em class="firstterm">values</em>.  For
+      example, the <code class="computeroutput">debug-symbols</code> feature can have a value of <code class="computeroutput">on</code> or
+      <code class="computeroutput">off</code>.  A <em class="firstterm">property</em> is just a (feature,
+      value) pair.  When a user initiates a build, Boost.Build
+      automatically translates the requested properties into appropriate
+      command-line flags for invoking toolset components like compilers
+      and linkers.
+    </p>
+<p>
+      There are many built-in features that can be combined to
+      produce arbitrary build configurations.  The following command
+      builds the project's <code class="computeroutput">release</code> variant with inlining
+      disabled and debug symbols enabled:
+</p>
+<pre class="screen">
+bjam release inlining=off debug-symbols=on
+</pre>
+<p>
+    </p>
+<p>
+      Properties on the command-line are specified with the syntax:
+
+</p>
+<pre class="screen">
+<em class="replaceable"><code>feature-name</code></em>=<em class="replaceable"><code>feature-value</code></em>
+</pre>
+<p>
+    </p>
+<p>
+      The <code class="option">release</code> and <code class="option">debug</code> that we have seen
+      in <span class="command"><strong>bjam</strong></span> invocations are just a shorthand way to specify
+      values of the <code class="varname">variant</code> feature.  For example, the
+      command above could also have been written this way:
+
+      </p>
+<pre class="screen">
+bjam variant=release inlining=off debug-symbols=on
+      </pre>
+<p>
+    </p>
+<p>
+      <code class="varname">variant</code> is so commonly-used that it has been given
+      special status as an <em class="firstterm">implicit</em> feature&#8212;
+      Boost.Build will deduce the its identity just from the name of one of its
+      values.
+    </p>
+<p>
+      A complete description of features can be found in <a class="xref" href="reference.html#bbv2.reference.features" title="Features and properties">the section called &#8220;Features and properties&#8221;</a>.
+    </p>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.tutorial.properties.requirements"></a>Build Requests and Target Requirements</h4></div></div></div>
+<p>
+        The set of properties specified on the command line constitute
+        a <em class="firstterm">build request</em>&#8212;a description of
+        the desired properties for building the requested targets (or,
+        if no targets were explicitly requested, the project in the
+        current directory). The <span class="emphasis"><em>actual</em></span>
+        properties used for building targets are typically a
+        combination of the build request and properties derived from
+        the project's <code class="filename">Jamroot</code> (and its other
+        Jamfiles, as described in <a class="xref" href="tutorial.html#bbv2.tutorial.hierarchy" title="Project Hierarchies">the section called &#8220;Project Hierarchies&#8221;</a>). For example, the
+        locations of <code class="computeroutput">#include</code>d header files are normally
+        not specified on the command-line, but described in
+        Jamfiles as <em class="firstterm">target
+        requirements</em> and automatically combined with the
+        build request for those targets. Multithread-enabled
+        compilation is another example of a typical target
+        requirement. The Jamfile fragment below
+        illustrates how these requirements might be specified.
+      </p>
+<pre class="programlisting">
+exe hello
+    : hello.cpp
+    : &lt;include&gt;boost &lt;threading&gt;multi
+    ;
+</pre>
+<p>
+        When <code class="filename">hello</code> is built, the two requirements specified
+        above will always be present. If the build request given on the
+        <span class="command"><strong>bjam</strong></span> command-line explictly contradicts a target's
+        requirements, the target requirements usually override (or, in the case
+        of &#8220;free&#8221;&#8221; features like
+        <code class="varname">&lt;include&gt;</code>,
+        <sup>[<a name="id3892911" href="#ftn.id3892911" class="footnote">10</a>]</sup>
+        augments) the build request.
+      </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>
+          The value of the <code class="varname">&lt;include&gt;</code> feature is
+          relative to the location of <code class="filename">Jamroot</code> where it is
+          used.
+        </p></td></tr>
+</table></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="bbv2.tutorial.properties.project_attributes"></a>Project Attributes</h4></div></div></div>
+<p>
+        If we want the same requirements for our other target, <code class="filename">hello2
+        </code>, we could simply duplicate them. However, as projects grow,
+        that approach leads to a great deal of repeated boilerplate in Jamfiles.
+
+        Fortunately, there's a better way. Each project can specify a set of
+        <em class="firstterm">attributes</em>, including requirements:
+
+</p>
+<pre class="programlisting">
+project
+    : requirements &lt;include&gt;/home/ghost/Work/boost &lt;threading&gt;multi
+    ;
+
+exe hello : hello.cpp ;
+exe hello2 : hello.cpp ;</pre>
+<p>
+
+        The effect would be as if we specified the same requirement for both
+        <code class="filename">hello</code> and <code class="filename">hello2</code>.
+      </p>
+</div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.tutorial.hierarchy"></a>Project Hierarchies</h3></div></div></div>
+<p>
+      So far we have only considered examples with one project &#8212;a. with
+      one user-written Boost.Jam file, <code class="filename">Jamroot</code>). A typical
+      large codebase would be composed of many projects organized into a tree.
+      The top of the tree is called the <em class="firstterm">project root</em>.
+      Every subproject is defined by a file called <code class="filename">Jamfile</code>
+      in a descendant directory of the project root. The parent project of a
+      subproject is defined by the nearest <code class="filename">Jamfile</code> or
+      <code class="filename">Jamroot</code> file in an ancestor directory. For example,
+      in the following directory layout:
+
+</p>
+<pre class="screen">
+top/
+  |
+  +-- Jamroot
+  |
+  +-- app/
+  |    |
+  |    +-- Jamfile
+  |    `-- app.cpp
+  |
+  `-- util/
+       |
+       +-- foo/
+       .    |
+       .    +-- Jamfile
+       .    `-- bar.cpp
+</pre>
+<p>
+
+      the project root is <code class="filename">top/</code>. The projects in
+      <code class="filename">top/app/</code> and <code class="filename">top/util/foo/</code> are
+      immediate children of the root project.
+
+      </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 we refer to a &#8220;Jamfile,&#8221; set in normal
+          type, we mean a file called either
+          <code class="filename">Jamfile</code> or
+          <code class="filename">Jamroot</code>.  When we need to be more
+          specific, the filename will be set as
+          &#8220;<code class="filename">Jamfile</code>&#8221; or
+          &#8220;<code class="filename">Jamroot</code>.&#8221;
+        </p></td></tr>
+</table></div>
+<p>
+    </p>
+<p>
+      Projects inherit all attributes (such as requirements)
+      from their parents.  Inherited requirements are combined with
+      any requirements specified by the subproject.
+      For example, if <code class="filename">top/Jamroot</code> has
+
+</p>
+<pre class="programlisting">
+&lt;include&gt;/home/ghost/local
+</pre>
+<p>
+
+      in its requirements, then all of its subprojects will have it
+      in their requirements, too.  Of course, any project can add
+      include paths to those specified by its parents. <sup>[<a name="id3893145" href="#ftn.id3893145" class="footnote">11</a>]</sup>
+    More details can be found in
+      <a class="xref" href="overview.html#bbv2.overview.projects" title="Projects">the section called &#8220;Projects&#8221;</a>.
+    </p>
+<p>
+      Invoking <span class="command"><strong>bjam</strong></span> without explicitly specifying
+      any targets on the command line builds the project rooted in the
+      current directory.  Building a project does not automatically
+      cause its subprojects to be built unless the parent project's
+      Jamfile explicitly requests it. In our example,
+      <code class="filename">top/Jamroot</code> might contain:
+
+</p>
+<pre class="programlisting">
+build-project app ;
+</pre>
+<p>
+
+      which would cause the project in <code class="filename">top/app/</code>
+      to be built whenever the project in <code class="filename">top/</code> is
+      built. However, targets in <code class="filename">top/util/foo/</code>
+      will be built only if they are needed by targets in
+      <code class="filename">top/</code> or <code class="filename">top/app/</code>.
+    </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.tutorial.libs"></a>Dependent Targets</h3></div></div></div>
+<p>
+      When a building a target <code class="filename">X</code> depends on first
+      building another target <code class="filename">Y</code> (such as a
+      library that must be linked with <em class="firstterm">X</em>),
+      <code class="filename">Y</code> is called a
+      <em class="firstterm">dependency</em> of <code class="filename">X</code> and
+      <code class="filename">X</code> is termed a
+      <em class="firstterm">dependent</em> of <code class="filename">Y</code>.
+    </p>
+<p>To get a feeling of target dependencies, let's continue the
+      above example and see how <code class="filename">top/app/Jamfile</code> can
+      use libraries from <code class="filename">top/util/foo</code>.  If
+      <code class="filename">top/util/foo/Jamfile</code> contains
+
+</p>
+<pre class="programlisting">
+lib bar : bar.cpp ;
+</pre>
+<p>
+
+      then to use this library in <code class="filename">top/app/Jamfile</code>, we can
+      write:
+
+</p>
+<pre class="programlisting">
+exe app : app.cpp ../util/foo//bar ;
+</pre>
+<p>
+
+      While <code class="computeroutput">app.cpp</code> refers to a regular source file,
+      <code class="computeroutput">../util/foo//bar</code> is a reference to another target:
+      a library <code class="filename">bar</code> declared in the Jamfile at
+      <code class="filename">../util/foo</code>.
+    </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>Some other build system have special syntax for listing dependent
+      libraries, for example <code class="varname">LIBS</code> variable. In Boost.Build,
+      you just add the library to the list of sources.
+      </p></td></tr>
+</table></div>
+<p>Suppose we build <code class="filename">app</code> with:
+    </p>
+<pre class="screen">
+bjam app optimization=full define=USE_ASM
+    </pre>
+<p>
+    Which properties will be used to build <code class="computeroutput">foo</code>? The answer is
+    that some features are
+    <em class="firstterm">propagated</em>&#8212;Boost.Build attempts to use
+    dependencies with the same value of propagated features. The
+    <code class="varname">&lt;optimization&gt;</code> feature is propagated, so both
+    <code class="filename">app</code> and <code class="filename">foo</code> will be compiled
+    with full optimization. But <code class="varname">&lt;define&gt;</code> is not
+    propagated: its value will be added as-is to the compiler flags for
+    <code class="filename">a.cpp</code>, but won't affect <code class="filename">foo</code>.
+    </p>
+<p>
+      Let's improve this project further. The library probably has some headers
+      that must be used when compiling <code class="filename">app.cpp</code>. We could
+      manually add the necessary <code class="computeroutput">#include</code> paths to <code class="filename">app
+      </code>'s requirements as values of the <code class="varname">&lt;include&gt;
+      </code> feature, but then this work will be repeated for all programs
+      that use <code class="filename">foo</code>. A better solution is to modify
+      <code class="filename">util/foo/Jamfile</code> in this way:
+
+      </p>
+<pre class="programlisting">
+project
+    : usage-requirements &lt;include&gt;.
+    ;
+
+lib foo : foo.cpp ;</pre>
+<p>
+
+      Usage requirements are applied not to the target being declared but to its
+      dependants. In this case, <code class="literal">&lt;include&gt;.</code> will be
+      applied to all targets that directly depend on <code class="filename">foo</code>.
+    </p>
+<p>
+      Another improvement is using symbolic identifiers to refer to the library,
+      as opposed to <code class="filename">Jamfile</code> location. In a large project, a
+      library can be used by many targets, and if they all use <code class="filename">Jamfile
+      </code> location, a change in directory organization entails much
+      work. The solution is to use project ids&#8212;symbolic names not tied to
+      directory layout. First, we need to assign a project id by adding this
+      code to <code class="filename">Jamroot</code>:
+    </p>
+<pre class="programlisting">
+use-project /library-example/foo : util/foo ;</pre>
+<p>
+      Second, we modify <code class="filename">app/Jamfile</code> to use the project id:
+      </p>
+<pre class="programlisting">
+exe app : app.cpp /library-example/foo//bar ;</pre>
+<p>
+
+      The <code class="filename">/library-example/foo//bar</code> syntax is used to refer
+      to the target <code class="filename">bar</code> in the project with id <code class="filename">
+      /library-example/foo</code>. We've achieved our goal&#8212;if the
+      library is moved to a different directory, only <code class="filename">Jamroot
+      </code> must be modified. Note that project ids are global&#8212;two
+      Jamfiles are not allowed to assign the same project id to different
+      directories.
+    </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>If you want all applications in some project to link to a certain
+        library, you can avoid having to specify it directly the sources of
+        every target by using the <code class="varname">&lt;library&gt;</code> property.
+        For example, if <code class="filename">/boost/filesystem//fs</code> should be
+        linked to all applications in your project, you can add
+        <code class="computeroutput">&lt;library&gt;/boost/filesystem//fs</code> to the project's
+        requirements, like this:
+      </p>
+<pre class="programlisting">
+project
+   : requirements &lt;library&gt;/boost/filesystem//fs
+   ;</pre>
+</td></tr>
+</table></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.tutorial.linkage"></a>Static and shared libaries</h3></div></div></div>
+<p>
+      Libraries can be either <span class="emphasis"><em>static</em></span>, which means they are
+      included in executable files that use them, or <span class="emphasis"><em>shared</em></span>
+      (a.k.a. <span class="emphasis"><em>dynamic</em></span>), which are only referred to from
+      executables, and must be available at run time. Boost.Build can create and
+      use both kinds.
+    </p>
+<p>
+      The kind of library produced from a <code class="computeroutput">lib</code> target is determined
+      by the value of the <code class="varname">link</code> feature. Default value is
+      <code class="literal">shared</code>, and to build a static library, the value should
+      be <code class="literal">static</code>. You can request a static build either on the
+      command line:
+      </p>
+<pre class="programlisting">bjam link=static</pre>
+<p>
+      or in the library's requirements:
+      </p>
+<pre class="programlisting">lib l : l.cpp : &lt;link&gt;static ;</pre>
+<p>
+    </p>
+<p>
+      We can also use the <code class="varname">&lt;link&gt;</code> property to express
+      linking requirements on a per-target basis. For example, if a particular
+      executable can be correctly built only with the static version of a
+      library, we can qualify the executable's <a class="link" href="reference.html#bbv2.reference.targets.references">target reference</a> to the
+      library as follows:
+
+
+
+      </p>
+<pre class="programlisting">
+exe important : main.cpp helpers/&lt;link&gt;static ;</pre>
+<p>
+
+      No matter what arguments are specified on the <span class="command"><strong>bjam</strong></span>
+      command line, <code class="filename">important</code> will only be linked with the
+      static version of <code class="filename">helpers</code>.
+    </p>
+<p>
+      Specifying properties in target references is especially useful if you use
+      a library defined in some other project (one you can't change) but you
+      still want static (or dynamic) linking to that library in all cases. If
+      that library is used by many targets, you <span class="emphasis"><em>could</em></span> use
+      target references everywhere:
+
+      </p>
+<pre class="programlisting">
+exe e1 : e1.cpp /other_project//bar/&lt;link&gt;static ;
+exe e10 : e10.cpp /other_project//bar/&lt;link&gt;static ;</pre>
+<p>
+
+      but that's far from being convenient. A better approach is to introduce a
+      level of indirection. Create a local <span class="type">alias</span> target that refers
+      to the static (or dynamic) version of <code class="filename">foo</code>:
+
+      </p>
+<pre class="programlisting">
+alias foo : /other_project//bar/&lt;link&gt;static ;
+exe e1 : e1.cpp foo ;
+exe e10 : e10.cpp foo ;</pre>
+<p>
+
+      The <a class="link" href="tasks.html#bbv2.tasks.alias" title="Alias"><code class="computeroutput">alias</code>
+      </a> rule is specifically used to rename a reference to a target and
+      possibly change the properties.
+
+      
+    </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>
+        When one library uses another, you put the second library in the source
+        list of the first. For example:
+        </p>
+<pre class="programlisting">
+lib utils : utils.cpp /boost/filesystem//fs ;
+lib core : core.cpp utils ;
+exe app : app.cpp core ;</pre>
+<p>
+        This works no matter what kind of linking is used. When <code class="filename">core
+        </code> is built as a shared library, it is linked directly into
+        <code class="filename">utils</code>. Static libraries can't link to other
+        libraries, so when <code class="filename">core</code> is built as a static
+        library, its dependency on <code class="filename">utils</code> is passed along to
+        <code class="filename">core</code>'s dependents, causing <code class="filename">app</code>
+        to be linked with both <code class="filename">core</code> and <code class="filename">utils
+        </code>.
+      </p>
+</td></tr>
+</table></div>
+<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>
+        (Note for non-UNIX system). Typically, shared libraries must be
+        installed to a directory in the dynamic linker's search path. Otherwise,
+        applications that use shared libraries can't be started. On Windows, the
+        dynamic linker's search path is given by the <code class="envar">PATH</code>
+        environment variable. This restriction is lifted when you use
+        Boost.Build testing facilities&#8212;the <code class="envar">PATH</code> variable
+        will be automatically adjusted before running the executable.
+        
+      </p></td></tr>
+</table></div>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.tutorial.conditions"></a>Conditions and alternatives</h3></div></div></div>
+<p>
+      Sometimes, particular relationships need to be maintained among a target's
+      build properties. For example, you might want to set specific <code class="computeroutput">
+      #define</code> when a library is built as shared, or when a target's
+      <code class="computeroutput">release</code> variant is built. This can be achieved using
+      <em class="firstterm">conditional requirements</em>.
+
+      </p>
+<pre class="programlisting">
+lib network : network.cpp
+    : <span class="bold"><strong>&lt;link&gt;shared:&lt;define&gt;NEWORK_LIB_SHARED</strong></span>
+     &lt;variant&gt;release:&lt;define&gt;EXTRA_FAST
+    ;</pre>
+<p>
+
+      In the example above, whenever <code class="filename">network</code> is built with
+      <code class="computeroutput">&lt;link&gt;shared</code>, <code class="computeroutput">&lt;define&gt;NEWORK_LIB_SHARED
+      </code> will be in its properties, too. Also, whenever its release variant
+      is built, <code class="computeroutput">&lt;define&gt;EXTRA_FAST</code> will appear in its
+      properties.
+    </p>
+<p>
+      Sometimes the ways a target is built are so different that describing them
+      using conditional requirements would be hard. For example, imagine that a
+      library actually uses different source files depending on the toolset used
+      to build it. We can express this situation using <em class="firstterm">target
+      alternatives</em>:
+      </p>
+<pre class="programlisting">
+lib demangler : dummy_demangler.cpp ;                      # alternative 1
+lib demangler : demangler_gcc.cpp : &lt;toolset&gt;gcc ;   # alternative 2
+lib demangler : demangler_msvc.cpp : &lt;toolset&gt;msvc ; # alternative 3</pre>
+<p>
+      When building <code class="filename">demangler</code>, Boost.Build will compare
+      requirements for each alternative with build properties to find the best
+      match. For example, when building with <code class="computeroutput">&lt;toolset&gt;gcc</code>
+      alternative 2, will be selected, and when building with
+      <code class="computeroutput">&lt;toolset&gt;msvc</code> alternative 3 will be selected. In all
+      other cases, the most generic alternative 1 will be built.
+    </p>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bbv2.tutorial.prebuilt"></a>Prebuilt targets</h3></div></div></div>
+<p>
+      To link to libraries whose build instructions aren't given in a Jamfile,
+      you need to create <code class="computeroutput">lib</code> targets with an appropriate
+      <code class="varname">file</code> property.  Target alternatives can be used to
+      associate multiple library files with a single conceptual target. For
+      example:
+      </p>
+<pre class="programlisting">
+# util/lib2/Jamfile
+lib lib2
+    :
+    : &lt;file&gt;lib2_release.a &lt;variant&gt;release
+    ;
+
+lib lib2
+    :
+    : &lt;file&gt;lib2_debug.a &lt;variant&gt;debug
+    ;</pre>
+<p>
+
+      This example defines two alternatives for <code class="filename">lib2</code>, and
+      for each one names a prebuilt file.  Naturally, there are no sources.
+      Instead, the <code class="varname">&lt;file&gt;</code> feature is used to specify
+      the file name.
+    </p>
+<p>
+      Once a prebuilt target has been declared, it can be used just like any
+      other target:
+
+      </p>
+<pre class="programlisting">
+exe app : app.cpp ../util/lib2//lib2 ;</pre>
+<p>
+
+      As with any target, the alternative selected depends on the properties
+      propagated from <code class="filename">lib2</code>'s dependants. If we build the
+      release and debug versions of <code class="filename">app</code> will be linked
+      with <code class="filename">lib2_release.a</code> and <code class="filename">lib2_debug.a
+      </code>, respectively.
+    </p>
+<p>
+      System libraries&#8212;those that are automatically found by the toolset
+      by searching through some set of predetermined paths&#8212;should be
+      declared almost like regular ones:
+
+      </p>
+<pre class="programlisting">
+lib pythonlib : : &lt;name&gt;python22 ;</pre>
+<p>
+
+      We again don't specify any sources, but give a <code class="varname">name</code>
+      that should be passed to the compiler. If the gcc toolset were used to
+      link an executable target to <code class="filename">pythonlib</code>,
+      <code class="option">-lpython22</code> would appear in the command line (other
+      compilers may use different options).
+    </p>
+<p>
+      We can also specify where the toolset should look for the library:
+
+      </p>
+<pre class="programlisting">
+lib pythonlib : : &lt;name&gt;python22 &lt;search&gt;/opt/lib ;</pre>
+<p>
+
+      And, of course, target alternatives can be used in the usual way:
+
+      </p>
+<pre class="programlisting">
+lib pythonlib : : &lt;name&gt;python22 &lt;variant&gt;release ;
+lib pythonlib : : &lt;name&gt;python22_d &lt;variant&gt;debug ;</pre>
+<p>
+    </p>
+<p>
+      A more advanced use of prebuilt targets is described in <a class="xref" href="faq.html#bbv2.recipies.site-config" title="Targets in site-config.jam">the section called &#8220;Targets in site-config.jam&#8221;</a>.
+    </p>
+</div>
+<div class="footnotes">
+<br><hr width="100" align="left">
+<div class="footnote"><p><sup>[<a id="ftn.id3892911" href="#id3892911" class="para">10</a>] </sup>
+             See <a class="xref" href="reference.html#bbv2.reference.features.attributes" title="Feature Attributes">the section called &#8220;Feature Attributes&#8221;</a>
+          </p></div>
+<div class="footnote"><p><sup>[<a id="ftn.id3893145" href="#id3893145" class="para">11</a>] </sup>Many
+      features will be overridden,
+      rather than added-to, in subprojects.  See <a class="xref" href="reference.html#bbv2.reference.features.attributes" title="Feature Attributes">the section called &#8220;Feature Attributes&#8221;</a> for more
+      information</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 &#169; 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="installation.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../bbv2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="overview.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
author	Anas Nashif <anas.nashif@intel.com>	2012-10-30 12:57:26 -0700
committer	Anas Nashif <anas.nashif@intel.com>	2012-10-30 12:57:26 -0700
commit	1a78a62555be32868418fe52f8e330c9d0f95d5a (patch)
tree	d3765a80e7d3b9640ec2e930743630cd6b9fce2b /doc/html/bbv2
download	boost-1a78a62555be32868418fe52f8e330c9d0f95d5a.tar.gz boost-1a78a62555be32868418fe52f8e330c9d0f95d5a.tar.bz2 boost-1a78a62555be32868418fe52f8e330c9d0f95d5a.zip