<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">

  <chapter id="bbv2.advanced">
    <title>User documentation</title>

  <para>This section will provide the information necessary to create your own
  projects using Boost.Build. The information provided here is relatively
  high-level, and <xref linkend="bbv2.reference"/> as
  well as the on-line help system must be used to obtain
  low-level documentation (see <xref linkend=
  "bbv2.reference.init.options.help"/>).</para>

  <para>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 <command>bjam</command> on the command line is:
      <orderedlist>
        <listitem>
          <para>Boost.Jam tries to find Boost.Build and loads the top-level
          module. The exact process is described in <xref
          linkend="bbv2.reference.init"/></para>
        </listitem>
        <listitem>
          <para>The top-level module loads user-defined configuration
          files, <filename>user-config.jam</filename> and <filename>site-config.jam</filename>, which define
          available toolsets.</para>
        </listitem>
        <listitem>
          <para>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.</para>
        </listitem>
        <listitem>
          <para>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 commands.</para>
        </listitem>        
      </orderedlist>
    </para>

    <para>So, to be able to successfully use Boost.Build, you need to know only
      three things:
      <itemizedlist>
        <listitem>
          <para><link linkend="bbv2.advanced.configuration">
              How to configure Boost.Build</link></para>
        </listitem>
        <listitem>
          <para><link linkend="bbv2.advanced.jamfiles">
              How to write Jamfiles</link></para>
        </listitem>
        <listitem>
          <para><link linkend="bbv2.advanced.build_process">
              How the build process works</link></para>
        </listitem>
        <listitem>
          <para>Some Basics about the Boost.Jam language. See the
          <ulink 
          url="http://www.boost.org/tools/build/jam_src/index.html#jam_fundamentals">Boost.Jam</ulink>
          and <ulink
          url="http://www.boost.org/tools/build/jam_src/jam.html">Classic
          Jam</ulink> documentation.
          <!-- Something better than this is desperately needed; the
               tutorial at least should clarify that whitespace is
               significant and we shouldn't get any further than the
               beginning of this document before briefly explaining
               Jam's data and procedural model, rule
               signatures, and Boost.Build modules -->
          </para>
        </listitem>
      </itemizedlist>
    </para>
    

  <section id="bbv2.advanced.configuration">
    <title>Configuration</title>

    <para>The Boost.Build configuration is specified in the file
    <filename>user-config.jam</filename>. You can edit the one that comes with Boost.Build, or
    <!-- You can't tell people that without telling them where to find it! -->
    create a copy in your home directory and edit that. (See the <link
    linkend="bbv2.reference.init.config">reference</link> for the exact search
    paths.) The primary function of that file is to declare which compilers
    and other tools are available. The simplest syntax to configure a tool is:
<programlisting>
using <replaceable>tool-name</replaceable> ;        
</programlisting>
      The <functionname>using</functionname> rule is given a name of tool, and will make that tool
      available to Boost.Build. For example, <code>using gcc ;</code> will make the gcc compiler
      available.      
    </para>

    <para>
      Since nothing but a tool name is specified, Boost.Build will
      pick some default settings.  For example, it will use the
      <command>gcc</command> executable found in the
      <envar>PATH</envar>, or look in some known installation
      locations. In most cases, this strategy works automatically. In
      case you have several versions of a compiler, it's installed in
      some unusual location, or you need to tweak its configuration,
      you'll need to pass additional parameters to the
      <functionname>using</functionname> rule.  The parameters to
      <functionname>using</functionname> can be different for each
      tool.  You can obtain specific documentation for any tool's
      configuration parameters by invoking
<programlisting>
bjam --help <replaceable>tool-name</replaceable>.init         
</programlisting>
    </para>
    <para>
      That said, for all the compiler toolsets Boost.Build supports
      out-of-the-box, the list of parameters to
      <functionname>using</functionname> is the same: <parameter
      class="function">toolset-name</parameter>, <parameter
      class="function">version</parameter>, <parameter
      class="function">invocation-command</parameter>, and <parameter
      class="function">options</parameter>.
      <!-- the previous text here was really confusing -->
    </para>

    <para>The <parameter class="function">version</parameter>
    parameter identifies the toolset version, in case you have
    several installed. It can have any form you like, but
    it's recommended that you use a numeric identifier like
    <literal>7.1</literal>.
    </para>

    <para>
      The <parameter class="function">invocation-command</parameter>
      parameter is the command that must be executed to run the
      compiler. This parameter can usually be omitted if the compiler
      executable
      <itemizedlist>
      <listitem><para>has its &#x201C;usual
      name&#x201D; and is in the <envar>PATH</envar>,
      or</para></listitem>
      <listitem><para>was installed in a standard
      &#x201C;installation directory&#x201D;,
      or</para></listitem>

      <listitem><para>can be found through a global mechanism like the
      Windows registry.</para></listitem>
      </itemizedlist>

      For example:
<programlisting>
using msvc : 7.1 ;
using gcc ;
</programlisting>
If the compiler can be found in the <envar>PATH</envar> but only by a
nonstandard name, you can just supply that name:
<programlisting>
using gcc : : g++-3.2 ;
</programlisting>
Otherwise, it might be necessary to supply the complete path to the
compiler executable:
<programlisting>
using msvc : : Z:/Programs/Microsoft Visual Studio/vc98/bin/cl ;
</programlisting>
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.
<!-- Will 

          using msvc : : foo/bar/vcvars32.bat && foo/bar/baz/cl ;

         work?  If not we should clarify what we really mean by "invocation command."
-->
    </para>

    <para>To configure several versions of a toolset, simply invoke
    the <functionname>using</functionname> rule multiple times:
<programlisting>
using gcc : 3.3 ;
using gcc : 3.4 : g++-3.4 ;
using gcc : 3.2 : g++-3.2 ;
</programlisting>
        Note that in the first call to
        <functionname>using</functionname>, the compiler found in the
        <envar>PATH</envar> will be used, and there's no need to
        explicitly specify the command.
    </para>

    <para>As shown above, both the <parameter
    class="function">version</parameter> and <parameter
    class="function">invocation-command</parameter> parameters are
    optional, but there's an important restriction: if you configure
    the same toolset more than once, you must pass the <parameter
    class="function">version</parameter>
    parameter every time. For example, the following is not allowed:
<programlisting>
using gcc ;
using gcc : 3.4 : g++-3.4 ;
</programlisting>
      because the first <functionname>using</functionname> call does
      not specify a <parameter class="function">version</parameter>.
    </para>

    <para>The <parameter class="function">options</parameter>
    parameter is used to fine-tune the configuration. All of
    Boost.Build's standard compiler toolsets accept properties of the
    four builtin features <varname>cflags</varname>,
    <varname>cxxflags</varname>, <varname>compileflags</varname> and
    <varname>linkflags</varname> as <parameter
    class="function">options</parameter> specifying flags that will be
    always passed to the corresponding tools. Values of the
    <varname>cflags</varname> feature are passed directly to the C
    compiler, values of the <varname>cxxflags</varname> feature are
    passed directly to the C++ compiler, and values of the
    <varname>compileflags</varname> feature are passed to both. For
    example, to configure a <command>gcc</command> toolset so that it
    always generates 64-bit code you could write:
