<h1class="title"><aclass="reference"href="../../index.htm"><imgalt="Boost"class="boost-logo"src="../../boost.png"/></a> Getting Started on Unix Variants</h1>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<!-- maybe we don't need this
.. Admonition:: A note to Cygwin_ and MinGW_ users
If you plan to build from the Cygwin_ bash shell, you're in the
right place. If you plan to use your tools from the Windows
command prompt, you should follow the instructions for `getting
started on Windows`_. Other command shells, such as MinGW_\ 's
<li><aclass="reference"href="#build-a-simple-program-using-boost"id="id21">4 Build a Simple Program Using Boost</a><ulclass="auto-toc">
<li><aclass="reference"href="#errors-and-warnings"id="id22">4.1 Errors and Warnings</a></li>
<li><aclass="reference"href="#prepare-to-use-a-boost-library-binary"id="id23">5 Prepare to Use a Boost Library Binary</a><ulclass="auto-toc">
<li><aclass="reference"href="#easy-build-and-install"id="id24">5.1 Easy Build and Install</a></li>
<li><aclass="reference"href="#or-custom-build-and-install"id="id25">5.2 Or, Custom Build and Install</a><ulclass="auto-toc">
<li><aclass="reference"href="#link-your-program-to-a-boost-library"id="id32">6 Link Your Program to a Boost Library</a><ulclass="auto-toc">
<p>The most reliable way to get a copy of Boost is to download a
distribution from <aclass="reference"href="http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041&release_id=376197">SourceForge</a>:</p>
any trouble, we suggest using an official Boost distribution
from <aclass="reference"href="http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041&release_id=376197">SourceForge</a>.</p>
</div>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<pclass="pre-wrap">The organization of Boost library headers isn't entirely uniform,
but most libraries follow a few patterns:</p>
<ulclass="pre-wrap last">
<li><pclass="first">Some older libraries and most very small libraries place all
public headers directly into <ttclass="docutils literal"><spanclass="pre">boost</span></tt><ttclass="docutils literal"><spanclass="pre">/</span></tt>.</p>
</li>
<li><pclass="first">Most libraries' public headers live in a subdirectory of
<ttclass="docutils literal"><spanclass="pre">boost</span></tt><ttclass="docutils literal"><spanclass="pre">/</span></tt>, named after the library. For example, you'll find
the Python library's <ttclass="docutils literal"><spanclass="pre">def.hpp</span></tt> header in</p>
<li><pclass="first">Some libraries have an “aggregate header” in <ttclass="docutils literal"><spanclass="pre">boost</span></tt><ttclass="docutils literal"><spanclass="pre">/</span></tt> that
<ttclass="docutils literal"><spanclass="pre">#include</span></tt>s all of the library's other headers. For
example, <aclass="reference"href="../../libs/python/doc/building.html">Boost.Python</a>'s aggregate header is</p>
<li><pclass="first">Most libraries place private headers in a subdirectory called
<ttclass="docutils literal"><spanclass="pre">detail</span></tt><ttclass="docutils literal"><spanclass="pre">/</span></tt>, or <ttclass="docutils literal"><spanclass="pre">aux_</span></tt><ttclass="docutils literal"><spanclass="pre">/</span></tt>. Don't expect to find
anything you can use in these directories.</p>
</li>
</ul>
</div>
<p>It's important to note the following:</p>
<olclass="arabic"id="boost-root-directory">
<li><pclass="first">The path to the <strong>boost root directory</strong> (often <ttclass="docutils literal"><spanclass="pre">/usr/local/</span></tt><ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt>) is
sometimes referred to as <ttclass="docutils literal"><spanclass="pre">$BOOST_ROOT</span></tt> in documentation and
mailing lists .</p>
</li>
<li><pclass="first">To compile anything in Boost, you need a directory containing
the <ttclass="docutils literal"><spanclass="pre">boost</span></tt><ttclass="docutils literal"><spanclass="pre">/</span></tt> subdirectory in your <ttclass="docutils literal"><spanclass="pre">#include</span></tt> path. <ttclass="docutils literal"></tt></p>
</li>
<li><pclass="first">Since all of Boost's header files have the <ttclass="docutils literal"><spanclass="pre">.hpp</span></tt> extension,
and live in the <ttclass="docutils literal"><spanclass="pre">boost</span></tt><ttclass="docutils literal"><spanclass="pre">/</span></tt> subdirectory of the boost root, your
Boost <ttclass="docutils literal"><spanclass="pre">#include</span></tt> directives will look like:</p>
<li><pclass="first">Don't be distracted by the <ttclass="docutils literal"><spanclass="pre">doc</span></tt><ttclass="docutils literal"><spanclass="pre">/</span></tt> subdirectory; it only
contains a subset of the Boost documentation. Start with
<ttclass="docutils literal"><spanclass="pre">libs</span></tt><ttclass="docutils literal"><spanclass="pre">/</span></tt><ttclass="docutils literal"><spanclass="pre">index.html</span></tt> if you're looking for the whole enchilada.</p>
</li>
</ol>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<li><aclass="reference"href="../../libs/python/doc/building.html">Boost.Python</a> (see the <aclass="reference"href="../../libs/python/doc/building.html">Boost.Python build documentation</a>
<p>A few libraries have optional separately-compiled binaries:</p>
<ulclass="simple">
<li><aclass="reference"href="../../libs/date_time/index.html">Boost.DateTime</a> has a binary component that is only needed if
you're using its <ttclass="docutils literal"><spanclass="pre">to_string</span></tt>/<ttclass="docutils literal"><spanclass="pre">from_string</span></tt> or serialization
features, or if you're targeting Visual C++ 6.x or Borland.</li>
<li><aclass="reference"href="../../libs/graph/index.html">Boost.Graph</a> also has a binary component that is only needed if
you intend to <aclass="reference"href="../../libs/graph/doc/read_graphviz.html">parse GraphViz files</a>.</li>
<li><aclass="reference"href="../../libs/test/index.html">Boost.Test</a> can be used in “header-only” or “separately compiled”
mode, although <strong>separate compilation is recommended for serious
use</strong>.</li>
</ul>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<p>to install somewhere else. Also, consider using the
<ttclass="docutils literal"><spanclass="pre">--show-libraries</span></tt> and <ttclass="docutils literal"><spanclass="pre">--with-libraries=</span></tt> options to limit the
long wait you'll experience if you build everything. Finally,</p>
<preclass="literal-block">
<strong>$</strong> make install
</pre>
<p>will leave Boost binaries in the <ttclass="docutils literal"><spanclass="pre">lib/</span></tt> subdirectory of your
installation prefix. You will also find a copy of the Boost
headers in the <ttclass="docutils literal"><spanclass="pre">include/</span></tt> subdirectory of the installation
prefix, so you can henceforth use that directory as an <ttclass="docutils literal"><spanclass="pre">#include</span></tt>
path in place of the Boost root directory.</p>
<p><aclass="reference"href="#link-your-program-to-a-boost-library"><em>skip to the next step</em></a></p>
<p><ttclass="docutils literal"><spanclass="pre">bjam</span></tt> is the command-line tool that drives the Boost Build
system. To build Boost binaries, you'll invoke <ttclass="docutils literal"><spanclass="pre">bjam</span></tt> from the
Boost root.</p>
<p>Boost provides <aclass="reference"href="http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=72941">pre-compiled <ttclass="docutils literal"><spanclass="pre">bjam</span></tt> executables</a> for a variety of platforms.
Alternatively, you can build <ttclass="docutils literal"><spanclass="pre">bjam</span></tt> yourself using <aclass="reference"href="../../doc/html/jam/building.html">these
<p>If you have multiple versions of a particular compiler installed,
you can append the version number to the toolset name, preceded by a
hyphen, e.g. <ttclass="docutils literal"><spanclass="pre">msvc-7.1</span></tt> or <ttclass="docutils literal"><spanclass="pre">gcc-3.4</span></tt>.</p>
<divclass="note">
<pclass="first admonition-title">Note</p>
<pclass="last">if you built <ttclass="docutils literal"><spanclass="pre">bjam</span></tt> yourself, you may
have selected a toolset name for that purpose, but that does not
affect this step in any way; you still need to select a Boost.Build
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<p>Boost.Build will place the Boost binaries in the <ttclass="docutils literal"><spanclass="pre">stage</span></tt><ttclass="docutils literal"><spanclass="pre">/</span></tt>
subdirectory of your <aclass="reference"href="#build-directory">build directory</a>.</p>
<divclass="note">
<pclass="first admonition-title">Note</p>
<pclass="last"><ttclass="docutils literal"><spanclass="pre">bjam</span></tt> is case-sensitive; it is important that all the
parts shown in <strong>bold</strong> type above be entirely lower-case.</p>
</div>
<p>For a description of other options you can pass when invoking
<p>In particular, to limit the amount of time spent building, you may
be interested in:</p>
<ulclass="simple">
<li>reviewing the list of library names with <ttclass="docutils literal"><spanclass="pre">--show-libraries</span></tt></li>
<li>limiting which libraries get built with the <ttclass="docutils literal"><spanclass="pre">--with-</span></tt><em>library-name</em> or <ttclass="docutils literal"><spanclass="pre">--without-</span></tt><em>library-name</em> options</li>
<li>choosing a specific build variant by adding <ttclass="docutils literal"><spanclass="pre">release</span></tt> or
<ttclass="docutils literal"><spanclass="pre">debug</span></tt> to the command line.</li>
<li><pclass="first">You can separately specify a directory to search (with <ttclass="docutils literal"><spanclass="pre">-L</span></tt><em>directory</em>) and a library name to search for (with <ttclass="docutils literal"><spanclass="pre">-l</span></tt><em>library</em>,<aclass="footnote-reference"href="#lowercase-l"id="id12"><sup>2</sup></a> dropping the filename's leading <ttclass="docutils literal"><spanclass="pre">lib</span></tt> and trailing
convention. On most unix-style platforms the extensions are
<ttclass="docutils literal"><spanclass="pre">.a</span></tt> and <ttclass="docutils literal"><spanclass="pre">.so</span></tt> for static libraries (archives) and shared
libraries, respectively. On Windows, <ttclass="docutils literal"><spanclass="pre">.dll</span></tt> indicates a shared
library and (except for static libraries built by the <ttclass="docutils literal"><spanclass="pre">gcc</span></tt>
<aclass="reference"href="#toolset">toolset</a>, whose names always end in <ttclass="docutils literal"><spanclass="pre">.a</span></tt>) <ttclass="docutils literal"><spanclass="pre">.lib</span></tt> indicates a
<p>To test our subject extraction, we'll filter the following text
file. Copy it out of your browser and save it as <ttclass="docutils literal"><spanclass="pre">jayne.txt</span></tt>:</p>
<preclass="literal-block">
To: George Shmidlap
From: Rita Marlowe
Subject: Will Success Spoil Rock Hunter?
---
See subject.
</pre>
<p>If you linked to a shared library, you may need to prepare some
platform-specific settings so that the system will be able to find
and load it when your program is run. Most platforms have an
environment variable to which you can add the directory containing
the library. On many platforms (Linux, FreeBSD) that variable is
<ttclass="docutils literal"><spanclass="pre">LD_LIBRARY_PATH</span></tt>, but on MacOS it's <ttclass="docutils literal"><spanclass="pre">DYLD_LIBRARY_PATH</span></tt>, and
on Cygwin it's simply <ttclass="docutils literal"><spanclass="pre">PATH</span></tt>. In most shells other than <ttclass="docutils literal"><spanclass="pre">csh</span></tt>
and <ttclass="docutils literal"><spanclass="pre">tcsh</span></tt>, you can adjust the variable as follows (again, don't
type the <ttclass="docutils literal"><spanclass="pre">$</span></tt>—that represents the shell prompt):</p>
<ttclass="docutils literal"><spanclass="pre">NDEBUG</span></tt><ttclass="docutils literal"><spanclass="pre">#define</span></tt>d. Although it's true that sometimes
