+
Getting Started
+
+
+
+
+
+
+
Welcome to the Boost libraries! By the time you've completed this
+tutorial, you'll be at least somewhat comfortable with the contents
+of a Boost distribution and how to go about using it.
+
+
+
+
This document is designed to be an extremely gentle introduction,
+so we included a fair amount of material that may already be very
+familiar to you. To keep things simple, we also left out some
+information intermediate and advanced users will probably want. At
+the end of this document, we'll refer you on to resources that can
+help you pursue these topics further.
+
+
+
+
We use one typographic convention that might not be immediately
+obvious: italic text in examples is meant as a descriptive
+placeholder for something else, usually information that you'll
+provide. For example:
+
+$ echo "My name is your name"
+
+
Here you're expected to imagine replacing the text “your name” with
+your actual name.
+
+
+
+
Getting Started on Unix Variants
+
+
+
+
+
+
+
+
+
The most reliable way to get a copy of Boost is to download a
+distribution from SourceForge:
+
+Download boost_1_34_0.tar.bz2.
+In the directory where you want to put the Boost installation,
+execute
+
+tar --bzip2 -xf /path/to/boost_1_34_0.tar.bz2
+
+
+
+
Other Packages
+
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. If you have
+any trouble, we suggest using an official Boost distribution
+from SourceForge.
+
+
+
+
+
+
+
+
This is is a sketch of the directory structure you'll end up with:
+
+boost_1_34_0/ .................The “boost root directory”
+ index.htm .........A copy of www.boost.org starts here
+ boost/ .........................All Boost Header files
+
+ libs/ ............Tests, .cpps, docs, etc., by library
+ index.html ........Library documentation starts here
+ algorithm/
+ any/
+ array/
+ …more libraries…
+ status/ .........................Boost-wide test suite
+ tools/ ...........Utilities, e.g. bjam, quickbook, bcp
+ more/ ..........................Policy documents, etc.
+ doc/ ...............A subset of all Boost library docs
+
+
+
It's important to note the following:
+
+The path to the boost root directory (often /usr/local/boost_1_34_0) is
+sometimes referred to as $BOOST_ROOT in documentation and
+mailing lists .
+To compile anything in Boost, you need a directory containing
+the boost/ subdirectory in your #include path.
+Since all of Boost's header files have the .hpp extension,
+and live in the boost/ subdirectory of the boost root, your
+Boost #include directives will look like:
+
+#include <boost/whatever.hpp>
+
+or
+
+#include "boost/whatever.hpp"
+
+depending on your religion as regards the use of angle bracket
+includes.
+Don't be distracted by the doc/ subdirectory; it only
+contains a subset of the Boost documentation. Start with
+libs/index.html if you're looking for the whole enchilada.
+
+
+
+
+
+
+
+
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.
+
+
Nothing to Build?
+
Most Boost libraries are header-only: they consist entirely
+of header files containing templates and inline functions, and
+require no separately-compiled library binaries or special
+treatment when linking.
+
+
The only Boost libraries that must be built separately are:
+
+
A few libraries have optional separately-compiled binaries:
+
+- Boost.DateTime has a binary component that is only needed if
+you're using its to_string/from_string or serialization
+features, or if you're targeting Visual C++ 6.x or Borland.
+- Boost.Graph also has a binary component that is only needed if
+you intend to parse GraphViz files.
+- Boost.Test can be used in “header-only” or “separately compiled”
+mode, although separate compilation is recommended for serious
+use.
+
+
+
+
+
+
+
+
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
+writes them to standard output:
+
+#include <boost/lambda/lambda.hpp>
+#include <iostream>
+#include <iterator>
+#include <algorithm>
+
+int main()
+{
+ using namespace boost::lambda;
+ typedef std::istream_iterator<int> in;
+
+ std::for_each(
+ in(std::cin), in(), std::cout << (_1 * 3) << " " );
+}
+
+
Copy the text of this program into a file called example.cpp.
+
Now, in the directory where you saved example.cpp, issue the
+following command:
+
+c++ -I path/to/boost_1_34_0 example.cpp -o example
+
+
To test the result, type:
+
+echo 1 2 3 | ./example
+
+
+
+
+
+
+
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. Errors are another matter. If you're
+seeing compilation errors at this point in the tutorial, check to
+be sure you've copied the example program correctly and that you've
+correctly identified the Boost root directory.
+
+
+
+
+
+
+
+
If you want to use any of the separately-compiled Boost libraries,
+you'll need to acquire library binaries.
+
+
+
Issue the following commands in the shell (don't type $; that
+represents the shell's prompt):
+
+$ cd path/to/boost_1_34_0
+$ ./configure --help
+
+
Select your configuration options and invoke ./configure again
+without the --help option. Unless you have write permission in
+your system's /usr/local/ directory, you'll probably want to at
+least use
+
+$ ./configure --prefix=path/to/installation/prefix
+
+
to install somewhere else. Also, consider using the
+--show-libraries and --with-libraries= options to limit the
+long wait you'll experience if you build everything. Finally,
+
+$ make install
+
+
will leave Boost binaries in the lib/ subdirectory of your
+installation prefix. You will also find a copy of the Boost
+headers in the include/ subdirectory of the installation
+prefix, so you can henceforth use that directory as an #include
+path in place of the Boost root directory.
+
skip to the next step
+
+
+
+
If you're using a compiler other than your system's default, you'll
+need to use Boost.Build to create binaries. You'll also
+use this method if you need a nonstandard build variant (see the
+Boost.Build documentation for more details).
+
+
+
+
Boost.Build is a text-based system for developing, testing, and
+installing software. To use it, you'll need an executable called
+bjam.
+
+
+
bjam is the command-line tool that drives the Boost Build
+system. To build Boost binaries, you'll invoke bjam from the
+Boost root.
+
Boost provides pre-compiled bjam executables for a variety of platforms.
+Alternatively, you can build bjam yourself using these
+instructions.
+
+
+
+
First, find the toolset corresponding to your compiler in the
+following table.
+
+
+
+
+
+
+
+| Toolset
+Name |
+Vendor |
+Notes |
+
|---|
+
+
+| acc |
+Hewlett Packard |
+Only very recent versions are
+known to work well with Boost |
+
+| borland |
+Borland |
+ |
+
+| como |
+Comeau Computing |
+Using this toolset may
+require configuring another
+toolset to act as its backend |
+
+| cw |
+Metrowerks/FreeScale |
+The CodeWarrior compiler. We
+have not tested versions of
+this compiler produced since
+it was sold to FreeScale. |
+
+| dmc |
+Digital Mars |
+As of this Boost release, no
+version of dmc is known to
+handle Boost well. |
+
+| darwin |
+Apple Computer |
+Apple's version of the GCC
+toolchain with support for
+Darwin and MacOS X features
+such as frameworks. |
+
+| gcc |
+The Gnu Project |
+Includes support for Cygwin
+and MinGW compilers. |
+
+| hp_cxx |
+Hewlett Packard |
+Targeted at the Tru64
+operating system. |
+
+| intel |
+Intel |
+ |
+
+| kylix |
+Borland |
+ |
+
+| msvc |
+Microsoft |
+ |
+
+| qcc |
+QNX Software Systems |
+ |
+
+| sun |
+Sun |
+Only very recent versions are
+known to work well with
+Boost. |
+
+| vacpp |
+IBM |
+The VisualAge C++ compiler. |
+
+
+
+
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. msvc-7.1 or gcc-3.4.
+
+
Note
+
if you built bjam 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.
+
+
+
+
+
Boost.Build will place all intermediate files it generates while
+building into the build directory. If your Boost root
+directory is writable, this step isn't strictly necessary: by
+default Boost.Build will create a bin.v2/ subdirectory for that
+purpose in your current working directory.
+
+
+
+
Change your current directory to the Boost root directory and
+invoke bjam as follows:
+
+bjam --build-dir=build-directory --toolset=toolset-name stage
+
+
For example, your session might look like this:
+
+$ cd ~/boost_1_34_0
+$ bjam --build-dir=/tmp/build-boost --toolset=gcc
+
+
+
+
+
Boost.Build will place the Boost binaries in the stage/
+subdirectory of your build directory.
+
+
Note
+
bjam is case-sensitive; it is important that all the
+parts shown in bold type above be entirely lower-case.
+
+
For a description of other options you can pass when invoking
+bjam, type:
+
+bjam --help
+
+
In particular, to limit the amount of time spent building, you may
+be interested in:
+
+- reviewing the list of library names with --show-libraries
+- limiting which libraries get built with the --with-library-name or --without-library-name options
+- choosing a specific build variant by adding release or
+debug to the command line.
+
+
+
+
+
+
During the process of building Boost libraries, you can expect to
+see some messages printed on the console. These may include
+
+Notices about Boost library configuration—for example, the Regex
+library outputs a message about ICU when built without Unicode
+support, and the Python library may be skipped without error (but
+with a notice) if you don't have Python installed.
+Messages from the build tool that report the number of targets
+that were built or skipped. Don't be surprised if those numbers
+don't make any sense to you; there are many targets per library.
+Build action messages describing what the tool is doing, which
+look something like:
+
+toolset-name.c++ long/path/to/file/being/built
+
+Compiler warnings.
+
+
+
+
+
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 here. Install the relevant development
+packages for libz and libbz2 if you need those features. Other
+errors when building Boost libraries are cause for concern.
+
If it seems like the build system can't find your compiler and/or
+linker, consider setting up a user-config.jam file as described
+in the Boost.Build documentation. If that isn't your problem or
+the user-config.jam file doesn't work for you, please address
+questions about configuring Boost for your compiler to the
+Boost.Build mailing list.
+
+
+
+
+
+
+
+
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 Boost.Regex library, which has a
+separately-compiled binary component.
+
+#include <boost/regex.hpp>
+#include <iostream>
+#include <string>
+
+int main()
+{
+ std::string line;
+ boost::regex pat( "^Subject: (Re: |Aw: )*(.*)" );
+
+ while (std::cin)
+ {
+ std::getline(std::cin, line);
+ boost::smatch matches;
+ if (boost::regex_match(line, matches, pat))
+ std::cout << matches[2] << std::endl;
+ }
+}
+
+
There are two main challenges associated with linking:
+
+- Tool configuration, e.g. choosing command-line options or IDE
+build settings.
+- Identifying the library binary, among all the build variants,
+whose compile configuration is compatible with the rest of your
+project.
+
+
There are two main ways to link to libraries:
+
+You can specify the full path to each library:
+
+$ c++ -I path/to/boost_1_34_0 example.cpp -o example \
+ ~/boost/lib/libboost_regex-gcc-3.4-mt-d-1_34.a
+
+You can separately specify a directory to search (with -Ldirectory) and a library name to search for (with -llibrary, dropping the filename's leading lib and trailing
+suffix (.a in this case):
+
+$ c++ -I path/to/boost_1_34_0 example.cpp -o example \
+ -L~/boost/lib/ -lboost_regex-gcc-3.4-mt-d-1_34
+
+As you can see, this method is just as terse as method A for one
+library; it really pays off when you're using multiple
+libraries from the same directory. Note, however, that if you
+use this method with a library that has both static (.a) and
+dynamic (.so) builds, the system may choose one
+automatically for you unless you pass a special option such as
+-static on the command line.
+
+
In both cases above, the bold text is what you'd add to the
+command lines we explored earlier.
+
+
+
+
+
+
In order to choose the right binary for your build configuration
+you need to know how Boost binaries are named. Each library
+filename is composed of a common sequence of elements that describe
+how it was built. For example,
+libboost_regex-vc71-mt-d-1_34.lib can be broken down into the
+following elements:
+
+- lib
+- Prefix: except on Microsoft Windows, every Boost library
+name begins with this string. On Windows, only ordinary static
+libraries use the lib prefix; import libraries and DLLs do
+not.
+- boost_regex
+- Library name: all boost library filenames begin with boost_.
+- -vc71
+- Toolset tag: identifies the toolset and version used to build
+the binary.
+- -mt
+- Threading tag: indicates that the library was
+built with multithreading support enabled. Libraries built
+without multithreading support can be identified by the absence
+of -mt.
+- -d
+ABI tag: encodes details that affect the library's
+interoperability with other compiled code. For each such
+feature, a single letter is added to the tag:
+
+
+
+
+
+
+
+| Key |
+Use this library when: |
+
|---|
+
+
+| s |
+linking statically to the C++ standard library and compiler runtime support
+libraries. |
+
+| g |
+using debug versions of the standard and runtime support libraries. |
+
+| y |
+using a special debug build of Python. |
+
+| d |
+building a debug version of your code. |
+
+| p |
+using the STLPort standard library rather than the default one supplied with
+your compiler. |
+
+| n |
+using STLPort's deprecated “native iostreams” feature. |
+
+
+
+
+For example, if you build a debug version of your code for use
+with debug versions of the static runtime library and the
+STLPort standard library in “native iostreams” mode,
+the tag would be: -sgdpn. If none of the above apply, the
+ABI tag is ommitted.
+- -1_34
+- Version tag: the full Boost release number, with periods
+replaced by underscores. For example, version 1.31.1 would be
+tagged as "-1_31_1".
+- .lib
+- Extension: determined according to the operating system's usual
+convention. On most *nix platforms the extensions are .a
+and .so for static libraries (archives) and shared libraries,
+respectively. On Windows, .dll indicates a shared library
+and—except for static libraries built by gcc toolset, whose
+names always end in .a``— ``.lib indicates a static or import
+library. Where supported by *nix toolsets, a full version
+extension is added (e.g. ".so.1.34") and a symbolic link to the
+library file, named without the trailing version number, will
+also be created.
+
+
+
+
+
+
+
+
To test our subject extraction, we'll filter the following text
+file. Copy it out of your browser and save it as jayne.txt:
+
+To: George Shmidlap
+From: Rita Marlowe
+Subject: Will Success Spoil Rock Hunter?
+---
+See subject.
+
+
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
+LD_LIBRARY_PATH, but on MacOS it's DYLD_LIBRARY_PATH, and
+on Cygwin it's simply PATH. In most shells other than csh
+and tcsh, you can adjust the variable as follows (again, don't
+type the $—that represents the shell prompt):
+
+$ VARIABLE_NAME=path/to/lib/directory:${VARIABLE_NAME}
+$ export VARIABLE_NAME
+
+
On csh and tcsh, it's
+
+$ setenv VARIABLE_NAME path/to/lib/directory:${VARIABLE_NAME}
+
+
Once the necessary variable (if any) is set, you can run your
+program as follows:
+
+$ path/to/compiled/example < path/to/jayne.txt
+
+
The program should respond with the email subject, “Will Success
+Spoil Rock Hunter?”
+
+
+
+
+
+
+
+
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 Boost Users'
+mailing list.
+
+
+
Onward
+
+Good luck, and have fun!
+—the Boost Developers
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Getting Started on Windows
+
+
+
+
+
+
A note to Cygwin and MinGW users
+
If you plan to use your tools from the Windows command prompt,
+you're in the right place. If you plan to build from the Cygwin
+bash shell, you're actually running on a POSIX platform and
+should follow the instructions for getting started on Unix
+variants. Other command shells, such as MinGW's MSYS, are
+not supported—they may or may not work.
+
+
+
+
+
The easiest way to get a copy of Boost is to use the installer
+provided by Boost Consulting. We especially recommend this
+method if you use Microsoft Visual Studio .NET 2003 or Microsoft
+Visual Studio 2005, because the installer can download and install
+precompiled library binaries, saving you the trouble of building
+them yourself. To complete this tutorial, you'll need to at least
+install the Boost.Regex binaries when given the option.
+
If you're using an earlier version of Visual Studio or some other
+compiler, or if you prefer to build everything yourself, you can
+download boost_1_34_0.exe and run it to install a complete Boost
+distribution.
+
+
+
+
+
+
+
This is is a sketch of the directory structure you'll end up with:
+
+boost_1_34_0\ .................The “boost root directory”
+ index.htm .........A copy of www.boost.org starts here
+ boost\ .........................All Boost Header files
+ lib\ .....................precompiled library binaries
+ libs\ ............Tests, .cpps, docs, etc., by library
+ index.html ........Library documentation starts here
+ algorithm\
+ any\
+ array\
+ …more libraries…
+ status\ .........................Boost-wide test suite
+ tools\ ...........Utilities, e.g. bjam, quickbook, bcp
+ more\ ..........................Policy documents, etc.
+ doc\ ...............A subset of all Boost library docs
+
+
+
It's important to note the following:
+
+The path to the boost root directory (often C:\Program Files\boost\boost_1_34_0) is
+sometimes referred to as $BOOST_ROOT in documentation and
+mailing lists .
+To compile anything in Boost, you need a directory containing
+the boost\ subdirectory in your #include path. Specific steps for setting up #include
+paths in Microsoft Visual Studio follow later in this document;
+if you use another IDE, please consult your product's
+documentation for instructions.
+Since all of Boost's header files have the .hpp extension,
+and live in the boost\ subdirectory of the boost root, your
+Boost #include directives will look like:
+
+#include <boost/whatever.hpp>
+
+or
+
+#include "boost/whatever.hpp"
+
+depending on your religion as regards the use of angle bracket
+includes. Even Windows users can (and, for
+portability reasons, probably should) use forward slashes in
+#include directives; your compiler doesn't care.
+Don't be distracted by the doc\ subdirectory; it only
+contains a subset of the Boost documentation. Start with
+libs\index.html if you're looking for the whole enchilada.
+
+
+
+
+
+
+
+
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.
+
+
Nothing to Build?
+
Most Boost libraries are header-only: they consist entirely
+of header files containing templates and inline functions, and
+require no separately-compiled library binaries or special
+treatment when linking.
+
+
The only Boost libraries that must be built separately are:
+
+
A few libraries have optional separately-compiled binaries:
+
+- Boost.DateTime has a binary component that is only needed if
+you're using its to_string/from_string or serialization
+features, or if you're targeting Visual C++ 6.x or Borland.
+- Boost.Graph also has a binary component that is only needed if
+you intend to parse GraphViz files.
+- Boost.Test can be used in “header-only” or “separately compiled”
+mode, although separate compilation is recommended for serious
+use.
+
+
+
+
+
+
+
+
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
+writes them to standard output:
+
+#include <boost/lambda/lambda.hpp>
+#include <iostream>
+#include <iterator>
+#include <algorithm>
+
+int main()
+{
+ using namespace boost::lambda;
+ typedef std::istream_iterator<int> in;
+
+ std::for_each(
+ in(std::cin), in(), std::cout << (_1 * 3) << " " );
+}
+
+
Copy the text of this program into a file called example.cpp.
+
+
Note
+
To build the examples in this guide, you can use an
+Integrated Development Environment (IDE) like Visual Studio, or
+you can issue commands from the command prompt. Since every
+IDE and compiler has different options and Microsoft's are by
+far the dominant compilers on Windows, we only give specific
+directions here for Visual Studio 2005 and .NET 2003 IDEs and
+their respective command prompt compilers (using the command
+prompt is a bit simpler). If you are using another compiler or
+IDE, it should be relatively easy to adapt these instructions to
+your environment.
+
+
+
+
+
+From Visual Studio's File menu, select New > Project…
+In the left-hand pane of the resulting New Project dialog,
+select Visual C++ > Win32.
+In the right-hand pane, select Win32 Console Application
+(VS8.0) or Win32 Console Project (VS7.1).
+In the name field, enter “example”
+Right-click example in the Solution Explorer pane and
+select Properties from the resulting pop-up menu
+In Configuration Properties > C/C++ > General > Additional Include
+Directories, enter the path to the Boost root directory, for example
+
+C:\Program Files\boost\boost_1_34_0
+
+In Configuration Properties > C/C++ > Precompiled Headers, change
+Use Precompiled Header (/Yu) to Not Using Precompiled
+Headers.
+Replace the contents of the example.cpp generated by the IDE
+with the example code above.
+From the Build menu, select Build Solution.
+
+
To test your application, hit the F5 key and type the following
+into the resulting window, followed by the Return key:
+
+1 2 3
+
+
Then hold down the control key and press "Z", followed by the
+Return key.
+
skip to the next step
+
+
+
+
From your computer's Start menu, if you are a Visual
+Studio 2005 user, select
+
+All Programs > Microsoft Visual Studio 2005
+> Visual Studio Tools > Visual Studio 2005 Command Prompt
+
or, if you're a Visual Studio .NET 2003 user, select
+
+All Programs > Microsoft Visual Studio .NET 2003
+> Visual Studio .NET Tools > Visual Studio .NET 2003 Command Prompt
+
to bring up a special command prompt window set up for the
+Visual Studio compiler. In that window, set the current
+directory to a suitable location for creating some temporary
+files and type the following command followed by the Return key:
+
+cl /EHsc /I path\to\boost_1_34_0 path\to\example.cpp
+
+
To test the result, type:
+
+echo 1 2 3 | example
+
+
+
+
+
+
+
+
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. Errors are another matter. If you're
+seeing compilation errors at this point in the tutorial, check to
+be sure you've copied the example program correctly and that you've
+correctly identified the Boost root directory.
+
+
+
+
+
+
+
+
If you want to use any of the separately-compiled Boost libraries,
+you'll need to acquire library binaries.
+
+
+
The installer supplied by Boost Consulting will download and
+install pre-compiled binaries into the lib\ subdirectory of the
+boost root, typically C:\Program Files\boost\boost_1_34_0\lib\. If you installed
+all variants of the Boost.Regex binary, you're done with this
+step. Otherwise, please run the installer again and install them
+now.
+
skip to the next step
+
+
+
+
If you're using an earlier version of Visual C++, or a compiler
+from another vendor, you'll need to use Boost.Build to create your
+own binaries.
+
+
+
+
Boost.Build is a text-based system for developing, testing, and
+installing software. To use it, you'll need an executable called
+bjam.
+
+
+
+
First, find the toolset corresponding to your compiler in the
+following table.
+
+
+
+
+
+
+
+| Toolset
+Name |
+Vendor |
+Notes |
+
|---|
+
+
+| acc |
+Hewlett Packard |
+Only very recent versions are
+known to work well with Boost |
+
+| borland |
+Borland |
+ |
+
+| como |
+Comeau Computing |
+Using this toolset may
+require configuring another
+toolset to act as its backend |
+
+| cw |
+Metrowerks/FreeScale |
+The CodeWarrior compiler. We
+have not tested versions of
+this compiler produced since
+it was sold to FreeScale. |
+
+| dmc |
+Digital Mars |
+As of this Boost release, no
+version of dmc is known to
+handle Boost well. |
+
+| darwin |
+Apple Computer |
+Apple's version of the GCC
+toolchain with support for
+Darwin and MacOS X features
+such as frameworks. |
+
+| gcc |
+The Gnu Project |
+Includes support for Cygwin
+and MinGW compilers. |
+
+| hp_cxx |
+Hewlett Packard |
+Targeted at the Tru64
+operating system. |
+
+| intel |
+Intel |
+ |
+
+| kylix |
+Borland |
+ |
+
+| msvc |
+Microsoft |
+ |
+
+| qcc |
+QNX Software Systems |
+ |
+
+| sun |
+Sun |
+Only very recent versions are
+known to work well with
+Boost. |
+
+| vacpp |
+IBM |
+The VisualAge C++ compiler. |
+
+
+
+
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. msvc-7.1 or gcc-3.4.
+
+
Note
+
if you built bjam 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.
+
+
+
+
+
Boost.Build will place all intermediate files it generates while
+building into the build directory. If your Boost root
+directory is writable, this step isn't strictly necessary: by
+default Boost.Build will create a bin.v2/ subdirectory for that
+purpose in your current working directory.
+
+
+
+
Change your current directory to the Boost root directory and
+invoke bjam as follows:
+
+bjam --build-dir=build-directory --toolset=toolset-name stage
+
+
For example, your session might look like this:
+
+C:WINDOWS> cd C:\Program Files\boost\boost_1_34_0
+C:\Program Files\boost\boost_1_34_0> bjam ^
+More? --build-dir=%TEMP%\build-boost ^
+More? --toolset=msvc stage
+
+
+
+
+
Boost.Build will place the Boost binaries in the stage\
+subdirectory of your build directory.
+
+
Note
+
bjam is case-sensitive; it is important that all the
+parts shown in bold type above be entirely lower-case.
+
+
For a description of other options you can pass when invoking
+bjam, type:
+
+bjam --help
+
+
In particular, to limit the amount of time spent building, you may
+be interested in:
+
+- reviewing the list of library names with --show-libraries
+- limiting which libraries get built with the --with-library-name or --without-library-name options
+- choosing a specific build variant by adding release or
+debug to the command line.
+
+
+
+
+
+
During the process of building Boost libraries, you can expect to
+see some messages printed on the console. These may include
+
+Notices about Boost library configuration—for example, the Regex
+library outputs a message about ICU when built without Unicode
+support, and the Python library may be skipped without error (but
+with a notice) if you don't have Python installed.
+Messages from the build tool that report the number of targets
+that were built or skipped. Don't be surprised if those numbers
+don't make any sense to you; there are many targets per library.
+Build action messages describing what the tool is doing, which
+look something like:
+
+toolset-name.c++ long/path/to/file/being/built
+
+Compiler warnings.
+
+
+
+
+
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 here. Install the relevant development
+packages for libz and libbz2 if you need those features. Other
+errors when building Boost libraries are cause for concern.
+
If it seems like the build system can't find your compiler and/or
+linker, consider setting up a user-config.jam file as described
+in the Boost.Build documentation. If that isn't your problem or
+the user-config.jam file doesn't work for you, please address
+questions about configuring Boost for your compiler to the
+Boost.Build mailing list.
+
+
+
+
+
+
+
+
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 Boost.Regex library, which has a
+separately-compiled binary component.
+
+#include <boost/regex.hpp>
+#include <iostream>
+#include <string>
+
+int main()
+{
+ std::string line;
+ boost::regex pat( "^Subject: (Re: |Aw: )*(.*)" );
+
+ while (std::cin)
+ {
+ std::getline(std::cin, line);
+ boost::smatch matches;
+ if (boost::regex_match(line, matches, pat))
+ std::cout << matches[2] << std::endl;
+ }
+}
+
+
There are two main challenges associated with linking:
+
+- Tool configuration, e.g. choosing command-line options or IDE
+build settings.
+- Identifying the library binary, among all the build variants,
+whose compile configuration is compatible with the rest of your
+project.
+
+
+
Auto-Linking
+
Most Windows compilers and linkers have so-called “auto-linking
+support,” which eliminates 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.
+
+
+
+
Starting with the header-only example project we created
+earlier:
+
+- Right-click example in the Solution Explorer pane and
+select Properties from the resulting pop-up menu
+- In Configuration Properties > Linker > Additional Library
+Directories, enter the path to the Boost binaries,
+e.g. C:\Program Files\boost\boost_1_34_0\lib\.
+- From the Build menu, select Build Solution.
+
+
skip to the next step
+
+
+
+
For example, we can compile and link the above program from the
+Visual C++ command-line by simply adding the bold text below to
+the command line we used earlier, assuming your Boost binaries are
+in C:\Program Files\boost\boost_1_34_0\lib:
+
+cl /EHsc /I path\to\boost_1_34_0 example.cpp ^
+ /link /LIBPATH: C:\Program Files\boost\boost_1_34_0\lib
+
+
+
Note
+
If—like Visual C++—your compiler supports auto-linking,
+you can probably ignore the next section.
+
skip to the next step
+
+
+
+
+
+
Note
+
If, like Visual C++, your compiler supports auto-linking,
+you can probably skip to the next step.
+
+
+
+
+
+
+
In order to choose the right binary for your build configuration
+you need to know how Boost binaries are named. Each library
+filename is composed of a common sequence of elements that describe
+how it was built. For example,
+libboost_regex-vc71-mt-d-1_34.lib can be broken down into the
+following elements:
+
+- lib
+- Prefix: except on Microsoft Windows, every Boost library
+name begins with this string. On Windows, only ordinary static
+libraries use the lib prefix; import libraries and DLLs do
+not.
+- boost_regex
+- Library name: all boost library filenames begin with boost_.
+- -vc71
+- Toolset tag: identifies the toolset and version used to build
+the binary.
+- -mt
+- Threading tag: indicates that the library was
+built with multithreading support enabled. Libraries built
+without multithreading support can be identified by the absence
+of -mt.
+- -d
+ABI tag: encodes details that affect the library's
+interoperability with other compiled code. For each such
+feature, a single letter is added to the tag:
+
+
+
+
+
+
+
+| Key |
+Use this library when: |
+
|---|
+
+
+| s |
+linking statically to the C++ standard library and compiler runtime support
+libraries. |
+
+| g |
+using debug versions of the standard and runtime support libraries. |
+
+| y |
+using a special debug build of Python. |
+
+| d |
+building a debug version of your code. |
+
+| p |
+using the STLPort standard library rather than the default one supplied with
+your compiler. |
+
+| n |
+using STLPort's deprecated “native iostreams” feature. |
+
+
+
+
+For example, if you build a debug version of your code for use
+with debug versions of the static runtime library and the
+STLPort standard library in “native iostreams” mode,
+the tag would be: -sgdpn. If none of the above apply, the
+ABI tag is ommitted.
+- -1_34
+- Version tag: the full Boost release number, with periods
+replaced by underscores. For example, version 1.31.1 would be
+tagged as "-1_31_1".
+- .lib
+- Extension: determined according to the operating system's usual
+convention. On most *nix platforms the extensions are .a
+and .so for static libraries (archives) and shared libraries,
+respectively. On Windows, .dll indicates a shared library
+and—except for static libraries built by gcc toolset, whose
+names always end in .a``— ``.lib indicates a static or import
+library. Where supported by *nix toolsets, a full version
+extension is added (e.g. ".so.1.34") and a symbolic link to the
+library file, named without the trailing version number, will
+also be created.
+
+
+
+
+
+
+
+
To test our subject extraction, we'll filter the following text
+file. Copy it out of your browser and save it as jayne.txt:
+
+To: George Shmidlap
+From: Rita Marlowe
+Subject: Will Success Spoil Rock Hunter?
+---
+See subject.
+
+
Now, in a command prompt window, type:
+
+path\to\compiled\example < path\to\jayne.txt
+
+
The program should respond with the email subject, “Will Success
+Spoil Rock Hunter?”
+
+
+
+
+
+
+
+
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 Boost Users'
+mailing list.
+
+
+
Onward
+
+Good luck, and have fun!
+—the Boost Developers
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Getting Started