<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="id20"name="id20">4 Build a Simple Program Using Boost</a><ulclass="auto-toc">
<li><aclass="reference"href="#errors-and-warnings"id="id21"name="id21">4.1 Errors and Warnings</a></li>
</ul>
</li>
<li><aclass="reference"href="#prepare-to-use-a-boost-library-binary"id="id22"name="id22">5 Prepare to Use a Boost Library Binary</a><ulclass="auto-toc">
<li><aclass="reference"href="#easy-build-and-install"id="id23"name="id23">5.1 Easy Build and Install</a></li>
<li><aclass="reference"href="#or-custom-build-and-install"id="id24"name="id24">5.2 Or, Custom Build and Install</a><ulclass="auto-toc">
<li><aclass="reference"href="#in-case-of-build-errors"id="id30"name="id30">5.4 In Case of Build Errors</a></li>
</ul>
</li>
<li><aclass="reference"href="#link-your-program-to-a-boost-library"id="id31"name="id31">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>
<pclass="last">RedHat, Debian, and other distribution packagers supply Boost
library packages, however you may need to adapt these
instructions if you use third-party packages, because their
creators usually choose to break Boost up into several packages,
reorganize the directory structure of the Boost distribution,
and/or rename the library binaries.<aclass="footnote-reference"href="#packagers"id="id2"name="id2"><sup>1</sup></a> If you have
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) -->
<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) -->
</div>
<divclass="section">
<h1><aclass="toc-backref"href="#id20"id="build-a-simple-program-using-boost"name="build-a-simple-program-using-boost">4 Build a Simple Program Using Boost</a></h1>
<p>To keep things simple, let's start by using a header-only library.
The following program reads a sequence of integers from standard
input, uses Boost.Lambda to multiply each number by three, and
<p>Copy the text of this program into a file called <ttclass="docutils literal"><spanclass="pre">example.cpp</span></tt>.</p>
<p>Now, in the directory where you saved <ttclass="docutils literal"><spanclass="pre">example.cpp</span></tt>, issue the
following command:</p>
<preclass="literal-block">
c++ -I <em>path/to/</em><ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt> example.cpp -o example
</pre>
<p>To test the result, type:</p>
<preclass="literal-block">
echo 1 2 3 | ./example
</pre>
<!-- 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) -->
<divclass="section">
<h2><aclass="toc-backref"href="#id21"id="errors-and-warnings"name="errors-and-warnings">4.1 Errors and Warnings</a></h2>
<p>Don't be alarmed if you see compiler warnings originating in Boost
headers. We try to eliminate them, but doing so isn't always
practical.<aclass="footnote-reference"href="#warnings"id="id4"name="id4"><sup>3</sup></a><strong>Errors are another matter</strong>. If you're
seeing compilation errors at this point in the tutorial, check to
be sure you've copied the <aclass="reference"href="#build-a-simple-program-using-boost">example program</a> correctly and that you've
correctly identified the <aclass="reference"href="#boost-root-directory">Boost root directory</a>.</p>
<!-- 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) -->
</div>
</div>
<divclass="section">
<h1><aclass="toc-backref"href="#id22"id="prepare-to-use-a-boost-library-binary"name="prepare-to-use-a-boost-library-binary">5 Prepare to Use a Boost Library Binary</a></h1>
<p>If you want to use any of the separately-compiled Boost libraries,
you'll need to acquire library binaries.</p>
<divclass="section">
<h2><aclass="toc-backref"href="#id23"id="easy-build-and-install"name="easy-build-and-install">5.1 Easy Build and Install</a></h2>
<p>Issue the following commands in the shell (don't type <ttclass="docutils literal"><spanclass="pre">$</span></tt>; that
represents the shell's prompt):</p>
<preclass="literal-block">
<strong>$</strong> cd <em>path/to/</em><ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt>
<strong>$</strong> ./configure --help
</pre>
<p>Select your configuration options and invoke <ttclass="docutils literal"><spanclass="pre">./configure</span></tt> again
without the <ttclass="docutils literal"><spanclass="pre">--help</span></tt> option. Unless you have write permission in
your system's <ttclass="docutils literal"><spanclass="pre">/usr/local/</span></tt> directory, you'll probably want to at
<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>
</div>
<divclass="section">
<h2><aclass="toc-backref"href="#id24"id="or-custom-build-and-install"name="or-custom-build-and-install">5.2 Or, Custom Build and Install</a></h2>
<p>If you're using a compiler other than your system's default, you'll
need to use <aclass="reference"href="../../tools/build/index.html">Boost.Build</a> to create binaries. You'll also
use this method if you need a nonstandard build variant (see the
<aclass="reference"href="../../tools/build/index.html">Boost.Build documentation</a> for more details).</p>
<!-- 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><aclass="reference"href="../../tools/build/index.html">Boost.Build</a> is a text-based system for developing, testing, and
installing software. To use it, you'll need an executable called
<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
instructions</a>.</p>
</div>
<divclass="section">
<h3><aclass="toc-backref"href="#id26"id="identify-your-toolset"name="identify-your-toolset"><spanid="toolset-name"></span><spanid="toolset"></span>5.2.2 Identify Your Toolset</a></h3>
<p>First, find the toolset corresponding to your compiler in the
<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
toolset from the table.</p>
</div>
</div>
<divclass="section">
<h3><aclass="toc-backref"href="#id27"id="select-a-build-directory"name="select-a-build-directory"><spanid="id9"></span><spanid="build-directory"></span>5.2.3 Select a Build Directory</a></h3>
<p><aclass="reference"href="../../tools/build/index.html">Boost.Build</a> will place all intermediate files it generates while
building into the <strong>build directory</strong>. If your Boost root
directory is writable, this step isn't strictly necessary: by
default Boost.Build will create a <ttclass="docutils literal"><spanclass="pre">bin.v2/</span></tt> subdirectory for that
<!-- 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>
<!-- 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) -->
</div>
</div>
<divclass="section">
<h1><aclass="toc-backref"href="#id31"id="link-your-program-to-a-boost-library"name="link-your-program-to-a-boost-library">6 Link Your Program to a Boost Library</a></h1>
<p>To demonstrate linking with a Boost binary library, we'll use the
following simple program that extracts the subject lines from
emails. It uses the <aclass="reference"href="../../libs/regex/index.html">Boost.Regex</a> library, which has a
<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="id11"name="id11"><sup>2</sup></a> dropping the filename's leading <ttclass="docutils literal"><spanclass="pre">lib</span></tt> and trailing
suffix (<ttclass="docutils literal"><spanclass="pre">.a</span></tt> in this case):</p>
<preclass="literal-block">
$ c++ -I <em>path/to/</em><ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt> example.cpp -o example <strong>\</strong>
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>
toolset, whose names always end in <ttclass="docutils literal"><spanclass="pre">.a</span></tt>) <ttclass="docutils literal"><spanclass="pre">.lib</span></tt> indicates a
static or import library. Where supported by toolsets on unix
variants, a full version extension is added (e.g. ".so.1.34") and
a symbolic link to the library file, named without the trailing
<!-- 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) -->
</div>
<divclass="section">
<h2><aclass="toc-backref"href="#id33"id="test-your-program"name="test-your-program">6.2 Test Your Program</a></h2>
<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>
<p>The program should respond with the email subject, “Will Success
Spoil Rock Hunter?”</p>
<!-- 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) -->
</div>
</div>
<divclass="section">
<h1><aclass="toc-backref"href="#id34"id="conclusion-and-further-resources"name="conclusion-and-further-resources">7 Conclusion and Further Resources</a></h1>
<p>This concludes your introduction to Boost and to integrating it
with your programs. As you start using Boost in earnest, there are
surely a few additional points you'll wish we had covered. One day
we may have a “Book 2 in the Getting Started series” that addresses
them. Until then, we suggest you pursue the following resources.
If you can't find what you need, or there's anything we can do to
make this document clearer, please post it to the <aclass="reference"href="../../more/mailing_lists.htm#users">Boost Users'
<tr><tdclass="label"><aclass="fn-backref"href="#id2"name="packagers">[1]</a></td><td><pclass="first">If developers of Boost packages would like to work
with us to make sure these instructions can be used with their
packages, we'd be glad to help. Please make your interest known
to the <aclass="reference"href="../../more/mailing_lists.htm#main">Boost developers' list</a>.</p>
<ttclass="docutils literal"><spanclass="pre">NDEBUG</span></tt><ttclass="docutils literal"><spanclass="pre">#define</span></tt>d. Although it's true that sometimes
