diff --git a/getting_started.html b/getting_started.html index fb9c89c..882d780 100644 --- a/getting_started.html +++ b/getting_started.html @@ -1,1238 +1,1253 @@ - - + + - Getting Started - - - - - + Getting Started + + + + + - - - - + +
-
+ + - - -
+ - - - - -
- - - - -
-

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

-
-
-
+ + + + + +
+ + + + +
+

Home
+ . Libraries
+ . People
+ . FAQ
+ . More

+
+
+ + + -

Getting Started

+

Getting Started

- -

Introduction

+

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:

+

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. +
      +
    1. Download Boost.
    2. -
    3. Install Boost.Jam.
    4. +
    5. Install Boost.Jam.
    6. -
    7. Configure your compiler toolset.
    8. +
    9. Configure your compiler toolset.
    10. -
    11. Go to Boost distribution directory.
    12. +
    13. Go to Boost distribution directory.
    14. -
    15. Build and install.
    16. -
    +
  3. Build and install.
  4. +
-

Download

+

Download

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

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

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

+

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

+

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

+

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.

+

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

+

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.

+

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

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.

+

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:

+

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

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

+

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. If - you need an image of the whole CVS tree, Boost Consulting provides an hourly - snapshot in - .tar.bz2 format. +

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. If you need an + image of the whole CVS tree, Boost Consulting provides an hourly + snapshot in + .tar.bz2 format. -

Documentation generated from BoostBook in - CVS

+

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.

+

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

+

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.

+

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.

- - - +
2
+ + - - -
+ 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 neccessary 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.
+ The 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 neccessary 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

+

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:

+

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

    Supported Toolsets

    - - - - - - - -
    3The following toolsets are supported by Boost.Build. For - information about configuring each - toolset, click its name in the leftmost column.
    +
  3. 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:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    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.
    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)
    mipsproSGI MIPSpro - C and C++
    msvcMicrosoft Visual - C++ version 6 command-line tools. NOTE; For version 7.x (the .NET - series) use the vc7 or vc7.1 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 - vc7.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.
    vc7.1Microsoft Visual - C++ command-line tools from Visual Studio .NET 2003.
    vc7.1-stlportMicrosoft Visual - C++ command-line tools from Visual Studio .NET 2003 + - STLPort.
    - -

    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 speicfied - 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:\tools\python on Win32.
    - Default; /usr/local on Unix, Linux, etc.
    - Default; /usr on Cygwin.
    --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.
    - -

    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. - -
    3. libboost_date_time-gcc-mt-d-1_31.so
    4. - -
    5. libboost_date_time-gcc-1_31.so
    6. - -
    7. libboost_date_time-gcc-mt-1_31.so
    8. - -
    9. libboost_date_time-gcc-d-1_31.a
    10. - -
    11. libboost_date_time-gcc-mt-d-1_31.a
    12. - -
    13. libboost_date_time-gcc-1_31.a
    14. - -
    15. libboost_date_time-gcc-mt-1_31.a
      -
    16. -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - - - - -
    · 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:

    - - - -

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

    - -
+ +

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 or vc7.1 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 + vc7.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.
vc7.1Microsoft Visual + C++ command-line tools from Visual Studio .NET 2003.
vc7.1-stlportMicrosoft Visual + C++ command-line tools from Visual Studio .NET 2003 + STLPort.
+ +

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 speicfied 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:\tools\python on Win32.
+ Default; /usr/local on Unix, Linux, etc.
+ Default; /usr on Cygwin.
--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.
+ +

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. + +
  3. libboost_date_time-gcc-mt-d-1_31.so
  4. + +
  5. libboost_date_time-gcc-1_31.so
  6. + +
  7. libboost_date_time-gcc-mt-1_31.so
  8. + +
  9. libboost_date_time-gcc-d-1_31.a
  10. + +
  11. libboost_date_time-gcc-mt-d-1_31.a
  12. + +
  13. libboost_date_time-gcc-1_31.a
  14. + +
  15. libboost_date_time-gcc-mt-1_31.a
  16. +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + +
· 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
  • +

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

    -
  • lib*.lib
  • - + -

    Toolset

    +

    Library Name

    -

    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:

    +

    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
    borland
    + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - -
    TOOLS Namebcb
    Abbreviation
    como
    borlandcomo
    bcb
    como-win32
    comocomo
    como
    cwpro8
    como-win32cw8
    como
    cwpro9
    cwcw9
    cw
    darwin
    darwinosx
    osx
    edg
    dmcedg
    dmc
    gcc
    dmc-stlportgcc
    dmc
    gcc-stlport
    edggcc
    edg
    gcc-nocygwin
    gccgcc
    gcc
    intel-linux
    gcc-stlportil
    gcc
    intel-win32
    gcc-nocygwiniw
    gcc
    kcc
    intel-linuxkcc
    il
    kylix
    intel-win32bck
    iw
    metrowerks
    kcccw
    kcc
    mingw
    kylixmgw
    bck
    mipspro
    mingwmp
    mgw
    msvc
    mingw-stlportvc
    mgw
    msvc-stlport
    mipsprovc
    mp
    sunpro
    msvcsw
    vc
    tru64cxx
    msvc-stlporttru
    vc
    tru64cxx65
    sunprotru
    sw
    vacpp
    tru64cxxxlc
    tru
    vc7
    tru64cxx65vc
    tru
    vc7.1
    vacppvc
    xlc
    Others
    vc7The first part of the toolset name.
    + vc + -

    Threading

    + + vc7-stlport -

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

    + vc + -

    Runtime

    + + vc7.1 -

    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.

    + vc + - - - + + - - + + - - + + - - + + +
    Key
    vc7.1-stlportFeature
    vc
    s
    OthersStatic link to runtime.
    The first part of the toolset name.
    - - g +

    Threading

    - Debug runtime. - +

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

    - - y +

    Runtime

    - Debug Python system. - +

    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.

    - - d + + + - - + + - - + + - - + + - - + + - - -
    KeyDebug enabled code.
    Feature
    p
    sSTLport runtime, instead of the vendor toolset runtime.
    Static link to runtime.
    n
    gSTLport runtime using the "native" IO streams instead of the - STLport IO streams.
    + Debug runtime. + -

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

    + + y -

    Boost Version

    + Debug Python system. + -

    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". The patch version number is not included because it is - assumed that patch versions are upward compatible.

    + + d -

    Library Type

    + Debug enabled code. + -

    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.

    + + p -

    Additional Steps

    + STLport runtime, instead of the vendor toolset runtime. + -

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

    + + n - -
    +

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

    -

    Revised 11 - July, 2004 -

    +

    Boost Version

    -

    Copyright © Rene Rivera 2003.
    - Copyright © Jens Maurer 2001.

    +

    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". + The patch version number is not included because it is assumed that patch + versions are upward compatible.

    -

    Use, modification, and distribution are subject to the Boost - Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at www.boost.org/LICENSE_1_0.txt)

    - +

    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.

    + +

    Additional + Steps

    + +

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

    + + +
    + +

    Revised 3 +October, 2004

    + +

    Copyright © Rene Rivera 2003.
    + Copyright © Jens Maurer 2001.

    + +

    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)

    + -