<li><aclass="reference"href="#the-structure-of-a-boost-distribution"id="id31"name="id31">3 The Structure of a Boost Distribution</a></li>
<li><aclass="reference"href="#build-a-simple-program-using-boost"id="id33"name="id33">5 Build a Simple Program Using Boost</a><ulclass="auto-toc">
<li><aclass="reference"href="#build-on-nix"id="id34"name="id34">5.1 Build on *nix</a></li>
<li><aclass="reference"href="#build-from-the-visual-studio-command-prompt"id="id35"name="id35">5.2 Build from the Visual Studio Command Prompt</a></li>
<li><aclass="reference"href="#build-in-the-visual-studio-ide"id="id36"name="id36">5.3 Build in the Visual Studio IDE</a></li>
<li><aclass="reference"href="#errors-and-warnings"id="id37"name="id37">5.4 Errors and Warnings</a></li>
<li><aclass="reference"href="#in-case-of-build-errors"id="id43"name="id43">6.5 In Case of Build Errors</a></li>
</ul>
</li>
<li><aclass="reference"href="#link-your-program-to-a-boost-library"id="id44"name="id44">7 Link Your Program to a Boost Library</a><ulclass="auto-toc">
<li><aclass="reference"href="#link-to-a-boost-library-on-windows"id="id45"name="id45">7.1 Link to a Boost Library on Windows</a></li>
<li><aclass="reference"href="#link-to-a-boost-library-on-nix"id="id46"name="id46">7.2 Link to a Boost Library On *nix</a></li>
<li><aclass="reference"href="#appendix-using-command-line-tools-in-windows"id="id50"name="id50">9 Appendix: Using command-line tools in Windows</a></li>
</ul>
</div>
<!-- ## Update this substitution for each release -->
<li><pclass="first"><strong>Download</strong>: users of other platforms—and Windows
users who prefer to build everything from scratch—can <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.</p>
<!-- ## Update this link for each release -->
<ul>
<li><pclass="first"><strong>Windows</strong>: Download and run <ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt><ttclass="docutils literal"><spanclass="pre">.exe</span></tt>
to unpack the distribution.<aclass="footnote-reference"href="#zip"id="id3"name="id3"><sup>1</sup></a></p>
</li>
<li><pclass="first"><strong>*nix</strong>: 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="literal-block">
tar --bzip2 -xf <em>/path/to/</em><ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt>.tar.bz2
</pre>
</li>
</ul>
</li>
<li><pclass="first"><strong>Boost packages</strong> from RedHat, Debian, or some other
distribution packager: these instructions may not work for you
if you use 3rd party packages, 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="id4"name="id4"><sup>2</sup></a></p>
</li>
</ol>
</div>
<divclass="section">
<h1><aclass="toc-backref"href="#id31"id="the-structure-of-a-boost-distribution"name="the-structure-of-a-boost-distribution">3 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:</span></tt><ttclass="docutils literal"><spanclass="pre">\Program</span></tt>`` <ttclass="docutils literal"><spanclass="pre">\</span><spanclass="pre">``Files</span></tt><ttclass="docutils literal"><spanclass="pre">\boost\</span></tt><ttclass="docutils literal"><spanclass="pre">boost_1_34_0</span></tt>.</p>
<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>The DateTime library has a separately-compiled component that
is only needed if you're using its to/from_string and/or
serialization features or if you're targeting Visual C++ 6.x or
Borland. The Graph library also has a separately-compiled part,
but you won't need it unless you intend to <aclass="reference"href="../libs/graph/doc/read_graphviz.html">parse GraphViz
files</a>.</p>
<!-- ## Keep the list of non-header-only libraries up-to-date -->
</div>
<divclass="section">
<h1><aclass="toc-backref"href="#id33"id="build-a-simple-program-using-boost"name="build-a-simple-program-using-boost">5 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>
<divclass="section">
<h2><aclass="toc-backref"href="#id34"id="build-on-nix"name="build-on-nix"><spanid="unix-header-only"></span>5.1 Build on *nix</a></h2>
<p>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 <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
<h2><aclass="toc-backref"href="#id35"id="build-from-the-visual-studio-command-prompt"name="build-from-the-visual-studio-command-prompt">5.2 Build from the Visual Studio Command Prompt</a></h2>
<p>From your computer's <em>Start</em> menu, 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 <aclass="reference"href="#command-prompt">command prompt</a> window set up for the Visual
Studio compiler. In that window, type the following command and
<h2><aclass="toc-backref"href="#id36"id="build-in-the-visual-studio-ide"name="build-in-the-visual-studio-ide"><spanid="vs-header-only"></span>5.3 Build in the Visual Studio IDE</a></h2>
<p>If you want to use any of the separately-compiled Boost libraries,
you'll need library binaries.</p>
<divclass="section">
<h2><aclass="toc-backref"href="#id39"id="install-visual-studio-binaries"name="install-visual-studio-binaries">6.1 Install Visual Studio 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
<h2><aclass="toc-backref"href="#id40"id="build-and-install-nix-binaries"name="build-and-install-nix-binaries">6.2 Build and Install *nix Binaries</a></h2>
<p>Issue the following commands in the shell (don't type <ttclass="docutils literal"><spanclass="pre">$</span></tt>; it
represents the shell's prompt):</p>
<preclass="literal-block">
<strong>$</strong> cd <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>
<strong>$</strong> ./configure --help
</pre>
<p>Select your configuration options and invoke <ttclass="docutils literal"><spanclass="pre">./configure</span></tt> again.
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 least use</p>
<h2><aclass="toc-backref"href="#id41"id="build-and-install-other-binaries"name="build-and-install-other-binaries">6.3 Build and Install Other Binaries</a></h2>
<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>
<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 <aclass="reference"href="#command-line-tool">command-line tool</a> 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="http://www.boost.org/doc/html/jam/building.html">these
instructions</a>.</p>
</div>
<divclass="section">
<h3><aid="identify-your-toolset"name="identify-your-toolset"><spanid="toolset-name"></span><spanid="toolset"></span>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><aid="select-a-build-directory"name="select-a-build-directory"><spanid="id15"></span><spanid="build-directory"></span>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>In either case, Boost.Build will place the Boost binaries in the
<ttclass="docutils literal"><spanclass="pre">stage/</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
<h2><aclass="toc-backref"href="#id43"id="in-case-of-build-errors"name="in-case-of-build-errors">6.5 In Case of Build Errors</a></h2>
<p>The only error messages you see when building Boost—if any—should
be related to the IOStreams library's support of zip and bzip2
formats as described <aclass="reference"href="file:///home/dave/src/boost/libs/iostreams/doc/installation.html">here</a>. Install the relevant development
packages for libz and libbz2 if you need those features. Other
errors when building Boost libraries are cause for concern.</p>
<p>If it seems like the build system can't find your compiler and/or
linker, consider setting up a <ttclass="docutils literal"><spanclass="pre">user-config.jam</span></tt> file as described
in the <aclass="reference"href="../tools/build/index.html">Boost.Build documentation</a>. If that isn't your problem or
the <ttclass="docutils literal"><spanclass="pre">user-config.jam</span></tt> file doesn't work for you, please address
questions about configuring Boost for your compiler to the
<h1><aclass="toc-backref"href="#id44"id="link-your-program-to-a-boost-library"name="link-your-program-to-a-boost-library">7 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">Boost.Regex</a> library, which has a
<p>There are two main challenges associated with linking:</p>
<olclass="arabic simple">
<li>Tool configuration, e.g. choosing command-line options or IDE
build settings.</li>
<li>Identifying the library binary, among all the build variants,
whose compile configuration is compatible with the rest of your
project.</li>
</ol>
<divclass="note">
<pclass="first admonition-title">Note</p>
<pclass="last"><aclass="reference"href="../libs/python/index.html">Boost.Python</a> users should read that library's own <aclass="reference"href="../libs/python/doc/building.html">build
documentation</a> as there are several library-specific issues to
consider.</p>
</div>
<divclass="section">
<h2><aclass="toc-backref"href="#id45"id="link-to-a-boost-library-on-windows"name="link-to-a-boost-library-on-windows">7.1 Link to a Boost Library on Windows</a></h2>
<h3><aid="link-to-a-boost-library-from-the-visual-studio-command-prompt"name="link-to-a-boost-library-from-the-visual-studio-command-prompt">Link to a Boost Library from the Visual Studio Command Prompt</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
<h3><aid="link-to-a-boost-library-in-the-visual-studio-ide"name="link-to-a-boost-library-in-the-visual-studio-ide">Link to a Boost Library in the Visual Studio IDE</a></h3>
<p>Starting with the <aclass="reference"href="#vs-header-only">header-only example project</a> we created
earlier:</p>
<olclass="arabic simple">
<li>Right-click <strong>example</strong> in the <em>Solution Explorer</em> pane and
select <em>Properties</em> from the resulting pop-up menu</li>
<h2><aclass="toc-backref"href="#id46"id="link-to-a-boost-library-on-nix"name="link-to-a-boost-library-on-nix">7.2 Link to a Boost Library On *nix</a></h2>
<p>There are two main ways to link to libraries:</p>
<olclass="upperalpha">
<li><pclass="first">You can specify the full path to each library:</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>
<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="id21"name="id21"><sup>6</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>
<ttclass="docutils literal"><spanclass="pre">.a</span></tt> and <ttclass="docutils literal"><spanclass="pre">.so</span></tt> for static libraries (archives) and shared
<p>The program should respond with the email subject, “Will Success
Spoil Rock Hunter?”</p>
</div>
<divclass="section">
<h3><aid="test-your-program-on-nix"name="test-your-program-on-nix">Test Your Program on *nix</a></h3>
<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>
<h1><aclass="toc-backref"href="#id49"id="conclusion-and-further-resources"name="conclusion-and-further-resources">8 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.
<h1><aclass="toc-backref"href="#id50"id="appendix-using-command-line-tools-in-windows"name="appendix-using-command-line-tools-in-windows"><spanid="command-line-tool"></span><spanid="command-prompt"></span><spanid="using-command-line-tools-in-windows"></span>9 Appendix: Using command-line tools in Windows</a></h1>
<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>
<tr><tdclass="label"><aclass="fn-backref"href="#id3"name="zip">[1]</a></td><td>If you prefer not to download executable programs, download
<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.</td></tr>
<tr><tdclass="label"><aclass="fn-backref"href="#id5"name="installer-src">[3]</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="#id24"name="debug-abi">[8]</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.
