diff --git a/Jamfile.v2 b/Jamfile.v2 index de53650..634be5d 100644 --- a/Jamfile.v2 +++ b/Jamfile.v2 @@ -15,6 +15,8 @@ for local b in $(bases) { html $(b) : $(b).rst : + # "PYTHONPATH=~/src/boost/tools && python ~/src/boost/tools/litre/active-rst.py" + # "-gdt --writer=html --source-url="./$(b).rst" --link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript "$(stylesheet) "-gdt --source-url="./$(b).rst" --link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript "$(stylesheet) ; } diff --git a/getting_started.html b/getting_started.html index fc0965e..01f0d0c 100644 --- a/getting_started.html +++ b/getting_started.html @@ -1,1554 +1,956 @@ - - - + + + - Getting Started - - - - - + + +Boost Getting Started + - - - - - - - - -
- - - - - -
- - - - -
-

. Home
- . Libraries
- . People
- . FAQ
- . More

-
-
-
- -

Getting Started

- - - -

Introduction

- -

These instructions are intended to help you get started using the Boost - Libraries. This walks you through getting, building, and installing the - libraries. To summarize these are the steps to get Boost built and - installed:

- -
    -
  1. Download Boost.
    2. - -
  2. Install Boost.Jam.
    3. - -
  3. Configure your compiler toolset.
    4. - -
  4. Go to Boost distribution directory.
    5. - -
  5. Build and install.
    6. -
- -

Download

- - - - - - - -
- 1The Boost Libraries are distributed through the SourceForge file - distribution system. Click here to - download releases from SourceForge. And - unpack the release to a convenient location.
- -

The Boost release includes all of the libraries and other material from - the web site. It is available in ZIP, TAR.GZ, and TAR.BZ2 formats. Past - releases are also available.

It is also possible to download current - snapshots of work-in-progress from Boost's CVS - repository. - -

.zip file

The .zip format is widely - supported by both free decoders and commercial compress/archive utilities. - If you don't already have a .zip file decoder, download one from the - Info-ZIP web site, which supplies - versions for many operating systems. - -

Text file line endings in the .zip file are as supplied by each library - developer.  This works fine for Windows, but not for Unix/Linux.  - The .tar.gz and .tar.bz2 files supply Unix/Linux friendly line endings.

- -

.tar.gz and .tar.bz2 files

- -

The .tar.gz format is widely supported on Unix/Linux platforms. Some - Windows compress/archive utilities can read the format as well.  - Because the gzip format compresses the archive as a single file rather than - compressing each file individually, the .tar.gz file is smaller that the - .zip file.

- -

The .tar.bz2 format is becoming widely available on Unix/Linux platforms - and is built into many tar utilities. This format differs for the .tar.gz - format in the compression used, which is considerably better and therefore - creates smaller files.

- -

Text file line endings in the .tar.gz and .tar.bz2 files have been - converted to newlines for ease of use on Unix/Linux platforms.

- -

Boost CVS Repository

- -

All Boost files, including the entire distribution tree including web - site HTML is maintained in a CVS repository. Command line, GUI, or browser - access is available.

- -

Boost CVS access via command line or graphical clients

For those - who have CVS clients installed, the libraries are also available from the - public Boost CVS - repository. Free command line clients (often already installed on - Linux/Unix systems) are available for many systems, and free GUI clients - are available for Windows, Mac, and other systems. - -

See the much improved CVS documentation (Section - F) from SourceForge, which includes links to the home pages for various GUI - and command line clients.

- -

The general procedure for command-line clients is something like - this:

- -
- cvs -d:pserver:anonymous@boost.cvs.sourceforge.net:/cvsroot/boost - login
- [Hit <return> when it asks for a password]
- cvs -z3 -d:pserver:anonymous@boost.cvs.sourceforge.net:/cvsroot/boost - checkout boost
- cvs -d:pserver:anonymous@boost.cvs.sourceforge.net:/cvsroot/boost - logout -
Read the manual for your CVS client for further information. - -

This access is read-only; if you are a library author and wish to have - CVS write access, please contact one of the moderators.

- -

Boost CVS access via web Browser

For access to the CVS archive from any modern web - browser, you can also use the web - browser  interface.  Try one of the color diffs to see how a - file has changed over time. Note: this interface is only suitable - for viewing individual files and their revision histories. - -

Documentation generated from - BoostBook in CVS

- -

Some of the Boost documentation is generated from BoostBook XML source stored in the CVS - repository, and will not appear directly in the CVS tree as readable HTML. - View a nightly build of the generated HTML on the - Nightly Generated Documentation page. Where generated HTML is missing - from the CVS tree, an attempt has been made to include redirection to this - nightly build, but if you are away from an internet connection you may want - to download the generated documentation archive from the aforementioned - page so you can browse those documents offline.

- -

Preparation

- -

The recommended way to build and install the Boost Libraries is to use - Boost.Build, the Boost - Build system. The rest of these instructions explain that use, but it is up - to you to use this method, or not. Note that some of the libraries also - include non Boost.Build makefiles and/or project files. But all include the - needed files for building with Boost.Build.

- - - - - - - -
- 2The build system uses Boost.Jam, an extension of the - Perforce Jam - portable make replacement. The recommended way to get Boost.Jam - if you are using a Boost distribution is to - download a prebuilt executable from SourceForge. If a - prebuilt executable is not provided for your platform or you are using - Boost's sources in an unreleased state, it may be necessary to build bjam - from sources included in the Boost source tree. To install - Boost.Jam, copy the bjam executable to a location accessible - in your PATH.
- -

Configuring the tools

- -

Before using Boost.Build you will need to configure the compiler tools - you are using. The build system's toolsets are designed to work in either - of two ways:

- -
    -
  1. The user sets up all of the environment for each toolset he wants to - use in the normal way. For example, for Microsoft VC++, ...VC98/Bin or - .../VC7/Bin is in the PATH environment variable, VCVARS32.BAT or - VSVARS32.BAT has been invoked, etc. For Metrowerks CodeWarrior, cwenv.bat - or equivalent has been called and ...Other Metrowerks Tools/Command Line - Tools is in the path. Many Unix operating systems come preconfigured this - way and require no user intervention.
    -
    2. - -
  2. The user doesn't want his environment cluttered with settings or has - nonstandard installations for some of his tools. Instead, he or she sets - variables which point to the toolset installation directories, either in - the command shell environment or on the bjam command-line. - These variables are used by the build system to locate the tools and - invoke the necessary setup. To set the variables on the bjam - command-line you use the "-s" option. For example:
    -
    - bjam "-sGCC_ROOT_DIRECTORY=/usr/local/gcc-3.3.2"
    -
    - Some variables, like the toolset TOOLS variable, can accept - multiple values separated by spaces. Others, like the path above, can - contain spaces. For such circumstances you should use quotes appropriate - for your command interpreter.
    3. -
- -

Supported Toolsets

- - - - - - - -
- 3The following toolsets are supported by Boost.Build. For - information about configuring each toolset, - click its name in the leftmost column.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TOOLS NameDescription
borlandBorland C++
comoComeau C++ compiler - front-end for non-Windows platforms
como-win32Comeau C++ compiler - front-end for Windows, using Microsoft Visual C++as a back-end.
cwMetrowerks CodeWarrior Pro - 6.x, 7.x, 8.x, and 9.x command-line tools
darwinApple Darwin OS hosted GNU GCC
dmcDigital Mars C++.
dmc-stlportDigital Mars C++, using - the STLport standard library - implementation
edgEdison Design Group compiler - front-end (evaluation version)
gccGNU GCC on Unix and Cygwin.
gcc-stlportGNU GCC on Unix and Cygwin, using the STLport standard library - implementation
gcc-nocygwinGNU GCC Cygwin command line compiler tools running in "no-cygwin" - mode (produces commercially redistributable objects)
intel-linuxIntel C++ for - Linux
intel-win32Intel C++ for - Windows using the Dinkumware standard library in the Intel-required - Microsoft Visual C++ 6 - or 7 installation
kccKAI C++
kylixBorland C++ for Linux - (Kylix).
mingwGNU GCC and associated tools in MinGW configuration (produces commercially - redistributable objects)
mingw-stlportGNU GCC and associated tools in MinGW configuration (produces commercially - redistributable objects), using the STLport standard library - implementation
mipsproSGI MIPSpro - C and C++
msvcMicrosoft Visual - C++ version 6 command-line tools. NOTE; For version 7.x (the .NET - series) use the vc7, vc-7_1, or vc-8_0 toolsets below.
msvc-stlportMicrosoft Visual - C++ version 6 command-line tools, using the STLport standard library implementation. - NOTE; For version 7.x (the .NET series) use the vc7-stlport or - vc-7_1-stlport toolsets below.
sunproSunPRO C++ - compiler
tru64cxxCompaq C++ for - Tru64 UNIX (versions prior to 6.5)
tru64cxx65Compaq C++ - Version 6.5 for Tru64 UNIX
vacppIBM Visual Age - C++ command-line tools
vc7Microsoft Visual - C++ command-line tools from Visual Studio .NET.
vc7-stlportMicrosoft Visual - C++ command-line tools from Visual Studio .NET + STLPort.
vc-7_1Microsoft Visual - C++ command-line tools from Visual Studio .NET 2003.
vc-7_1-stlportMicrosoft Visual - C++ command-line tools from Visual Studio .NET 2003 + STLPort.
vc-8_0Microsoft Visual - C++ command-line tools from Visual Studio .NET 2005.
- -

Build and Install

- -

The common build and install process is driven by the top-level build - file (Jamfile).

- - - - - - - -
- 4 -

First you need to change to the directory where you have the Boost - distribution you downloaded. For example:

- -
-

chdir boost-1.31.0

-
-
- -

The default build and install attempts to build all available libraries - and install to default locations the libraries and Boost header files. On - Unix systems the default install location is "/usr/local", and on - Windows systems the default is "C:\Boost". Within those - directories libraries are installed to the "lib" subdirectory, and - headers to an "include/boost-1_31" subdirectory, the version will - reflect the distribution you are installing.

- - - - - - - -
- 5 - Invoke the build system, specifying the toolset(s) you wish to use, to build and install. For - example for GNU/GCC. - -
-

bjam "-sTOOLS=gcc" install

-
- -

Or if you are interested only in the built libraries you can have - them built and collected to a common directory without - installation.

- -
-

bjam "-sTOOLS=gcc" stage

-
-
- -

The build and install system can be controlled through a set of options - similar in style to GNU configure options. The options allow you to, among - other things, change the install location, disable building of libraries, - etc. You can see a summary of the available options by invoking "bjam - --help". The full invocation takes the form:

- -
-

bjam [options...] [install|stage]

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Action 
noneOnly builds the Boost libraries. This - lets you do the first part of what the install action normally - does without copying the built libraries to the install location.
installBuilds and installs Boost libraries and - headers.
stageBuilds the Boost libraries and copies - them into a common directory.
Option 
--helpShows a short summary of the options and - syntax of the command.
- -sTOOLS=<toolsets>The list of tools to compile with. - Usually only one is needed.
--prefix=PREFIXInstall architecture independent files - here.
- Default; C:\Boost on Win32.
- Default; /usr/local on Unix. Linux, etc.
- --exec-prefix=EPREFIXInstall architecture dependent files - here.
- Default; PREFIX
--libdir=DIRInstall libraries here.
- Default; EPREFIX/lib
--includedir=DIRInstall source headers here. The Boost - headers are installed in a version specific - "boost-<version>" subdirectory in this directory.
- Default; PREFIX/include
--builddir=DIRBuild in this location instead of - building within the distribution tree. This moves where the sources for - the libraries are compiled to before they are installed. - Recommended!
--stagedir=DIRWhen staging only, with the - "stage" action, copy to the given location.
- Default; ./stage
- --without-<library>Do not build, stage, or install the - specified library.
- --with-<library>Build, stage, or install the specified - library. This changes the default from trying to build all possible - libraries, to only building the specified libraries.
- --with-python-root[=PYTHON_ROOT]Build Boost.Python libraries with the - Python devel packages located at PYTHON_ROOT. The Boost.Python - libraries are built only if the build can find the Python development - package at this location.
- Default; C:\Python24 on Win32.
- Default; /usr on Unix, Linux, Cygwin, etc.
- --with-python-version[=2.4]Build Boost.Python libraries with the - Python version indicated.
- Default; 2.4.
--with-pydebugBuild Boost.Python libraries using the - Python debug runtime. This builds an additional set of libraries for - use with the debug version of Python. The regular versions of the - Boost.Python libraries are also built.
-sHAVE_ICU=1Build Boost.Regex libraries with Unicode - support provided by the ICU - libraries. ICU must have been built with the same compiler that you - are using to build Boost, and must be installed into your compiler's - include and library search paths. See the Boost.Regex installation - documentation for more information.
- -sICU_PATH=pathBuild Boost.Regex libraries with Unicode - support provided by the ICU - libraries. ICU must have been built with the same compiler that you - are using to build Boost, and must have been built (or installed to) - directory path. For example if you configured ICU with - --prefix=/usr/local/icu/3.3, then use - -sICU_PATH=/usr/local/icu/3.3. See the Boost.Regex installation - documentation for more information.
-sNO_COMPRESSION=1Build Boost.Iostreams without support for - the compression filters which rely on the non-Boost libraries zlib and - libbz2. If you use Windows, this option is enabled by default. If you - use UNIX, the compression filters will likely work with no - configuration, so this option should not be necessary. For full details - see Boost.Iostreams - Installation.
- -

There are additional options as supported by Boost.Build and Boost.Jam. Of the additional - options perhaps the most imporant is "-sBUILD=<features/variants>" - which lets you override what is built by default. The - "<features/variants>" value is a list, separated by spaces, - of build requests. Features take the form of a tag and a value or values. - And variants are single symbolic names for a collection of features. For - example the default is to request "debug release - <runtime-link>static/dynamic <threading>single/multi", in - which "debug" and "release" are variants, and the rest - features with two values each.

- -

If you have some feedback about the build and install process please - drop us a line at the Boost.Build - mailing list. We are particularly interested if it works for your - platform and if it there is anything that you feel could be done - better.

- -

Results

- -

The results of building come in to forms: static libraries, and dynamic - libraries. Depending on the platform the libraries produced have different - names to accommodate the platform requirements. For a single Boost library - the build with the default will produce eight different libraries. For - example building the Boost.Datetime library on Unix type system it would - produce:

- -
    -
  1. libboost_date_time-gcc-d-1_31.so
    2. - -
  2. libboost_date_time-gcc-mt-d-1_31.so
    3. - -
  3. libboost_date_time-gcc-1_31.so
    4. - -
  4. libboost_date_time-gcc-mt-1_31.so
    5. - -
  5. libboost_date_time-gcc-d-1_31.a
    6. - -
  6. libboost_date_time-gcc-mt-d-1_31.a
    7. - -
  7. libboost_date_time-gcc-1_31.a
    8. - -
  8. libboost_date_time-gcc-mt-1_31.a
    9. -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - -
· Library Prefix
- 		 
lib - - - - -
· Library Name
-
boost_date_time - - - - -
· Toolset
-
-gcc - - - - -
· Threading
-
-mt - - - - -
· Runtime
-
-d - - - - -
· Boost Version
-
-1_31 - - - - -
· Library Type
-
.a 
- -

Library Prefix

- -

The "lib" prefix on the libraries is a requirement on many platforms, - like Unix, and on others like GCC running on Windows. The prefix is - therefore added to all libraries on Unix type systems, and to static - libraries on Windows. That is on Unix shared libraries and static libraries - (object archives) are named respectively:

- -
    -
  • lib*.so
    • - -
  • lib*.a
    • -
- -

On Windows shared libraries do not have the prefix to differentiate the - import libraries from static libraries. Consequently on Windows the - libraries are named:

- - - - - - - - - - - - - - - - - - - -
*.dllDynamic library version.
*.libImport library for the dll.
lib*.libStatic library version.

-
- -

Library Name

- -

For Boost libraries the name has the "boost_" prefix to - separate them from other libraries in your system.

- -

Toolset

- -

The toolset name is an abbreviation based on the compiler you are - building with. The abbreviation is composed of a short, 2 to 4 characters, - tag for the compiler and a version number of the compiler's major and minor - revision (if available). For example if your toolset is - "gcc-3_2_3" the toolset tag would be "gcc32". The toolset - abbreviations used are as follows:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TOOLS NameAbbreviation
borlandbcb
comocomo
como-win32como
cwcw
darwinosx
dmcdmc
dmc-stlportdmc
edgedg
gccgcc
gcc-stlportgcc
gcc-nocygwingcc
intel-linuxil
intel-win32iw
kcckcc
kylixbck
mingwmgw
mingw-stlportmgw
mipspromp
msvcvc
msvc-stlportvc
sunprosw
tru64cxxtru
tru64cxx65tru
vacppxlc
vc7vc
vc7-stlportvc
vc-7_1vc
vc-7_1-stlportvc
vc-8_0vc
OthersThe first part of the toolset name.
- -

Threading

- -

This tag indicates if the library is compiled with threading support. If - threading is enabled "-mt" is added, otherwise nothing is - added.

- -

Runtime

- -

This specifies the type of runtime the library was compiled against, and - the type of code that is compiled. More commonly this encodes the ABI - variation used in the code. For each feature of the runtime system and code - compilation option a single letter is added to this tag.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
KeyFeature
sStatic link to runtime.
gDebug runtime.
yDebug Python system.
dDebug enabled code.
pSTLport runtime, instead of the vendor toolset runtime.
nSTLport runtime using the "native" IO streams instead of the - STLport IO streams.
- -

For example if you compile debug code for STLport using native IO - streams, and statically link to the debug runtime the tag would be: - "-sgdpn".

- -

Boost Version

- -

This is the short label for the version of the Boost Libraries. The - major and minor version numbers are taken together separated by an - underscore. For example version 1.31.0 would be tagged as "-1_31". - For patch versions the patch number is also included, for example a version - of 1.31.1 would be tagged as "-1_31_1".

- -

Library Type

- -

The extension holds the type of library. This follows the platform - requirements. On Windows this is ".dll" for shared libraries, and - ".lib" for static libraries including import libraries. On Unix - this is ".a" for static libraries (archives), and ".so" for shared - libraries. For toolsets that support it in Unix they will also have a full - version extension (for example ".so.1.31.0") with a symbolic link - for the un-versioned library.

- -

Automatic Linking on Windows

- -

For most Boost libraries that have separate source, the correct build - variant is linked against automatically when you include one of that - library's header files.  For this feature to work, your compiler must - support the #pragma comment(lib, name) feature (Microsoft - Visual C++, Intel C++, Metrowerks C++ , and Borland C++ all support - this).

- -

If you are linking to a dynamic runtime, then you can choose to link to - either a static or a dynamic Boost library, the default is to do a static - link.  You can alter this for a specific library whatever by - defining BOOST_WHATEVER_DYN_LINK to force Boost library whatever - to be linked dynamically.  Alternatively you can force all Boost - libraries to dynamic link by defining BOOST_ALL_DYN_LINK.

- -

This feature can be disabled for Boost library whatever by - defining BOOST_WHATEVER_NO_LIB, or for all of Boost by defining - BOOST_ALL_NO_LIB.

- -

If you want to observe which libraries are being linked against then - defining BOOST_LIB_DIAGNOSTIC will cause the auto-linking code to emit a - #pragma message each time a library is selected for - linking.

- -

There are some Boost libraries (Boost.Test is one one special case), - where automatic linking is not supported for technical reasons: please - consult the documentation for each of the libraries you are using for more - information, and the Boost.Config - documentation for more information on configuration macros.  The - following table shows the current supported configurations, (Boost - libraries not listed here consist of headers only):

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
LibraryStatic LinkDynamic LinkDefault linkageAutomatic library selectionComments
Date-TimeYesYesstaticYes 
FilesystemYes -

Yes

- 		staticYes 
GraphYesNostaticNoThe separate Graph library source is needed only when reading an AT&T graphviz - file.
IostreamsYes -

Yes

- 		staticYes 
Program OptionsYesYesstaticYes 
PythonYesYesdynamicNoSince all Python extensions are DLL's it makes sense to dynamic - link to the Boost Python library by default (static linking is - only really an option if you are embedding python).
RegexYesYesstaticYes 
SerializationYesYesstaticYes 
SignalsYesYesstaticYes 
TestYesNostaticNoWhich library you link to depends upon which program entry point - you define, rather than which Boost.Test features you use.
ThreadPartialYesstatic (Visual C++), otherwise dynamicYesFor technical reasons static linking is supported on only one - Windows compiler (Visual C++).
WaveYesYesstaticYes 

-
- -

Additional - Steps

- -

Depending on your platform and configuration you may need to perform - some additional configuration to get Boost to build and install.

- -
    -
  • Configure the boost - source code. This step should not be required on the vast majority of - platforms, but if you're trying to build Boost on an untested or - unsupported platform it may be necessary.
    -
    • - -
  • If Boost.Build has problems detecting your Python installation it - will print a short messages about how to configure for finding the Python - installation. For more information, see these detailed instructions.
    • -
-
- -

Revised $Date$

- -

Copyright © Rene Rivera 2003.
- Copyright © Jens Maurer 2001.
- Copyright © John Maddock 2004.

- -

Distributed under the Boost Software License, Version 1.0. (See - accompanying file LICENSE_1_0.txt or copy - at www.boost.org/LICENSE_1_0.txt)

+ +
+

Getting Started

+ +
+

Contents

+ +
+ +
+

1   Introduction

+

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.

+
+

1.1   What's Here

+

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.

+
+
+

1.2   Preliminaries

+

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.

+

We identify Unix and its variants such as Linux, FreeBSD, and MacOS +collectively as *nix. If you're not targeting Microsoft Windows, +the instructions for *nix users will probably work for you. +Cygwin users working from the Cygwin bash prompt should also +follow the *nix instructions. To use your Cygwin compiler from +the Windows command prompt, follow the instructions for Windows +users.

+

Although Boost supports a wide variety of Windows compilers +(including older Microsoft compilers), most instructions for +Windows users cover only the Visual Studio .NET 2003 and Visual +Studio 2005. We hope that gives you enough information to adapt +them for your own compiler or IDE.

+
+

Onward

+
+

Good luck, and have fun!

+

—the Boost Developers

+
+
+
+
+
+

2   Get Boost

+

There are basically three ways to get Boost on your system:

+
    +

  1. Windows Installer: Boost Consulting provides an installer +for Windows platforms that installs a complete Boost +distribution, plus optional precompiled library binaries for +Visual Studio, and (optionally) a prebuilt version of the +bjam build tool.

    +
    2. +

  2. Download: users of other platforms—and Windows +users who prefer to build everything from scratch—can download +a complete Boost distribution from SourceForge.

    + +
      +

    • Windows: Download and run boost_1_34_0.exe +to unpack the distribution.1

      +
      • +

    • *nix: Download boost_1_34_0.tar.bz2. Then, in the +directory where you want to put the Boost installation, +execute

      +
      +tar --bzip2 -xf /path/to/boost_1_34_0.tar.bz2
+
      +
      • +
    +
    3. +

  3. Boost packages 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.2

    +
    4. +
+
+
+

3   The Structure of a Boost Distribution

+

This is is a sketch of the directory structure you'll get when you +unpack your Boost installation (windows users replace forward +slashes with backslashes):

+
+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 library3
+     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
+
+
+

Header Organization

+

The organization of Boost library headers isn't entirely uniform, +but most libraries follow a few patterns:

+
    +
  • Some older libraries and most very small libraries place all +public headers directly into boost/.
    • +
  • Most libraries' public headers live in a subdirectory of +boost/ named after the library. For example, you'll find +the Type Traits Library's is_void.hpp header in +boost/type_traits/is_void.hpp.
    • +
  • Some libraries have an “aggregate header” in boost/ that +#includes all of the library's other headers. For +example, Boost.Python's aggregate header is +boost/python.hpp.
    • +
  • Most libraries place private headers in a subdirectory called +detail/ or aux_/. Don't look in these directories and +expect to find anything you can use.
    • +
+
+

A few things are worth noting right off the bat:

+
    +

  1. The path to the “boost root directory” is sometimes referred to +as $BOOST_ROOT in documentation and mailing lists. If you +used the Windows installer, that will usually be C:\Program Files\boost\boost_1_34_0.

    +
    2. +

  2. To compile anything in Boost, you need a directory containing +the boost/ subdirectory in your #include path. For most +compilers, that means adding

    +
    +-I/path/to/boost_1_34_0
+
    +

    to the command line. 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.

    +
    3. +

  3. 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"
+
    +
    4. +
+
+depending on your religion as regards the use of angle bracket +includes. Even Windows users can use forward slashes in +#include directives; your compiler doesn't care.
+
    +
  1. 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.
    2. +
+
+
+

4   Header-Only Libraries

+

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 can't be used without separate +compilation are:

+
    +
  • Boost.Filesystem
    • +
  • Boost.IOStreams
    • +
  • Boost.ProgramOptions
    • +
  • Boost.Python
    • +
  • Boost.Regex
    • +
  • Boost.Serialization
    • +
  • Boost.Signals
    • +
  • Boost.Test
    • +
  • Boost.Thread
    • +
  • Boost.Wave
    • +
+

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 parse GraphViz +files.

+ +
+
+

5   Build a Simple Program Using Boost

+

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.

+
+

5.1   Build on *nix

+

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
+
+

next...

+
+
+

5.2   Build from the Visual Studio Command Prompt

+

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, type the following command and +hit the return key:

+
+cl /EHsc /Ipath\to\boost_1_34_0 path\to\example.cpp
+
+

To test the result, type:

+
+echo 1 2 3 | example
+
+

next...

+
+
+

5.3   Build in the Visual Studio IDE

+
    +
  • 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, e.g. +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.5
    • +
  • 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.

+
+
+

5.4   Errors and Warnings

+

Don't be alarmed if you see compiler warnings from Boost headers. +We try to eliminate them, but doing so isn't always practical.4

+

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.

+
+
+
+

6   Get Boost Library Binaries

+

If you want to use any of the separately-compiled Boost libraries, +you'll need library binaries.

+
+

6.1   Install Visual Studio Binaries

+

The Windows 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\.

+

next...

+
+
+

6.2   Build and Install *nix Binaries

+

Issue the following commands in the shell (don't type $; it +represents the shell's prompt):

+
+$ cd /path/to/boost_1_34_0
+$ ./configure --help
+
+

Select your configuration options and invoke ./configure again. +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. Finally,

+
+$ make install
+
+

which 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.

+

next...

+
+
+

6.3   Build and Install Other Binaries

+

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 +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.

+
+

Get 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.

+
+
+

Identify Your Toolset

+

First, find the toolset corresponding to your compiler in the +following table.

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Toolset +NameVendorNotes
accHewlett PackardOnly very recent versions are +known to work well with Boost
borlandBorland 
comoComeau ComputingUsing this toolset may +require configuring another +toolset to act as its backend
cwMetrowerks/FreeScaleThe CodeWarrior compiler. We +have not tested versions of +this compiler produced since +it was sold to FreeScale.
dmcDigital MarsAs of this Boost release, no +version of dmc is known to +handle Boost well.
darwinApple ComputerApple's version of the GCC +toolchain with support for +Darwin and MacOS X features +such as frameworks.
gccThe Gnu ProjectIncludes support for Cygwin +and MinGW compilers.
hp_cxxHewlett PackardTargeted at the Tru64 +operating system.
intelIntel 
kylixBorland 
msvcMicrosoft 
qccQNX Software Systems 
sunSunOnly very recent versions are +known to work well with +Boost.
vacppIBMThe VisualAge C++ compiler.
+

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. 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.

+
+
+
+

Select a Build Directory

+

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.

+
+
+

Invoke bjam

+

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, on Windows, your session might look like:

+
+C:WINDOWS> cd C:\Program Files\boost\boost_1_34_0
+C:\Program Files\boost\boost_1_34_0> bjam \
+  --build-dir=%TEMP%\build-boost          \
+  --toolset=msvc stage
+
+

And on Unix:

+
+$ cd ~/boost_1_34_0
+$ bjam --build-dir=~/build-boost --prefix=~/boost
+
+

In either case, 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
+
+
+
+
+

6.4   Expected Build Output

+

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.

    +
    • +
+
+
+

6.5   In Case of Build Errors

+

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.

+
+
+
+

7   Link Your Program to a Boost Library

+

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:

+
    +
  1. Tool configuration, e.g. choosing command-line options or IDE +build settings.
    2. +
  2. Identifying the library binary, among all the build variants, +whose compile configuration is compatible with the rest of your +project.
    3. +
+
+

Note

+

Boost.Python users should read that library's own build +documentation as there are several library-specific issues to +consider.

+
+
+

7.1   Link to a Boost Library on Windows

+

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.

+
+

Link to a Boost Library from the Visual Studio Command Prompt

+

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
+
+

next...

+
+
+

Link to a Boost Library in the Visual Studio IDE

+

Starting with the header-only example project we created +earlier:

+
    +
  1. Right-click example in the Solution Explorer pane and +select Properties from the resulting pop-up menu
    2. +
  2. 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\.
    3. +
  3. From the Build menu, select Build Solution.
    4. +
+

next...

+
+
+
+

7.2   Link to a Boost Library On *nix

+

There are two main ways to link to libraries:

+
    +

  1. 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
+
    +
    2. +

  2. You can separately specify a directory to search (with -Ldirectory) and a library name to search for (with -llibrary,6 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.

    +
    3. +
+

In both cases above, the bold text is what you'd add to the +command lines we explored earlier.

+
+
+

7.3   Library Naming

+

When auto-linking is not available, you need to know how Boost +binaries are named so you can choose the right one for your build +configuration. 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.7
+
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:

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyUse this library when:
slinking statically to the C++ standard library and compiler runtime support +libraries.
gusing debug versions of the standard and runtime support libraries.
yusing a special debug build of Python.
dbuilding a debug version of your code.8
pusing the STLPort standard library rather than the default one supplied with +your compiler.
nusing STLPort's deprecated “native iostreams” feature.9
+

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 Windows, .dll +indicates a shared library and .lib indicates a static or +import library. On most *nix platforms the extensions are +.a and .so 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 +number, will also be created.
+
+
+
+

7.4   Test Your Program

+

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.
+
+
+

Test Your Program on Microsoft Windows

+

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?”

+
+
+

Test Your Program on *nix

+

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?”

+
+
+
+
+

8   Further Resources

+

This concludes your introduction to Boost and using it with your +programs. Remember that this page is only supposed to get you +started and not describe every detail you might want to know about. +There are lots of resources you can pursue from this point onward. +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.

+ +
+

Note

+

We're also very interested in what sort of material might +be appropriate for a “Book 2” in a Getting Started series.

+
+
+
+

9   Appendix: Using command-line tools in Windows

+

In Windows, a command-line tool is invoked by typing its name, +optionally followed by arguments, into a Command Prompt window +and pressing the Return (or Enter) key.

+

To open Command Prompt, click the Start menu button, click +Run, type “cmd”, and then click OK.

+

All commands are executed within the context of a current +directory in the filesystem. To set the current directory, +type:

+
+cd path\to\some\directory
+
+

followed by Return. For example,

+
+cd C:\Program Files\boost\boost_1_34_0
+
+

One way to name a directory you know about is to write

+
+%HOMEDRIVE%%HOMEPATH%\directory-name
+
+

which indicates a sibling folder of your “My Documents” folder.

+

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.

+
+ + + + + +
[1]If you prefer not to download executable programs, download +boost_1_34_0.zip 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.
+ + + + + +
[2]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 Boost developers' list.
+ + + + + +
[3]If you used the Windows installer from Boost +Consulting and deselected “Source and Documentation” (it's +selected by default), you won't see the libs/ subdirectory. +That won't affect your ability to use precompiled binaries, but +you won't be able to rebuild libraries from scratch.
+ + + + + +
[4]Remember that warnings are specific to each compiler +implementation. The developer of a given Boost library might +not have access to your compiler. Also, some warnings are +extremely difficult to eliminate in generic code, to the point +where it's not worth the trouble. Finally, some compilers don't +have any source code mechanism for suppressing warnings.
+ + + + + +
[5]There's no problem using Boost with precompiled headers; +these instructions merely avoid precompiled headers because it +would require Visual Studio-specific changes to the source code +used in the examples.
+ + + + + +
[6]That option is a dash followed by a lowercase “L” +character, which looks very much like a numeral 1 in some fonts.
+ + + + + +
[7]This convention distinguishes the static version of +a Boost library from the import library for an +identically-configured Boost DLL, which would otherwise have the +same name.
+ + + + + +
[8]These libraries were compiled without optimization +or inlining, with full debug symbols enabled, and without +NDEBUG #defined. 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.
+ + + + + +
[9]This feature of STLPort is deprecated because it's +impossible to make it work transparently to the user; we don't +recommend it.
+
+
+
+
+View document source. +Generated on: 2006-12-11 20:27 UTC. +Generated by Docutils from reStructuredText source. + +