<li><aclass="reference"href="#the-structure-of-a-boost-distribution"id="id21"name="id21">2 The Structure of a Boost Distribution</a></li>
<li><aclass="reference"href="#building-a-simple-boost-program"id="id22"name="id22">3 Building a Simple Boost Program</a><ulclass="auto-toc">
<li><aclass="reference"href="#microsoft-windows-command-line-using-visual-c"id="id24"name="id24">3.2 Microsoft Windows Command-Line using Visual C++</a></li>
<li><aclass="reference"href="#visual-studio-net-2003-or-visual-studio-2005"id="id25"name="id25">3.3 Visual Studio .NET 2003 or Visual Studio 2005</a></li>
<li><aclass="reference"href="#microsoft-visual-c-8-0-or-7-1-visual-studio-2005-net-2003-binaries"id="id28"name="id28">4.1 Microsoft Visual C++ 8.0 or 7.1 (Visual Studio 2005/.NET 2003) Binaries</a></li>
<li><aclass="reference"href="#building-boost-binaries-with-boost-build"id="id31"name="id31">4.4 Building Boost Binaries with Boost.Build</a><ulclass="auto-toc">
<li><aclass="reference"href="#select-a-prefix-directory"id="id37"name="id37">4.4.6 Select a Prefix Directory</a></li>
</ul>
</li>
</ul>
</li>
<li><aclass="reference"href="#linking-a-program-with-a-boost-library"id="id38"name="id38">5 Linking A Program with a Boost Library</a><ulclass="auto-toc">
<p>There are basically three ways to get Boost on your system:</p>
<olclass="arabic simple">
<li>Download and run the <aclass="reference"href="http://www.boost-consulting.com/download.html">Windows installer</a> supplied by Boost
Consulting (not available for Boost alpha/beta releases).</li>
</ol>
<!-- ## remove the parenthesized note for full releases -->
<olclass="arabic simple"start="2">
<li>or, <aclass="reference"href="http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041&release_id=376197">download a complete Boost distribution</a> from SourceForge.</li>
<trclass="field"><thclass="field-name">Windows users:</th><tdclass="field-body"><pclass="first"><ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt><ttclass="docutils literal"><spanclass="pre">.exe</span></tt> is a program you can
run to unpack the distribution; if you prefer not to download
executable programs, get <ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt><ttclass="docutils literal"><spanclass="pre">.zip</span></tt> and use an
external tool to decompress it. We don't recommend using
Windows' built-in decompression as it can be painfully slow
for large archives.</p>
</td>
</tr>
<trclass="field"><thclass="field-name">*nix users:</th><tdclass="field-body"><pclass="first">Download <ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt><ttclass="docutils literal"><spanclass="pre">.tar.bz2</span></tt>, then, in the
directory where you want to put the Boost installation,
execute</p>
<preclass="last literal-block">
tar --bzip2 -xf <em>/path/to/</em><ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt>.tar.bz2
</pre>
</td>
</tr>
</tbody>
</table>
</blockquote>
<olclass="arabic simple"start="3">
<li>or use a Boost package from RedHat, Debian, or some other
distribution packager. These instructions may not work for you
if you use this method, because other packagers sometimes choose
to break Boost up into several packages or to reorganize the
directory structure of the Boost distribution.<aclass="footnote-reference"href="#packagers"id="id3"name="id3"><sup>1</sup></a></li>
</ol>
</div>
<divclass="section">
<h1><aclass="toc-backref"href="#id21"id="the-structure-of-a-boost-distribution"name="the-structure-of-a-boost-distribution">2 The Structure of a Boost Distribution</a></h1>
<p>This is is a sketch of the directory structure you'll get when you
unpack your Boost installation (windows users replace forward
<li>Most libraries place private headers in a subdirectory called
<ttclass="docutils literal"><spanclass="pre">detail/</span></tt> or <ttclass="docutils literal"><spanclass="pre">aux_/</span></tt>. Don't look in these directories and
expect to find anything you can use.</li>
</ul>
</div>
<p>A few things are worth noting right off the bat:</p>
<olclass="arabic">
<li><pclass="first">The path to the “boost root directory” is sometimes referred to
as <ttclass="docutils literal"><spanclass="pre">$BOOST_ROOT</span></tt> in documentation and mailing lists. If you
used the Windows installer, that will usually be <ttclass="docutils literal"><spanclass="pre">C:\Program</span><spanclass="pre">Files\boost\</span></tt><ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt>.</p>
</li>
<li><pclass="first">To compile anything in Boost, you need a directory containing
the <ttclass="docutils literal"><spanclass="pre">boost/</span></tt> subdirectory in your <ttclass="docutils literal"><spanclass="pre">#include</span></tt> path. For most
<p>to the command line. Specific steps for setting up <ttclass="docutils literal"><spanclass="pre">#include</span></tt>
paths in Microsoft Visual Studio follow later in this document;
if you use another IDE, please consult your product's
documentation for instructions.</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> subdirectory of the boost root, your
Boost <ttclass="docutils literal"><spanclass="pre">#include</span></tt> directives will look like:</p>
<preclass="literal-block">
#include <boost/<em>whatever</em>.hpp>
</pre>
<p>or</p>
<preclass="literal-block">
#include "boost/<em>whatever</em>.hpp"
</pre>
</li>
</ol>
<blockquote>
depending on your religion as regards the use of angle bracket
includes. Even Windows users can use forward slashes in
<ttclass="docutils literal"><spanclass="pre">#include</span></tt> directives; your compiler doesn't care.</blockquote>
<olclass="arabic simple"start="4">
<li>Don't be distracted by the <ttclass="docutils literal"><spanclass="pre">doc/</span></tt> subdirectory; it only
contains a subset of the Boost documentation. Start with
<ttclass="docutils literal"><spanclass="pre">libs/index.html</span></tt> if you're looking for the whole enchilada.</li>
</ol>
</div>
<divclass="section">
<h1><aclass="toc-backref"href="#id22"id="building-a-simple-boost-program"name="building-a-simple-boost-program">3 Building a Simple Boost Program</a></h1>
<p>The first thing many people want to know is, “how do I build
Boost?” The good news is that often, there's nothing to build.</p>
<p>Simply issue the following command (<ttclass="docutils literal"><spanclass="pre">$</span></tt> represents the
prompt issued by the shell, so don't type that):</p>
<preclass="literal-block">
<strong>$</strong> c++ -I <ttclass="docutils literal"><spanclass="pre">/</span></tt><em>path</em><ttclass="docutils literal"><spanclass="pre">/</span></tt><em>to</em><ttclass="docutils literal"><spanclass="pre">/</span></tt><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">
<strong>$</strong> echo 1 2 3 | ./example
</pre>
</div>
<divclass="section">
<h2><aclass="toc-backref"href="#id24"id="microsoft-windows-command-line-using-visual-c"name="microsoft-windows-command-line-using-visual-c">3.2 Microsoft Windows Command-Line using Visual C++</a></h2>
<p>From your computer's <em>Start</em> menu, select if you are a Visual
Studio 2005 user, select</p>
<blockquote>
<em>All Programs</em>><em>Microsoft Visual Studio 2005</em>
><em>Visual Studio Tools</em>><em>Visual Studio 2005 Command Prompt</em></blockquote>
<p>or if you're a Visual Studio .NET 2003 user, select</p>
<blockquote>
<em>All Programs</em>><em>Microsoft Visual Studio .NET 2003</em>
><em>Visual Studio .NET Tools</em>><em>Visual Studio .NET 2003 Command Prompt</em></blockquote>
<p>to bring up a special command prompt window set up for the Visual
Studio compiler. In that window, type the following command and
hit the return key (<ttclass="docutils literal"><spanclass="pre">C:\PROMPT></span></tt> represents the prompt issued by
<strong>C:PROMPT></strong> echo 1 2 3 | example
</pre>
</div>
<divclass="section">
<h2><aclass="toc-backref"href="#id25"id="visual-studio-net-2003-or-visual-studio-2005"name="visual-studio-net-2003-or-visual-studio-2005"><spanid="vs-header-only"></span>3.3 Visual Studio .NET 2003 or Visual Studio 2005</a></h2>
<p>If you want to use any of the separately-compiled Boost libraries,
you'll need to get ahold of library binaries.</p>
<divclass="section">
<h2><aclass="toc-backref"href="#id28"id="microsoft-visual-c-8-0-or-7-1-visual-studio-2005-net-2003-binaries"name="microsoft-visual-c-8-0-or-7-1-visual-studio-2005-net-2003-binaries">4.1 Microsoft Visual C++ 8.0 or 7.1 (Visual Studio 2005/.NET 2003) Binaries</a></h2>
<p>The <aclass="reference"href="http://www.boost-consulting.com/download.html">Windows installer</a> supplied by Boost Consulting will download
and install pre-compiled binaries into the <ttclass="docutils literal"><spanclass="pre">lib\</span></tt> subdirectory of
the boost root, typically <ttclass="docutils literal"><spanclass="pre">C:\Program</span><spanclass="pre">Files\boost\</span></tt><ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt><ttclass="docutils literal"><spanclass="pre">\lib\</span></tt>.</p>
<p>If you're not using Visual C++ 7.1 or 8.0, or you're a *nix user
who wants want to build with a toolset other than your system's
default, or if you want a nonstandard variant build of Boost
(e.g. optimized, but with debug symbols), you'll need to use
<aclass="reference"href="../tools/build/index.html">Boost.Build</a> to create your own binaries.</p>
</div>
<divclass="section">
<h2><aid="building-boost-binaries-with-boost-build"name="building-boost-binaries-with-boost-build">4.4 Building Boost Binaries with <aclass="reference"href="../tools/build/index.html">Boost.Build</a></a></h2>
<p>Like an IDE, <aclass="reference"href="../tools/build/index.html">Boost.Build</a> is a system for developing, testing, and
installing software. Instead of using a GUI, though, <aclass="reference"href="../tools/build/index.html">Boost.Build</a>
is text-based, like <ttclass="docutils literal"><spanclass="pre">make</span></tt>. <aclass="reference"href="../tools/build/index.html">Boost.Build</a> is written in the
<p>To use <aclass="reference"href="../tools/build/index.html">Boost.Build</a>, you'll need an executable called <ttclass="docutils literal"><spanclass="pre">bjam</span></tt>, the
<pclass="first sidebar-title">Using command-line tools in Windows</p>
<p>In Windows, a command-line tool is invoked by typing its name,
optionally followed by arguments, into a <em>Command Prompt</em> window
and pressing the Return (or Enter) key.</p>
<p>To open <em>Command Prompt</em>, click the <em>Start</em> menu button, click
<em>Run</em>, type “cmd”, and then click OK.</p>
<p>All commands are executed within the context of a <strong>current
directory</strong> in the filesystem. To set the current directory,
type:</p>
<preclass="literal-block">
cd <em>path</em>\<em>to</em>\<em>some</em>\<em>directory</em>
</pre>
<p>followed by Return. For example,</p>
<preclass="literal-block">
cd <ttclass="docutils literal"><spanclass="pre">C:\Program</span><spanclass="pre">Files\boost\</span></tt><ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt>
</pre>
<p>One way to name a directory you know about is to write</p>
<preclass="literal-block">
%HOMEDRIVE%%HOMEPATH%\<em>directory-name</em>
</pre>
<p>which indicates a sibling folder of your “My Documents” folder.</p>
<pclass="last">Long commands can be continued across several lines by typing
backslashes at the ends of all but the last line. Many of the
examples on this page use that technique to save horizontal
space.</p>
</div>
<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 the
<aclass="reference"href="http://www.boost.org/doc/html/jam/building.html">instructions</a> given in the <aclass="reference"href="../tools/jam/index.html">Boost.Jam documentation</a>.</p>
<p><ttclass="docutils literal"><spanclass="pre">bjam</span></tt> is a command-line tool. To build Boost binaries, you'll
invoke <ttclass="docutils literal"><spanclass="pre">bjam</span></tt> with the current directory set to the Boost root,
and with options described in the following sections.</p>
</div>
<divclass="section">
<h3><aclass="toc-backref"href="#id33"id="identify-your-toolset"name="identify-your-toolset"><spanid="toolset-name"></span><spanid="toolset"></span>4.4.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 apend 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="#id34"id="select-a-build-directory"name="select-a-build-directory"><spanid="id10"></span><spanid="build-directory"></span>4.4.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
<p>For example, on Windows, your session might look like:</p>
<preclass="literal-block">
C:WINDOWS> cd <ttclass="docutils literal"><spanclass="pre">C:\Program</span><spanclass="pre">Files\boost\</span></tt><ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt>
<p>You already have the Boost headers on your system (in the
<ttclass="docutils literal"><spanclass="pre">boost/</span></tt> subdirectory of your Boost distribution), so if you
prefer not to create an additional copy, instead of installing
Boost you can simply “stage” the Boost binaries, which leaves them
in the <ttclass="docutils literal"><spanclass="pre">stage/</span></tt> subdirectory of your chosen <aclass="reference"href="#build-directory">build directory</a>:</p>
<h3><aclass="toc-backref"href="#id37"id="select-a-prefix-directory"name="select-a-prefix-directory"><spanid="id11"></span><spanid="prefix-directory"></span>4.4.6 Select a Prefix Directory</a></h3>
<p>Choose a <strong>prefix directory</strong>. The installation process will
leave you with the following subdirectories of the prefix directory:</p>
<ulclass="simple">
<li><ttclass="docutils literal"><spanclass="pre">lib</span></tt>, containing the Boost binaries</li>
<li><ttclass="docutils literal"><spanclass="pre">include/</span></tt><ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt>, containing the Boost headers.</li>
</ul>
<p>Change your current directory to the Boost root directory and
invoke <ttclass="docutils literal"><spanclass="pre">bjam</span></tt> as follows:</p>
<p>For example, on Windows your session might look like:</p>
<preclass="literal-block">
C:WINDOWS> cd <ttclass="docutils literal"><spanclass="pre">C:\Program</span><spanclass="pre">Files\boost\</span></tt><ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt>
<h1><aclass="toc-backref"href="#id38"id="linking-a-program-with-a-boost-library"name="linking-a-program-with-a-boost-library">5 Linking A Program with 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">Boost.Regex</a> library, which has a
<p>Most Windows compilers and linkers have so called “auto-linking
support,” which is used by many Boost libraries to eliminate the
second challenge. Special code in Boost header files detects your
compiler options and uses that information to encode the name of
the correct library into your object files; the linker selects the
library with that name from the directories you've told it to
search.</p>
<divclass="note">
<pclass="first admonition-title">Note</p>
<p>As of this writing, a few Boost libraries don't support
auto-linking:</p>
<ulclass="last simple">
<li>Boost.Python</li>
<li>…others?…</li>
</ul>
</div>
<divclass="section">
<h3><aclass="toc-backref"href="#id40"id="visual-c-command-line"name="visual-c-command-line">5.1.1 Visual C++ Command Line</a></h3>
<p>For example, we can compile and link the above program from the
Visual C++ command-line by simply adding the <strong>bold</strong> text below to
the command line we used earlier, assuming your Boost binaries are
in <ttclass="docutils literal"><spanclass="pre">C:\Program</span><spanclass="pre">Files\boost\</span></tt><ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt>:</p>
Directories</em>, enter the path to the Boost binaries,
e.g. <ttclass="docutils literal"><spanclass="pre">C:\Program</span><spanclass="pre">Files\boost\</span></tt><ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt><ttclass="docutils literal"><spanclass="pre">\lib\</span></tt>.</li>
<li>From the <em>Build</em> menu, select <em>Build Solution</em>.</li>
</ol>
<p>To link with a library that doesn't use auto-linking support,
before building (step 3 above), you also need to specify the library
<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="id14"name="id14"><sup>4</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 <ttclass="docutils literal"><spanclass="pre">/</span></tt><em>path</em><ttclass="docutils literal"><spanclass="pre">/</span></tt><em>to</em><ttclass="docutils literal"><spanclass="pre">/</span></tt><ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt> example.cpp -o example <strong>\</strong>
<dd><em>Extension</em>: determined according to the
operating system's usual convention. On Windows, <ttclass="docutils literal"><spanclass="pre">.dll</span></tt>
indicates a shared library and <ttclass="docutils literal"><spanclass="pre">.lib</span></tt> indicates a static or
import library. On most *nix 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. Where supported by *nix toolsets, a
full version extension is added (e.g. ".so.1.34"); a symbolic
link to the library file, named without the trailing version
<tr><tdclass="label"><aclass="fn-backref"href="#id4"name="installer-src">[2]</a></td><td>If you used the <aclass="reference"href="http://www.boost-consulting.com/download.html">Windows installer</a> from Boost
Consulting and deselected “Source and Documentation” (it's
selected by default), you won't see the <ttclass="docutils literal"><spanclass="pre">libs/</span></tt> subdirectory.
That won't affect your ability to use precompiled binaries, but
you won't be able to rebuild libraries from scratch.</td></tr>
<tr><tdclass="label"><aclass="fn-backref"href="#id17"name="debug-abi">[6]</a></td><td>These libraries were compiled without optimization
or inlining, with full debug symbols enabled, and without
<ttclass="docutils literal"><spanclass="pre">NDEBUG</span></tt><ttclass="docutils literal"><spanclass="pre">#define</span></tt>d. All though it's true that sometimes
these choices don't affect binary compatibility with other
compiled code, you can't count on that with Boost libraries.</td></tr>
Generated by <aclass="reference"href="http://docutils.sourceforge.net/">Docutils</a> from <aclass="reference"href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
