build/doc/src/install.xml

<?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.installation">
    <title>Installation</title>

    <para>
      This section describes how to install Boost.Build from a
      released Boost source distribution. 
      <footnote>
        <para>Note that packages prepared for
      Unix/Linux systems usually make their own choices about where to
      put things and even which parts of Boost to include.  When we
      say &#x201C;released source distribution&#x201D; we mean a
      distribution of Boost as released on its SourceForge
      <ulink url="http://sourceforge.net/project/showfiles.php?group_id=7586">project
      page</ulink>.
        </para>
    </footnote>
All paths are given relative to
      the <firstterm>Boost.Build v2 root directory</firstterm>, which is 

      <!-- the normal location of the document you are reading.
      Boost.Build is -->

      <!-- That is a lie AFAICT, at least in a Boost distro.  You need
      to say something that will be true if you want to cover BBv2 as
      distributed separately -->

      located in the <filename>tools/build/v2</filename> subdirectory
      of a full <ulink url="http://www.boost.org">Boost</ulink>
      distribution.
    </para>

    <orderedlist>
      <listitem>
        <simpara>
          Boost.Build uses <ulink
          url= "../../tools/build/jam_src/index.html">Boost.Jam</ulink>, an
          extension of the <ulink
          url="http://www.perforce.com/jam/jam.html">Perforce
          Jam</ulink> portable <command>make</command> replacement. The
          recommended way to get Boost.Jam is to <emphasis
          role="bold"><ulink
          url= "http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=72941">download
          a prebuilt executable</ulink></emphasis> from SourceForge.
          If a prebuilt executable is not provided for your platform
          or you are using Boost's sources in an unreleased state, it
          may be neccessary to <ulink
          url= "../../tools/build/jam_src/index.html#building_bjam">build <command>bjam</command>
          from sources</ulink> included in the Boost source tree.
        </simpara>
      </listitem>

      <listitem>
        <para>

          To install Boost.Jam, copy the executable,
          called <command>bjam</command>
          or <command>bjam.exe</command> to a location accessible in
          your <envar>PATH</envar>.  Go to the Boost.Build root
          directory and
          run <command>bjam <option>--version</option></command>. You
          should see:

          <screen>
            Boost.Build V2 (Milestone N)
            Boost.Jam xx.xx.xx 
          </screen>

          where N is the version of Boost.Build you're using.
        </para>
      </listitem>

      <listitem>
        <simpara>
          Configure Boost.Build to recognize the build resources (such
          as compilers and libraries) you have installed on your
          system.  Open the
          <filename>user-config.jam</filename> file in the Boost.Build
          root directory and follow the instructions there to describe
          your toolsets and libraries, and, if neccessary, where they
          are located.
        </simpara>
      </listitem>

      <listitem>
        <simpara>
          You should now be able to go to the
          <filename>example/hello/</filename> directory and run
          <command>bjam</command> there. A simple application will be
          built. You can also play with other projects in the
          <filename>example/</filename> directory. 
    <!-- This part should not go into intoduction docs, but we need to
         place it somewhere. 

    <para>It is slighly better way is to copy
    <filename>new/user-config.jam</filename> into one of the locations
    where it can be found (given in <link linkend=
    "bbv2.reference.init.config">this table</link>). This prevent you
    from accidentally overwriting your config when updating.</para>

    -->
        </simpara>
      </listitem>
    </orderedlist>

    <para>
      If you are using Boost's CVS state, be sure to
      rebuild <command>bjam</command> even if you have a previous
      version.  The CVS version of Boost.Build requires the CVS
      version of Boost.Jam.
    </para>

    <para>
      When <command>bjam</command> is invoked, it always needs to be
      able to find the Boost.Build root directory, where the
      interpreted source code of Boost.Build is located.  There are
      two ways to tell <command>bjam</command> about the root directory:
    </para>

    <itemizedlist>
      <listitem>
        <simpara>
          Set the environment variable <envar>BOOST_BUILD_PATH</envar>
          to the absolute path of the Boost.Build root directory.
        </simpara>
      </listitem>

      <listitem>
        <para>
          At the root directory of your project or in any of its
          parent directories, create a file called
          <filename>boost-build.jam</filename>, with a single line:

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

        </para>
      </listitem>
    </itemizedlist>

  <para><emphasis role="bold">N.B.</emphasis>
  When <command>bjam</command> is invoked from anywhere in the Boost
  directory tree <emphasis>other than</emphasis> the Boost.Build root
  and its subdirectories, <ulink url="../../tools/build">Boost.Build
  v1</ulink> is used by default. To override the default and use
  Boost.Build v2, you have to add the <option>--v2</option> command
  line option to all <command>bjam</command> invocations.</para>

  </chapter>