<?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 <ulink
      url="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=8041">Boost
      source distribution</ulink>
      or <ulink url="http://sourceforge.net/cvs/?group_id=7586">CVS
      image</ulink>.
      <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&amp;package_id=8041">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 Boost <ulink url="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=8041">distribution</ulink>.
      <footnote>
        <para>The Boost.Build subset of boost is also distributed
        separately, for those who are only interested in getting a
        build tool. The top-level directory of a <ulink
        url="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=80982">Boost.Build
        distribution</ulink> contains all the subdirectories of the
        <filename>tools/build/v2</filename> subdirectory from a full
        Boost distribution, so it is itself a valid Boost.Build root
        directory.  It also contains the
        <filename>tools/jam/src</filename> subdirectory of a
        full Boost distribution, so you can rebuild Boost.Jam from
        source.
        </para>
    </footnote>
    </para>

    <orderedlist>
      <listitem>
        <simpara>
          Boost.Build uses <ulink
          url= "../../tools/jam/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 necessary to 
          <link linkend="jam.building">build <command>bjam</command>
          from sources</link> 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 necessary, 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>

        <bridgehead>Information for distributors</bridgehead>

        <para>
          If you're planning to package Boost.Build for a Linux distribution,
          please follow these guidelines:

          <itemizedlist>
            <listitem><para>Create a separate package for Boost.Jam.</para></listitem>

            <listitem>
              <para>Create another package for Boost.Build, and make
              this package install all Boost.Build files to
              <filename>/usr/share/boost-build</filename> directory. After
              install, that directory should contain everything you see in
              Boost.Build release package, except for
              <filename>jam_src</filename> directory.  If you're using Boost CVS
              to obtain Boost.Build, as opposed to release package, take
              everything from the <filename>tools/build/v2</filename> directory.
              For a check, make sure that
              <filename>/usr/share/boost-build/boost-build.jam</filename> is installed.
              </para>

              <para>Placing Boost.Build into <filename>/usr/share/boost-build</filename>
              will make sure that <command>bjam</command> will find Boost.Build
              without any additional setup.</para>
            </listitem>

            <listitem><para>Provide a
            <filename>/etc/site-config.jam</filename> configuration file that will
            contain:
<programlisting>
using gcc ;
</programlisting>
             You might want to add dependency from Boost.Build package to gcc,
             to make sure that users can always build Boost.Build examples.
            </para></listitem>
          </itemizedlist>
        </para>

        <para>If those guidelines are met, users will be able to invoke
        <command>bjam</command> without any explicit configuration.
        </para>

    
      

  </chapter>

<!--
     Local Variables:
     mode: nxml
     sgml-indent-data:t
     sgml-parent-document:("userman.xml" "chapter")
     sgml-set-face: t
     sgml-omittag:nil
     sgml-shorttag:nil
     sgml-namecase-general:t
     sgml-general-insert-case:lower
     sgml-minimize-attributes:nil
     sgml-always-quote-attributes:t
     sgml-indent-step:2
     sgml-exposed-tags:nil
     sgml-local-catalogs:nil
     sgml-local-ecat-files:nil
     End:
-->