| <?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&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 “released source distribution” we mean a |
| distribution of Boost as released on its SourceForge |
| <ulink url="http://sourceforge.net/project/showfiles.php?group_id=7586&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&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&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&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: |
| --> |
| |