<programlisting>
using gcc : 3.4 : : &lt;compileflags&gt;-m64 &lt;linkflags&gt;-m64 ;
</programlisting>
    </para>
                
    </section>

  <section id="bbv2.advanced.jamfiles">
    <title>Writing Jamfiles</title>

    <section id="bbv2.advanced.overview">
      <title>Overview</title>

      <para>Jamfiles are the thing that is most important to the user,
      <!-- Semantics-free, and wrong.  Many things are more important to the user -->
      bacause they declare the targets that should be built. 
      <!-- The reader already knows that -->
      Jamfiles are also used for organizing targets&#x2014;
      <!-- Practically redundant with "Jamfiles... declare targets" -->
      each Jamfile is a separate project
      <!-- Okay, there's some content! -->
      that can be built independently from the other projects.
      <!-- :( Practically redundant with "each Jamfile is a separate project." -->
      </para>

      <para>Jamfiles mostly contain calls to Boost.Build functions that do
        all the work, specifically:
        <!-- it's too late to start saying "functions."  You have to
             use "rules" everwhere or it will just get confusing. -->
        <itemizedlist>
          <listitem>
            <para><link linkend="bbv2.advanced.targets">declare main
                targets</link></para>
          </listitem>
          <listitem>
            <para><link
            linkend="bbv2.advanced.projects">define
            project properties</link></para>
          </listitem>
          <listitem>
            <para><link linkend="bbv2.advanced.other-rules">do various other
            things</link></para> 
            <!-- Semantics-free again. -->
          </listitem>
        </itemizedlist>
      </para>

      <!-- Don't expect those links to do anything useful, even for
           someone reading the HTML.  A list of items where all of the
           *real* content is only available through links is often
           worse than nothing.  Have you ever tried to read NG
           postings by Alexander Terekhov? The whole list is pretty
           useless.  Consider scratching or rewriting the entire section. -->

      <!-- That's a *lot* of flotsam below.  If it's not good enough
           to go in the output users see, just delete it. -->
      <!-- ======================================================== -->
<!--
      <para>The most fundemental entity in Boost.Build is <emphasis>main
          target</emphasis>. This is object that user want to construct from
        sources and keep up to date with regard to those sources. Typical
        examples of main targets are executable files and libraries.</para>
      
      <para>Main targets are grouped in <emphasis>projects</emphasis>. Their main
        purpose is organization: related targets placed in one project,
        can then be built together, or share some definitions.</para>
      
      <para>Main targets and projects are created as the result of reading
        one or several Jamfiles. Each Jamfile is a file written in
        Boost.Jam interpreted language, and typically contains calls to
        functions provided by Boost.Build, which create main targets of
        needed type, declare project attributes and access other
        projects. The full list of functions provided by Boost.Build is
        described <link linkend="bbv2.advanced.builtins">below</link>.
        Of course, user can create his own functions, or it can directly
        access Boost.Build internals from Jamfile, if builtin facilities are
        not sufficient.</para>

  <para>Each main target, or project can be built in a number of ways,
  say with optimization or without. We'll call such entities
  "metatargets". To make Boost.Build produce any real targets, user
  issues <link linkend="bbv2.reference.buildreq">build request</link>,
  which specifies metatargets to be built, and properties to be
  used.</para>

  <para>The <emphasis>properties</emphasis> are just (name,value) pairs that
  describe various aspects of constructed objects, for example:</para>
  <programlisting>
&lt;optimization&gt;full &lt;inlining&gt;off
</programlisting>

  <para>Given the built request, Boost.Build figures out the targets
  needed for requested metatargets with requested properties, how
  they can be created, and whether exising files can be reused. It
  finally issues command to create needed files, automatically
  converting properties into appropricate command line options.</para>
-->
      <!-- ======================================================== -->
    </section>

      <!-- Delete this flotsam too! -->
      <!-- ======================================================== -->
<!--
    <section id="bbv2.advanced.roadmap">
      <title>Your first project and roadmap</title>


  <para>Creating your first project requires three steps:</para>

  <orderedlist>
    <listitem><simpara>Create an empty file called "Jamfile"</simpara></listitem>

    <listitem>
      <simpara>
        Create an empty file called "project-root.jam"
      </simpara>
    </listitem>

    <listitem>
      <para>Either set your <envar>BOOST_BUILD_PATH</envar> environment
    variant to Boost.Build root, or create a "boost-build.jam" file
    with the following content:

<programlisting>
boost-build /path/to/boost.build ;
</programlisting>

      </para>
    </listitem>
  </orderedlist>

  <para>After that, you can run the "bjam" command in the directory
  where you've created the files. Surely, it won't do anything, but
  it will run without error, at least. Your next steps might
  be:</para>

  <orderedlist>
    <listitem>
      <simpara>
        Adding new main targets to the "Jamfile" file. The basic
    syntax for declaring a main target is described <link linkend=
    "bbv2.advanced.targets">below</link>, and all builtin functions for
    declaring main targets are <link linkend=
    "bbv2.advanced.builtins.targets">listed</link>.
      </simpara>
    </listitem>

    <listitem>
      <simpara>
        Creating subprojects. Create a directory, put new Jamfile
    there, and move some main targets to that Jamfile, or declare
    new ones. The <link linkend="bbv2.advanced.projects">projects
    reference</link> will help with this part.
      </simpara>
    </listitem>

    <listitem>
      <simpara>
        Customizing Boost.Build for your needs. You might have
    additional tools you want to run, or just want different
    extension for some file. The <link linkend="bbv2.extending">extender manual</ulink> is waiting for
    you.
      </simpara>
    </listitem>
  </orderedlist>

    </section>
-->
    <section id="bbv2.advanced.targets">
      <title>Main targets</title>

      <para id="bbv2.advanced.targets.main">
        A <firstterm>Main target</firstterm> is a user-defined named
        entity that can be built, for example an <!-- a named --> executable file.
        <!-- We already said it was named in the very same sentence.
             Is there even such a thing as an unnamed executable?? -->
        Declaring a main target is usually done using one of the main
        target rules described in <xref linkend=
        "bbv2.advanced.builtins.targets"/>.  The user can also declare
        custom main target rules as shown in <xref
        linkend="bbv2.extending.rules"/>.
</para>
      
      <para>Most main target rules in Boost.Build can be invoked with
      a common syntax:</para>

      <!-- I think we maybe ought to be talking about a common
           _signature_ here, having already explained Boost.Jam function
           signatures at the beginning of this chapter.  Then we could show 
           ( main-target-name : sources * : requirements * : default-build * : usage-requirements * )
           instead.  More precise.

           Also, I suggest replacing "default-build" by "default-properties" everywhere.
      -->

<anchor id="bbv2.main-target-rule-syntax"/>
<programlisting>
<replaceable>rule-name</replaceable>&#x2002;<replaceable>main-target-name</replaceable>
    : <replaceable>sources...</replaceable>
    : <replaceable>requirements...</replaceable> 
    : <replaceable>default-build...</replaceable>
    : <replaceable>usage-requirements...</replaceable>
    ;
</programlisting>

      <itemizedlist>
        <listitem>
          <simpara>
            <parameter>main-target-name</parameter> 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
            (&#x2018;<code>-</code>&#x2019;), and underscores
            (&#x2018;<code>_</code>&#x2019;).
          </simpara>
        </listitem>
        
        <listitem>
          <simpara>
            <parameter>sources</parameter> is the list of source files and other main
            targets that must be combined. 
          </simpara>
        </listitem>
        
        <listitem>
          <simpara>
            <parameter>requirements</parameter> is the list of properties that must always
            be present when this main target is built.
          </simpara>
        </listitem>
        
        <listitem>
          <simpara>
            <parameter>default-build</parameter> 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 propogation from a dependent target.
          </simpara>
        </listitem>
        
        <listitem>
          <simpara>
            <parameter>usage-requirements</parameter> is the list of properties that will be
            propagated to all main targets that use this one, i.e. to all its
            dependents.
          </simpara>
        </listitem>
      </itemizedlist>

      <para>          
        Some main target rules have a shorter list of parameters;
        consult their documentation for details.
      </para>
      <para>Note that the actual requirements, default-build and
      usage-requirements attributes for a target are obtained by
      combining the explicitly specified ones with those specified for
      the project where a target is declared.
      <!-- Need an xref here to the place where the combination is
           described in detail -->
      </para>
      
      <para>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
      <functionname>glob</functionname> rule. Here are two examples:
<programlisting>
exe a : a.cpp ;           # a.cpp is the only source file
exe b : [ glob *.cpp ] ;  # all .cpp files in this directory are sources 
</programlisting>
        Unless you specify a files with absolute path, the name is
        considered relative to the source directory -- which is typically
        the directory where the Jamfile is located, but can be changed as
        described in <xref linkend=
          "bbv2.advanced.projects.attributes.projectrule"/>.
      </para>
      
      <para>
        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 need to <!-- targets don't "specify"
        anything -->be qualified with<!----> a directory or a symbolic
        project name. For example:
<programlisting>
lib helper : helper.cpp ;
exe a : a.cpp helper ;
exe b : b.cpp ..//utils ;<!-- It's unclear at this point whether that's a directory path or project ID.  Clarify -->
exe c : c.cpp /boost/program_options//program_options ;
</programlisting>
        The first exe uses the library defined in the same
        project. The second one uses some target (most likely library)
        defined by Jamfile one level higher. Finally, the third target
        uses some <ulink url="http://boost.org">C++ Boost</ulink>
        library, referring to it by its absolute symbolic name. More
        information about it <!-- What is "it?"  Used here, "it" must
        refer to "some C++ Boost library" or "its absolute symbolic
        name -->can be found in <xref
        linkend="bbv2.tutorial.libs"/> and <xref
        linkend="bbv2.reference.ids"/>.
      </para>

<!--
      <section id="bbv2.advanced.targets.requirements">        
        <title>Requirements and usage-requirements</title>
        
        <para>The requirements argument specify what properties are absolutely
        necessary for this main target. 
      </section>
-->
      <para>Requirements are the properties that should always be present when
        building a target. Typically, they are includes and defines:
<programlisting>
exe hello : hello.cpp : &lt;include&gt;/opt/boost &lt;define&gt;MY_DEBUG ;
</programlisting>
        In special circumstances, 
        <!-- What sort of "special circumstances?"  This is vague and unclear -->
        other properties can be used, 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
<programlisting>
lib util : util.cpp : &lt;link&gt;static ;
obj main : main.cpp : &lt;optimization&gt;off ;
</programlisting>                
      </para>

      <para>Sometimes requirements are necessary only for a specific
      compiler or build variant.  <link
      linkend="bbv2.reference.variants.propcond">Conditional
      properties</link> can be used in that case: 
      <!-- This phrasing is a bit awkward.  Hasn't this been covered
           more thoroughly in the tutorial? -->
<programlisting>
lib util : util.cpp : &lt;toolset&gt;msvc:&lt;link&gt;static ;
</programlisting>
        <!-- "In means when whenever" is nonsense -->
        Whenever <code>&lt;toolset&gt;msvc</code> property is
        in build properties, the <code>&lt;link&gt;static</code> property will
        be included as well. Conditional requirements can be &#x201C;chained&#x201D;:
<programlisting>
lib util : util.cpp : &lt;toolset&gt;msvc:&lt;link&gt;static 
                      &lt;link&gt;static:&lt;define&gt;STATIC_LINK ;
</programlisting>
        will set of static link
        <!-- ??? Even if you remove "of," what does it mean to "set static link?" -->
        and the <code>STATIC_LINK</code> define on the
        <code>msvc</code> toolset.
        <!-- really, on the **toolset** ?? I don't think so!-->
      </para>

      <para>The <varname>default-build</varname> parameter
      <!-- You can't say "attribute" here because you use it with an
           entirely different meaning in the next section! -->
      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:
<programlisting>
exe hello : hello.cpp : : &lt;threading&gt;multi ;
</programlisting>
        would build a multi-threaded target in unless the user
        explicitly requests a single-threaded version. The difference between
        requirements and default-build is that requirements cannot be
        overriden in any way.<!-- Is that still true?  I thought
        requirements could be overridden by explicit request as
        propagated from dependents -->
      </para>

      <para>A target of the same name can be declared several times,  in which
        case each declaration is called an
        <firstterm>alternative</firstterm>. When the target is built, one of
        the alternatives will be selected and used.  Alternatives need not be
        defined by the same main target rule.  For example,
<programlisting>
lib helpers : helpers.hpp ;                 # a header-only library
alias helpers : helpers.lib : &lt;toolset&gt;msvc ; # except on msvc
</programlisting>
<!-- Above, is "helpers.lib" a target reference or a file reference?
     If the former, how does the extension get added?  If the latter,
     is it a realistic case?  What about:

  obj helpers : helpers.cpp
  lib helpers : helpers.cpp msvc_helper.cpp : <toolset>msvc ;

??
 -->
      </para>

      <para>The actual commands used to build any given main target can differ greatly from
        platform to platform. For example, you might have different lists
        of sources for different compilers, or different options for those
        compilers. Two approaches to this are explained in the 
        <link linkend="bbv2.tutorial.conditions">tutorial</link>.
        <!-- Doing an inferior job of covering this material here is
             bad.  This chapter should be merged with the tutorial.

             Also, AFAICT only one approach is explained in the
             referenced section.  Another approach that might have
             been covered would be to combine the <source> property,
             which is covered in a different section of the tutorial,
             with conditional properties. -->
      </para>

      <para>Sometimes a main target is really needed only by some other main
        target. For example, a rule that declares a test-suite uses a main
        target 
        <!-- how can a rule "use a main target??" -->
        that represent test, but those main targets are rarely needed
        by themselves.
        <!-- what does that mean??  This is completely opaque to me.
             IMO this whole paragraph should be dropped -->
      </para>

      <para>It is possible to declare a target inline, i.e. the "sources"
        parameter may include calls to other main rules. For example:</para>

<programlisting>
exe hello : hello.cpp 
    [ obj helpers : helpers.cpp : &lt;optimization&gt;off ] ;
</programlisting>

      <para>
        Will cause "helpers.cpp" to be always compiled without
        optimization. 
        <!-- This bit was unintelligible until I reread it about 10 times

        It's possible to request main targets declared inline, but
        since they are considered local, they are renamed to
        "parent-main-target_name..main-target-name"
        -->
        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>bjam hello..helpers</code>.
      </para>

    </section>

    <section id="bbv2.advanced.projects">
      <title>Projects</title>

      <para>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. 
      </para>

      <para>Projects are named using the
      <functionname>project</functionname> rule, which has the
      following syntax:
<programlisting>
project <replaceable>id</replaceable> : <replaceable>attributes</replaceable> ;
</programlisting>
        Here, <replaceable>attributes</replaceable> is a sequence of
        rule arguments, each of which begins with an attribute-name
        and is followed by any number of build properties.  <!--
        The previous description was completely wrong and confusing -->
        The list
        of attribute names along with its handling is also shown in
        the table below. For example, it is possible to write:
<programlisting>
project tennis 
    : requirements &lt;threading&gt;multi 
    : default-build release
    ;
</programlisting>   
      </para>

      <para>The possible attributes are listed below.</para>

      <para><emphasis>Project id</emphasis> 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". <link linkend=
          "bbv2.reference.ids">Target references</link> make use of project ids to
        specify a target.</para>
        <!-- 
             This is actually spelled "project-id," isn't it?  You
             have to fix all of these and use a code font.  Also below
             in the table.
        -->

      <para><emphasis>Source location</emphasis> specifies the directory where sources
        for the project are located.</para>

      <para><emphasis>Project requirements</emphasis> are requirements that apply to
        all the targets in the projects as well as all subprojects.</para>

      <para><emphasis>Default build</emphasis> is the build request that should be
        used when no build request is specified explicitly.</para>
        <!-- 
             This contradicts your earlier description of default
             build and I believe it is incorrect.  Specifying a build
             request does not neccessarily render default build
             ineffective, because it may cover different features.
             This description is repeated too many times in the
             documentation; you almost *had* to get it wrong once.
        -->

      <para id="bbv2.advanced.projects.attributes.projectrule">
        The default values for those attributes are
        given in the table below.

        <table>
          <title/>
          <tgroup cols="4">
            <thead>
              <row>
                <entry>Attribute</entry>
                
                <entry>Name for the 'project' rule</entry>
                <!-- Incorrectly gives the impression that Project IDs
                     (for example) are not called “Project ID” except
                     in the context of the 'project' rule.  BTW, use
                     <function>...</function>, not single quotes -->
                
                <entry>Default value</entry>
                
                <entry>Handling by the 'project' rule</entry>
              </row>
            </thead>
            
            <tbody>
              
              <row>
                <entry>Project id</entry>
                
                <entry>none</entry>
                
                <entry>none</entry>
                
                <entry>Assigned from the first parameter of the 'project' rule.
                  It is assumed to denote absolute project id.</entry>
              </row>
              
              <row>
                <entry>Source location</entry>
                
                <entry><literal>source-location</literal></entry>
                
                <entry>The location of jamfile for the project</entry>
                
                <entry>Sets to the passed value</entry>
              </row>
              
              <row>
                <entry>Requirements</entry>
                
                <entry><literal>requirements</literal></entry>
                
                <entry>The parent's requirements</entry>
                
                <entry>The parent's requirements are refined with the passed
                  requirement and the result is used as the project
                  requirements.</entry>
              </row>
              
              <row>
                <entry>Default build</entry>
                
                <entry><literal>default-build</literal></entry>
                
                <entry>none</entry>
                
                <entry>Sets to the passed value</entry>
              </row>
              
              <row>
                <entry>Build directory</entry>
                
                <entry><literal>build-dir</literal></entry>
                
                <entry>Empty if the parent has no build directory set.
                Otherwise, the parent's build directory with with the
                relative path from parent to the current project
                appended to it.
                </entry>
                
                <entry>Sets to the passed value, interpreted as relative to the
                  project's location.</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        </para>

      <para>Besides defining projects and main targets, Jamfiles
      commonly invoke utility rules such as
      <functionname>constant</functionname> and
      <functionname>path-constant</functionname>, which inject a
      specified Boost.Jam variable setting into this project's Jamfile
      module and those of all its subprojects.  See <xref
      linkend="bbv2.advanced.other-rules"/> for a complete description
      of these utility rules.  Jamfiles are regular Boost.Jam source
      files and Boost.Build modules, so naturally they can contain any kind of Boost.Jam code,
      including rule definitions.
      <!-- I improved that sentence, but I don't think it belongs
           here.  I suggest you strike it. -->
      </para>

      <para>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 <filename>Jamroot</filename> rather than
      <filename>Jamfile</filename>.  When loading a project,
      Boost.Build looks for either <filename>Jamroot</filename> or
      <code>Jamfile</code>.  They are handled indentically, except
      that if the file is called <filename>Jamroot</filename>, the
      search for a parent project is not performed.
      </para>

      <para>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 <link
      linkend="bbv2.advanced.projects.relationships.useprojectrule"><functionname>use-project</functionname></link>,
      or a target reference, no specific order should be assumed.
      </para>

      <note>
        <para>Giving the root project the special name
        &#x201C;<filename>Jamroot</filename>&#x201D; ensures that
        Boost.Build won't misinterpret a directory above it as the
        project root just because the directory contains a Jamfile.
        <!-- The logic of the previous reasoning didn't hang together -->
        </para>          
      </note>

      <!-- All this redundancy with the tutorial is bad.  The tutorial
           should just be made into the introductory sections of this
           document, which should be called the "User Guide."  It's
           perfectly appropriate to start a user guide with that kind
           of material. -->
    </section>

    
    <section id="bbv2.advanced.other-rules">
      <title>Jamfile Utility Rules</title>

      <para>The following table describes utility rules that can be
      used in Jamfiles. Detailed information for any of these rules can
      be obtained by running:
<screen>
bjam --help project.<replaceable>rulename</replaceable>
</screen>
      </para>

      <table>
        <title/>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Rule</entry>
              
              <entry>Semantics</entry>
            </row>
          </thead>
          
          <tbody>
            <row>
              <entry><link linkend=
                  "bbv2.advanced.projects.attributes.projectrule">project</link>
              </entry>
              
              <entry>Define this project's symbolic ID or attributes.</entry>
            </row>
            
            <row>
              <entry><link linkend=
                  "bbv2.advanced.projects.relationships.useprojectrule">use-project</link></entry>
              
              <entry>Make another project known so that it can be referred to by symbolic ID.</entry>
            </row>
            
            <row>
              <entry><link linkend=
                  "bbv2.advanced.projects.relationships.buildprojectrule">build-project</link></entry>
              
              <entry>Cause another project to be built when this one is built.</entry>
            </row>
            
            <row>
              <entry><link linkend=
                  "bbv2.reference.buildprocess.explict">explicit</link></entry>
              
              <entry>State that a target should be built only by explicit
                request.</entry>
            </row>
            
            <row>
              <entry>glob</entry>
              
              <entry>Translate a list of shell-style wildcards into a
              corresponding list of files.</entry>
            </row>

            <row>
              <entry>constant</entry>
              
              <entry>Injects a variable setting into this project's
              Jamfile module and those of all its subprojects.</entry>
            </row>

            <row>
              <entry>path-constant</entry>
              
              <entry>Injects a variable set to a path value into
              this project's Jamfile module and those of all its subprojects.
              If the value is a relative path it will be adjusted for
              each subproject so that it refers to the same
              directory.</entry>
            </row>


          </tbody>
        </tgroup>
      </table>
    </section>
      

<!-- STRIKE ALL FLOTSAM!! -->
<!--
      <section id="bbv2.advanced.projects.relationships">
        <title>Project relationship</title>

  <para>There are three kinds of project relationships.</para>

  <para>First is parent-child. This relationship is established
  implicitly: parent directories of a project are searched, and the
  first found Jamfile is assumed to define the parent project. The
  parent-child relationship affects only attribute values for the
  child project.</para>

  <para id="bbv2.advanced.projects.relationships.buildprojectrule">
  Second is build relationship. Some
  project may request to recursively build other projects. Those
  project need not be child projects. The <literal>build-project</literal>
  rule is used for that:</para>
  <programlisting>
    build-project src ;   
</programlisting>

  <para id="bbv2.advanced.projects.relationships.useprojectrule">
  The third kind is the 'use'
  relationship. In means that one project uses targets from
  another. It is possible to just refer to target in other projects
  using target id. However, if target id uses project id, it is
  required that the project id is known. The
  <literal>use-project</literal>
  rule is employed to guarantee that.
  </para>

<programlisting>
use-project ( id : location )
</programlisting>

        <para>
It loads the project at the specified location, which makes
its project id available in the project which invokes the rule. It
is required that the <literal>id</literal> parameter passed to the
<literal>use-project</literal> rule be equal to the id that the loaded
project declared. At this moment, the <literal>id</literal> paremeter
should be absolute project id.
        </para>
      </section>
    </section>

-->
<!-- STRIKE ALL FLOTSAM!! -->
       
  </section>
  
  <section id="bbv2.advanced.build_process">
    <title>The Build Process</title>

    <para>When you've described your targets, you want Boost.Build to run the
      right tools and create the needed targets. 
      <!-- That sentence is awkward and doesn't add much. -->
      This section will describe
      two things: how you specify what to build, and how the main targets are
      actually constructed.
    </para>

    <para>The most important thing to note is that in Boost.Build, unlike
      other build tools, the targets you declare do not correspond to specific
      files. What you declare in a Jamfile is more like a “metatarget.” 
      <!-- Do we need a new word?  We already have “main target.” If
           you're going to introduce “metatarget” you should at least
           tie it together with the main target concept. It's too
           strange to have been saying “main target” all along and now
           suddenly start saying “what you declare in a jamfile” -->
      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,
      <!-- Don't say “of course”—it just makes those not already
           familiar with what you're describing feel stupid. --> 
      producing different files.
    </para>
    <tip>
      <para>
        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. 
      </para>
    </tip>

    <section>
      <title>Build request</title>

      <para>
        The command line specifies which targets to build and with which
        properties. For example:
<programlisting>
bjam app1 lib1//lib1 toolset=gcc variant=debug optimization=full
</programlisting>
        would build two targets, "app1" and "lib1//lib1" with the specified
        properties. You can refer to any targets, using 
        <link linkend="bbv2.reference.ids">target id</link> 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:
<programlisting>
bjam app1 lib1//lib1 gcc debug optimization=full
</programlisting>
        The complete syntax, which has some additional shortcuts, is
        described in <xref linkend="bbv2.reference.commandline"/>.
        <!-- The previous text was unintelligible. Did I guess your meaning? -->
      </para>
    </section>

    <section><title>Building a main target</title>

      <para>When you request, directly or indirectly, a build of a main target
        with specific requirements, the following steps are made. Some brief
        explanation is provided, and more details are given in <xref
        linkend="bbv2.reference.buildprocess"/>.
        <orderedlist>
          
          <listitem><para>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.</para>
          <!--
              Added to what?  Don't say “the build request!” The
              request is what was requested; if its meaning changes
              the reader will be confused.
          -->
          </listitem>
          
          <listitem><para>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.
            </para></listitem>
          
          <listitem><para>Determining "common" properties. 
          <!-- It would be nice to have a better name for this.  But
               even more importantly, unless you say something about
               the reason for choosing whatever term you use, the
               reader is going to wonder what it means. -->
              The build request
              is <link linkend="bbv2.reference.variants.proprefine">refined</link>
              with target's requirements. 
              <!-- It's good that you have the links here and below,
                   but I'm concerned that it doesn't communicate well
                   in print and there's not enough information for the
                   print reader.  Maybe we need separate XSL for PDF
                   printing that generates a readable footnote. -->
              The conditional properties in
              requirements are handled as well. Finally, default values of
              features are added.
            </para></listitem>
          
          <listitem><para>Building targets referred by the sources list and
              dependency properties. The list of sources and the properties
              can refer to other target using <link
              linkend="bbv2.reference.ids">target references</link>. For each
              reference, we take all <link
              linkend="bbv2.reference.features.attributes.propagated">propagated</link>
              properties, refine them by explicit properties specified in the
              target reference, and pass the resulting properties as build
              request to the other target.              
            </para></listitem>
          
          <listitem><para>Adding the usage requirements produced when building
              dependencies to the "common" properties. When dependencies are
              built in the previous step, they return 
              <!-- don't assume reader has a mental model for BB internals! -->
              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.              
            </para></listitem>
          
          <listitem><para>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
              <!-- Was "in." Why are these short and unmistakable
                   words so commonly misspelled? -->
              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.
            </para></listitem>
          
          <listitem><para>Computing the usage requirements to be returned. The
          conditional properties in usage requirements are expanded 
          <!-- what does "expanded" mean? -->
          and the
          result is returned.</para></listitem>
        </orderedlist>        
      </para>
    </section>

    <section><title>Building a project</title>

      <para>Often, a user builds a complete project, not just one main
      target. In fact, invoking <command>bjam</command> without
      arguments
      <!-- do you know the difference between parameters and
           arguments?  I only learned this year -->
      builds the project defined in the current
      directory.</para>

      <para>When a project is built, the build request is passed without
        modification to all main targets in that project.
        <!-- What does it mean to pass a build request to a target?
             -->
        It's is possible to
        prevent implicit building of a target in a project with the
        <code>explicit</code> rule:
<programlisting>
explicit hello_test ;
</programlisting>
        would cause the <code>hello_test</code> target to be built only if
        explicitly requested by the user or by some other target.
      </para>

      <para>The Jamfile for a project can include a number of
      <code>build-project</code> rule calls
      <!-- A comma would only be correct here in German -->
      that specify additional projects
      to be built.
      </para>

    </section>

  </section>

  <section id="bbv2.advanced.builtins.targets">
    <title>Builtin target types</title>

    <!-- Every section must have immediate content, even if it's only
         an introductory sentence or two -->
    <section>
      <title>Programs</title>

      <para>Programs are created using the <code>exe</code> rule, which
        follows the <link linkend="bbv2.main-target-rule-syntax">common
          syntax</link>. For example:
<programlisting>
exe hello : hello.cpp some_library.lib /some_project//library 
          : &lt;threading&gt;multi 
          ;
</programlisting>
        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.
      </para>

      <tip>
        <para>         
          On Windows, if an application uses dynamic libraries, and both
          the application and the libraries are built by Boost.Build, its not
          possible to immediately run the application, because the
          <literal>PATH</literal> environment variable should include the path
          to the libraries. It means you have to either add the paths
          manually, or place the application and the libraries to the same
          directory, for example using the <link linkend="bbv2.builtins.stage">
            stage</link> rule.
        </para>
        <!-- We should be emphasizing the use of the built-in testing
             rules rather than continually discussing these quirks of
             running programs with dynamic libraries. -->
      </tip>
    </section>

    <section>
      <title>Libraries</title>

      <para>Libraries are created using the <code>lib</code> rule, which
        follows the <link linkend="bbv2.main-target-rule-syntax">common
          syntax</link>. For example:
<programlisting>
lib helpers : helpers.cpp : &lt;include&gt;boost : : &lt;include&gt;. ;
</programlisting>
      </para>
      <!-- Add one sentence that says what the above does. -->
      <para>In the most common case, the <code>lib</code> creates a library
        from the specified sources. Depending on the value of
        &lt;link&gt; feature the library will be either static or
        shared. There are two other cases. First is when the library is
        installed somewhere in compiler's search paths, and should be
        searched by the compiler (typically, using the <option>-l</option>
        option). The second case is where the library is available as a 
        prebuilt file and the full path is known.          
        <!-- But the first case is also prebuilt.  This is confusingly phrased. -->
        </para>
      
      <para>
        The syntax for these case is given below:
<programlisting>
lib z : : &lt;name&gt;z &lt;search&gt;/home/ghost ;            
lib compress : : &lt;file&gt;/opt/libs/compress.a ;
</programlisting>
        The <code>name</code> property specifies the name that should be
        passed to the <option>-l</option> option, and the <code>file</code>
        property specifies the file location. The <varname>search</varname> 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
        default compiler paths will be searched.
      </para>

      <para>The difference between using the <varname>file</varname> feature as
        opposed to the <varname>name</varname> feature together with the
        <varname>search</varname> feature is that <varname>file</varname> is more
        precise. A specific file will be used. On the other hand, the
        <varname>search</varname> feature only adds a library path, and the
        <varname>name</varname> feature gives the basic name of the library. The
        search rules are specific to the linker. For example, given these
        definition:
<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 ;
</programlisting>
        It's possible to use release version of <code>a</code> and debug
        version of <code>b</code>. Had we used the <varname>name</varname> and
        <varname>search</varname> features, the linker would always pick either
        release or debug versions.
        <!-- explain -->
      </para>
      
      <para>
        For convenience, the following syntax is allowed:
<programlisting>
lib z ;
lib gui db aux ;
</programlisting>
          and is does exactly the same as:
<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 ;            
</programlisting>
      </para>
          
      <para>When a library uses another library you should put that another
        library in the 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 won't work. For example:
<programlisting>
lib z ;
lib png : z : &lt;name&gt;png ;
</programlisting>
        </para>

      <note>
        <para>When a library (say, <code>a</code>), that has another
          library, (say, <code>b</code>) 
          <!-- how can a library "have" a library? -->
          is linked dynamically, the <code>b</code>
          library will be incorporated 
          <!-- Incorporated?  Be precise. -->
          in <code>a</code>. (If <code>b</code>
          is dynamic library as well, then <code>a</code> will only refer to
          it, and not include any extra code.) 
          <!-- Don't parenthesize a whole sentence. -->
          When the <code>a</code>
          library is linked statically, Boost.Build will assure that all
          executables that link to <code>a</code> will also link to
          <code>b</code>.
        </para>
      </note>
         
      <para>One feature of Boost.Build that is very important for libraries
        is usage requirements. 
        <!-- Rephrase that.  But then, it's much too late for an
             introduction of usage requirements - you've already
             discussed them many times. -->
        For example, if you write:
<programlisting>
lib helpers : helpers.cpp : : : &lt;include&gt;. ;
</programlisting>
        then the compiler include path for all targets that use
        <code>helpers</code> will contain the directory 
        <!-- The rest of this sentence is unintelligible -->
        where the target is defined.path to "helpers.cpp". The user
        only needs to add <code>helpers</code> to the list of sources,
        and needn't consider the requirements its use imposes on a
        dependent target. This feature greatly simplifies Jamfiles.
        <!-- You can't say “allows to”—you need a noun.  This error is
             repeated throughout. -->
      </para>

      <note>
        <para>If you don't want shared libraries to include all libraries
          that are specified in sources (especially statically linked ones),
          you'd need to use the following:
<programlisting>
lib b : a.cpp ;
lib a : a.cpp : &lt;use&gt;b : : &lt;library&gt;b ;
</programlisting>
          This specifies that <code>a</code> uses <code>b</code>, and causes
          all executables that link to <code>a</code> also link to
          <code>b</code>. In this case, even for shared linking, the
          <code>a</code> library won't even refer to <code>b</code>.
        </para>
      </note>
          
    </section>

    <section id="bbv2.builtins.alias">
      <title>Alias</title>

      <para>The <code>alias</code> rule follows the <link
          linkend="bbv2.main-target-rule-syntax">common syntax</link>. For
        example:
<programlisting>
alias core : im reader writer ;
</programlisting>
        will build the sources
        <!-- it's not immediately obvious that there are sources.  Make this more transparent -->
        and return
        <!-- no mental model -->
        the generated source targets
        without modification. 
      </para>

      <para>
        The <functionname>alias</functionname> rule is a convenience tool. If you often build
        the same group of targets at the same time, you can define an alias
        to save typing.        
      </para>

      <para>
        Another use of the <code>alias</code> rule is to change build
        properties. For example, if you always want static linking for a
        specific C++ Boost library, you can write the following:
<programlisting>
alias threads : /boost/thread//boost_thread : &lt;link&gt;static ;
</programlisting>
        and use only the <code>threads</code> alias in your Jamfiles.
        <!-- changed name for clarity -->
      </para>              

      <para>
        You can also specify usage requirements for the
        <code>alias</code> target. If you write the following:
<programlisting>
alias header_only_library : : : :  &lt;include&gt;/usr/include/header_only_library ; 
</programlisting>
        then using <code>header_only_library</code> in sources will only add an
        include path. Also note that when there are some sources, their usage
        requirements are propagated, too. For example:
<programlisting>
lib lib : lib.cpp : : : &lt;include&gt;. ;
alias lib_alias ; <!-- This line can't possibly be correct!?? -->
exe main : main.cpp lib_alias ;
</programlisting>
        will compile <filename>main.cpp</filename> with the additional include.
      </para>
 
    </section>

    <section id="bbv2.builtins.stage">
      <title>Installing</title>

      <para>For installing a built target you should use the
        <code>install</code> rule, which follows the <link
          linkend="bbv2.main-target-rule-syntax">common syntax</link>. For
        example:
<programlisting>
install dist : hello helpers ;
</programlisting>
        will cause the targets <code>hello</code> and <code>helpers</code> to
        be moved to the <filename>dist</filename> directory, relative to
        Jamfile's directory. The directory can
        be changed with the <code>location</code> property:
<programlisting>
install dist : hello helpers : &lt;location&gt;/usr/bin ;
</programlisting>
        While you can achieve the same effect by changing the target name to
        <filename>/usr/bin</filename>, using the <code>location</code>
        property is better, because it allows you to use a memnonic target
        name.
      </para>

      <para>The <code>location</code> property is especially handy when the location
        is not fixed, but depends on build variant or environment variables:
<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) ;
</programlisting> 
        See also <link linkend="bbv2.reference.variants.propcond">conditional
          properties</link> and <link linkend="bbv2.faq.envar">environment variables</link>
      </para>
      
      <para>
        Specifying the names of all libraries to install can be boring. The
        <code>install</code> allows you to specify only the top-level executable
        targets to install, and automatically install all dependencies:
<programlisting>
install dist : hello 
           : &lt;install-dependencies&gt;on &lt;install-type&gt;EXE
             &lt;install-type&gt;LIB
           ;
</programlisting>
        will find all targets that <code>hello</code> depends on, and install
        all of the 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 <link
        linkend="bbv2.builtin.features.use"><code>use</code></link> feature
        are not considered, because 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.
      </para>

      <para>The <link linkend="bbv2.builtins.alias"><code>alias</code></link>
      rule can be used when targets must be installed into several
      directories:
<programlisting>
install install : install-bin install-lib ;
install install-bin : applications : /usr/bin ;
install install-lib : helper : /usr/lib ;
</programlisting>
    </para>

    <para>Because the <code>install</code> rule just copies targets, most 
    free features <footnote><para>see the definition of "free" in <xref
    linkend="bbv2.reference.features.attributes"/>.</para></footnote>
    have no effect when used in requirements of the <code>install</code>. 
    The only two which matter are  
    <link linkend="bbv2.builtin.features.dependency">
    <varname>dependency</varname></link> and, on Unix,
    <varname>dll-path</varname>. 
    </para>

    <note>
      <para>
        (Unix specific). On Unix, executables built with Boost.Build typically
        contain the list of paths to all used dynamic 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 with the <varname>dll-path</varname> feature.
      </para>
    </note>
      

    </section>

    <section id="bbv2.builtins.testing">

      <title>Testing</title>

      <para>Boost.Build has convenient support for running unit tests. The
        simplest way is the <code>unit-test</code> rule, which follows the
        <link linkend="bbv2.main-target-rule-syntax">common syntax</link>. For
        example:
<programlisting>
unit-test helpers_test : helpers_test.cpp helpers ;
</programlisting>
      </para>

      <para>The <functionname>unit-test</functionname> rule behaves like the
        <functionname>exe</functionname> rule, but after the executable is created it is
        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't miss a unit test failure.
      </para>

      <para>There are rules for more elaborate testing: <code>compile</code>,
        <code>compile-fail</code>, <code>run</code> and
        <code>run-fail</code>. They are more suitable for automated testing, and
        are not covered here.
      </para>        
    </section>
    
  </section>
  
  <section id="bbv2.advanced.builtins.features">
    <title>Builtin features</title> 
        
    <variablelist>
      <varlistentry><term><literal>variant</literal></term>
        
        <listitem>
          <simpara>
            A feature that combines several low-level features, making
            it easy to request common build configurations.
          </simpara>
          
          <para><emphasis role="bold">Allowed values:</emphasis> <literal>debug</literal>, <literal>release</literal>,
            <literal>profile</literal></para>
            <!-- It should be noted that these are extensible -->
          
          <para>The value <literal>debug</literal> expands to</para>
          
          <!-- these are badly formatted when printed; they run off the right edge of the page.  Fix. -->
          <programlisting>
            &lt;optimization&gt;off &lt;debug-symbols&gt;on &lt;inlining&gt;off &lt;runtime-debugging&gt;on
          </programlisting>
          
          <para>The value <literal>release</literal> expands to</para>
          
          <programlisting>
            &lt;optimization&gt;speed &lt;debug-symbols&gt;off &lt;inlining&gt;full &lt;runtime-debugging&gt;off
          </programlisting>
          
          <para>The value <literal>profile</literal> expands to the same as
            <literal>release</literal>, plus:</para>
          
          <programlisting>
            &lt;profiling&gt;on &lt;debug-symbols&gt;on
          </programlisting>
          
          <para><emphasis role="bold">Rationale:</emphasis> Runtime
          debugging is on in debug builds to suit the expectations of
          people used to various IDEs. 
          <!-- Define "runtime debugging." Why will those people expect it to be on in debug builds? -->
          It's assumed other folks don't
          have any specific expectation in this point.
          <!-- What is the value of that sentence? -->
          </para>
        </listitem></varlistentry>
      
      <varlistentry id="bbv2.advanced.builtins.features.link">
        <term><literal>link</literal></term>
        
        <listitem>
          <simpara>
            A feature that controls how libraries are built.
          </simpara>
          
          <para><emphasis role="bold">Allowed values:</emphasis> <literal>shared</literal>,
            <literal>static</literal></para>
        </listitem></varlistentry>
      
      <varlistentry><term><literal>source</literal></term>
        
        <listitem>
          <simpara>
            The <code>&lt;source&gt;X</code> feature has the same effect on building a target
            as putting X in the list of sources. The feature
            is sometimes more convenient:
            <!-- Than what? You have to say, or don't say "more." -->
            you can put <code>&lt;source&gt;X</code> in the
            requirements for a project and <filename>X</filename> will
            be included as a source in all of the project's main
            targets.
            <!-- The previous text was inaccurate -->
          </simpara>
        </listitem>
      </varlistentry>
      
      <varlistentry><term><literal>library</literal></term>
        
        <listitem>
          <simpara>
            This feature is equivalent to the &lt;source&gt; feature, and exists
            for backward compatibility reasons.
          </simpara>
        </listitem>
      </varlistentry>

      <varlistentry><term><anchor id="bbv2.builtin.features.dependency"/>
          <literal>dependency</literal></term>
        
        <listitem>
          <simpara>
            <!-- vp: I'm just copy-pasting the description of 
            'use', so that I can document 'stage'. I'll clean things up
            when I get to editing this part -->
            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 
            <!-- Do you really mean "to the requirements?" -->
            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>#include</code> paths) of some
            library to be applied, but don't want to link to it.
            <!-- It's hard to picture why anyone would want to do
                 that.  Please flesh out this motivation -->
          </simpara>
        </listitem>
      </varlistentry>

            
      <varlistentry><term><anchor id="bbv2.builtin.features.use"/>
          <literal>use</literal></term>
        
        <listitem>
          <simpara>
            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 
            <!-- Do you really mean "to the requirements?" -->
            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>#include</code> paths) of some
            library to be applied, but don't want to link to it.
            <!-- It's hard to picture why anyone would want to do
                 that.  Please flesh out this motivation -->
          </simpara>
        </listitem>
      </varlistentry>
      
      <varlistentry><term><literal>dll-path</literal></term>
        
        <listitem>
          <simpara>
            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 <xref linkend="bbv2.faq.dll-path"/>
            in <xref linkend="bbv2.faq"/> for details.
          </simpara>
        </listitem></varlistentry>
      
      <varlistentry><term><literal>hardcode-dll-paths</literal></term>
        
        <listitem>
          <simpara>
            Controls automatic generation of dll-path properties.
          </simpara>
          
          <para><emphasis role="bold">Allowed values:</emphasis>
            <literal>true</literal>, <literal>false</literal>.  This property
            is specific to Unix systems. If an executable is built with
            <code>&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 
            <!-- you need an antecedent.  This _what_? -->
            is very convenient during
            development. Plase see the <link
            linkend="bbv2.faq.dll-path">FAQ entry</link> for details.
            Note that on Mac OSX, the paths are unconditionally hardcoded by
            the linker, and it's not possible to disable that behaviour.
          </para>
        </listitem></varlistentry>

      <varlistentry>
        <term><literal>cflags</literal></term>
        <term><literal>cxxflags</literal></term>
        <term><literal>linkflags</literal></term>
        
        <listitem>
          <simpara>
            The value of those features is passed without modification to the
            corresponding tools. For <code>cflags</code> that's both C and C++
            compilers, for <code>cxxflags</code> that's C++ compiler and for
            <code>linkflags</code> that's linker. The features are handy when
            you're trying to do something special that cannot be achieved by
            higher-level feature in Boost.Build.
          </simpara>
        </listitem>
      </varlistentry>


    </variablelist>
  </section>

  <section id="bbv2.advanced.differences_to_v1">
    <title>Differences to Boost.Build V1</title>
    <!-- "Differences to" is the British English usage.  American
         English is "differences from."  You can use the former but be
         sure you know what you're doing -->

    <para>While Boost.Build V2 is based on the same ideas as Boost.Build V1,
    some of the syntax was changed, and some new important features were
    added. This chapter describes most of the changes.</para>

    <section id="bbv2.advanced.differences_to_v1.configuration">
      <title>Configuration</title>
      
      <para>In V1, there were two methods to configure a toolset. One was to
      set some environment variable, or use the <option>-s</option> command line option to set
      a variable inside BJam. 
      <!-- You can't say "one was ... , or ...."  If you say "One
           was," you have to say "and the other was."  I suggest "In
           V1 you could configure a toolset by..., or by ... " -->
      Another method was to create a new toolset module that would set
      the variables and then invoke the base toolset. Neither method
      is necessary now: the <functionname>using</functionname> rule provides a consistent way to
      initialize a toolset, 
      <!-- Rephrase the following.  If you can't tell what doesn't work about it, ask. -->
      including several versions. See <xref
      linkend="bbv2.advanced.configuration"/> for details.
      </para>
      
    </section>

    <section id="bbv2.advanced.differences_to_v1.jamfiles">
      <title>Writing Jamfiles</title>

      <para>Probably one of the most important differences in V2 Jamfiles is
      the use of project requirements. In V1, if several targets had the same
      requirements (for example, a common <code>#include</code> path), it was necessary to
      manually write the requirements or use a helper rule or template target. In V2, the
      common properties can be specified with the <code>requirements</code> project
      attribute, as documented in <xref linkend="bbv2.advanced.projects"/>.
      </para>

      <para><link linkend="bbv2.tutorial.libs">Usage requirements</link>
      also help to simplify Jamfiles. 
      <!-- Simplify, simplify, simplify!  You could go through the
           entire document several times and make changes like that
           one -->
      If a library requires
      all clients to use specific <code>#include</code> paths or macros when compiling 
      code that depends on the library, that information can be cleanly
      represented.</para>

      <para>The difference between <code>lib</code> and <code>dll</code> targets in V1 is completely
      eliminated in V2. There's only one library target type, <code>lib</code>, which can create
      either static or shared libraries depending on the value of the 
        <link linkend="bbv2.advanced.builtins.features.link"><varname>&lt;link&gt;</varname>
      feature</link>. If your target should be only built in one way<!--"variant" has a different meaning here-->, you
      can add <code>&lt;link&gt;shared</code> or <code>&lt;link&gt;static</code> to its requirements.
      </para>

      <para>The syntax for referring to other targets was changed a bit. While
      in V1 one would use:
<programlisting>
exe a : a.cpp &lt;lib&gt;../foo/bar ;
</programlisting> 
        the V2 syntax is:
<programlisting>
exe a : a.cpp ../foo//bar ;
</programlisting>
        Note that you don't need to specify the type of other target, but the
        last element should be separated from the others by a double slash to indicate that
        you're referring to target <filename>bar</filename> in project <filename>../foo</filename>, and not to
        project <filename>../foo/bar</filename>.
        </para>
      
                  
    </section>

    <section id="bbv2.advanced.differences_to_v1.build_process">
      <title>Build process</title>

      <para>The command line syntax in V2 is completely different. For example
<programlisting>
bjam -sTOOLS=msvc -sBUILD=release some_target
</programlisting>
        now becomes:
<programlisting>
bjam toolset=msvc variant=release some_target
</programlisting>
        or, using implicit features, just:
<programlisting>
bjam msvc release some_target
</programlisting>
      See <link linkend="bbv2.reference.commandline">the reference</link> for a
      complete description of the syntax.
      </para>

            
    </section>

  </section>
    

  </chapter>

<!--
     Local Variables:
     mode: nxml
     sgml-indent-data: t     
     sgml-parent-document: ("userman.xml" "chapter")
     sgml-set-face: t
     End:
-->
