BGEN

See ./index.html for information about this release. The "Getting Started" 
section is a useful starting place.

---------------------------
Copyright Beman Dawes, 2008

Distributed under the Boost Software License, Version 1.0.
See ./LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt 

# Copyright Vladimir Prus 2002-2006.
# Copyright Dave Abrahams 2005-2006.
# Copyright Rene Rivera 2005-2007.
# Copyright Douglas Gregor 2005.
#
# Distributed under the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)

# Usage:
#
#   b2 [options] [properties] [install|stage]
#
#   Builds and installs Boost.
#
# Targets and Related Options:
#
#   install                 Install headers and compiled library files to the
#   =======                 configured locations (below).
#
#   --prefix=<PREFIX>       Install architecture independent files here.
#                           Default; C:\Boost on Win32
#                           Default; /usr/local on Unix. Linux, etc.
#
#   --exec-prefix=<EPREFIX> Install architecture dependent files here.
#                           Default; <PREFIX>
#
#   --libdir=<DIR>          Install library files here.
#                           Default; <EPREFIX>/lib
#
#   --includedir=<HDRDIR>   Install header files here.
#                           Default; <PREFIX>/include
#
#   stage                   Build and install only compiled library files to the
#   =====                   stage directory.
#
#   --stagedir=<STAGEDIR>   Install library files here
#                           Default; ./stage
#
# Other Options:
#
#   --build-type=<type>     Build the specified pre-defined set of variations of
#                           the libraries. Note, that which variants get built
#                           depends on what each library supports.
#
#                               -- minimal -- (default) Builds a minimal set of
#                               variants. On Windows, these are static
#                               multithreaded libraries in debug and release
#                               modes, using shared runtime. On Linux, these are
#                               static and shared multithreaded libraries in
#                               release mode.
#
#                               -- complete -- Build all possible variations.
#
#   --build-dir=DIR         Build in this location instead of building within
#                           the distribution tree. Recommended!
#
#   --show-libraries        Display the list of Boost libraries that require
#                           build and installation steps, and then exit.
#
#   --layout=<layout>       Determine whether to choose library names and header
#                           locations such that multiple versions of Boost or
#                           multiple compilers can be used on the same system.
#
#                               -- versioned -- Names of boost binaries include
#                               the Boost version number, name and version of
#                               the compiler and encoded build properties. Boost
#                               headers are installed in a subdirectory of
#                               <HDRDIR> whose name contains the Boost version
#                               number.
#
#                               -- tagged -- Names of boost binaries include the
#                               encoded build properties such as variant and
#                               threading, but do not including compiler name
#                               and version, or Boost version. This option is
#                               useful if you build several variants of Boost,
#                               using the same compiler.
#
#                               -- system -- Binaries names do not include the
#                               Boost version number or the name and version
#                               number of the compiler. Boost headers are
#                               installed directly into <HDRDIR>. This option is
#                               intended for system integrators building
#                               distribution packages.
#
#                           The default value is 'versioned' on Windows, and
#                           'system' on Unix.
#
#   --buildid=ID            Add the specified ID to the name of built libraries.
#                           The default is to not add anything.
#
#   --python-buildid=ID     Add the specified ID to the name of built libraries
#                           that depend on Python. The default is to not add
#                           anything. This ID is added in addition to --buildid.
#
#   --help                  This message.
#
#   --with-<library>        Build and install the specified <library>. If this
#                           option is used, only libraries specified using this
#                           option will be built.
#
#   --without-<library>     Do not build, stage, or install the specified
#                           <library>. By default, all libraries are built.
#
# Properties:
#
#   toolset=toolset         Indicate the toolset to build with.
#
#   variant=debug|release   Select the build variant
#
#   link=static|shared      Whether to build static or shared libraries
#
#   threading=single|multi  Whether to build single or multithreaded binaries
#
#   runtime-link=static|shared
#                           Whether to link to static or shared C and C++
#                           runtime.
#

# TODO:
#  - handle boost version
#  - handle python options such as pydebug

import boostcpp ;
import package ;

import sequence ;
import xsltproc ;
import set ;
import path ;
import link ;

path-constant BOOST_ROOT : . ;
constant BOOST_VERSION : 1.55.0 ;
constant BOOST_JAMROOT_MODULE : $(__name__) ;

boostcpp.set-version $(BOOST_VERSION) ;

	
local all-headers =
    [ MATCH .*libs/(.*)/include/boost : [ glob libs/*/include/boost ] ] ;

for dir in $(all-headers)
{
    link-directory $(dir)-headers : libs/$(dir)/include/boost : <location>. ;
    explicit $(dir)-headers ;
}

local numeric-headers =
   [ MATCH .*libs/numeric/(.*)/include/boost : [ glob libs/*/*/include/boost ] ] ;

for dir in $(numeric-headers)
{
    link-directory numeric-$(dir)-headers : libs/numeric/$(dir)/include/boost : <location>. ;
    explicit numeric-$(dir)-headers ;
}

if $(all-headers)
{
    constant BOOST_MODULARLAYOUT : $(all-headers) $(numeric-headers) ;
}
if $(BOOST_MODULARLAYOUT)
{
    echo modularized layout build ;
}

project boost
    : requirements <include>.
      # Disable auto-linking for all targets here, primarily because it caused
      # troubles with V2.
      <define>BOOST_ALL_NO_LIB=1
      # Used to encode variant in target name. See the 'tag' rule below.
      <tag>@$(__name__).tag
      <conditional>@handle-static-runtime
      # The standard library Sun compilers use by default has no chance
      # of working with Boost. Override it.
      <toolset>sun:<stdlib>sun-stlport
      # Comeau does not support shared lib
      <toolset>como:<link>static
      <toolset>como-linux:<define>_GNU_SOURCE=1
      # When building docs within Boost, we want the standard Boost style
      <xsl:param>boost.defaults=Boost
    : usage-requirements <include>.
    : build-dir bin.v2
    ;

# This rule is called by Boost.Build to determine the name of target. We use it
# to encode the build variant, compiler name and boost version in the target
# name.
#
rule tag ( name : type ? : property-set )
{
    return [ boostcpp.tag $(name) : $(type) : $(property-set) ] ;
}

rule handle-static-runtime ( properties * )
{
    # Using static runtime with shared libraries is impossible on Linux, and
    # dangerous on Windows. Therefore, we disallow it. This might be drastic,
    # but it was disabled for a while without anybody complaining.

    # For CW, static runtime is needed so that std::locale works.
    if <link>shared in $(properties) && <runtime-link>static in $(properties) &&
        ! ( <toolset>cw in $(properties) )
    {
        ECHO "error: link=shared together with runtime-link=static is not allowed" ;
        ECHO "error: such property combination is either impossible " ;
        ECHO "error: or too dangerious to be of any use" ;
        EXIT ;
    }
}

all-libraries = [ MATCH .*libs/(.*)/build/.* : [ glob libs/*/build/Jamfile.v2 ]
    [ glob libs/*/build/Jamfile ] ] ;

all-libraries = [ sequence.unique $(all-libraries) ] ;
# The function_types library has a Jamfile, but it's used for maintenance
# purposes, there's no library to build and install.
all-libraries = [ set.difference $(all-libraries) : function_types ] ;

# Setup convenient aliases for all libraries.

local rule explicit-alias ( id : targets + )
{
    alias $(id) : $(targets) ;
    explicit $(id) ;
}

# First, the complicated libraries: where the target name in Jamfile is
# different from its directory name.
explicit-alias prg_exec_monitor : libs/test/build//boost_prg_exec_monitor ;
explicit-alias test_exec_monitor : libs/test/build//boost_test_exec_monitor ;
explicit-alias unit_test_framework : libs/test/build//boost_unit_test_framework ;
explicit-alias bgl-vis : libs/graps/build//bgl-vis ;
explicit-alias serialization : libs/serialization/build//boost_serialization ;
explicit-alias wserialization : libs/serialization/build//boost_wserialization ;
for local l in $(all-libraries)
{
    if ! $(l) in test graph serialization
    {
        explicit-alias $(l) : libs/$(l)/build//boost_$(l) ;
    }
}

alias headers : $(all-headers)-headers numeric-$(numeric-headers)-headers : : : <include>.  ;
explicit headers ;

# Make project ids of all libraries known.
for local l in $(all-libraries)
{
    use-project /boost/$(l) : libs/$(l)/build ;
}

# This rule should be called from libraries' Jamfiles and will create two
# targets, "install" and "stage", that will install or stage that library. The
# --prefix option is respected, but --with and --without options, naturally, are
# ignored.
#
# - libraries -- list of library targets to install.
#
rule boost-install ( libraries * )
{
    package.install install
        : <dependency>/boost//install-proper-headers $(install-requirements)
        : # No binaries
        : $(libraries)
        : # No headers, it is handled by the dependency.
    ;

    install stage : $(libraries) : <location>$(BOOST_STAGE_LOCATE) ;

    module [ CALLER_MODULE ]
    {
        explicit stage ;
        explicit install ;
    }
}

headers =
    # The .SUNWCCh files are present in tr1 include directory and have to be
    # installed (see http://lists.boost.org/Archives/boost/2007/05/121430.php).
    [ path.glob-tree $(BOOST_ROOT)/boost : *.hpp *.ipp *.h *.inc *.SUNWCCh : CVS .svn ]
    [ path.glob-tree $(BOOST_ROOT)/boost/compatibility/cpp_c_headers : c* : CVS .svn ]
    [ path.glob boost/tr1/tr1 : * : bcc32 sun CVS .svn ]
    ;

# Declare special top-level targets that build and install the desired variants
# of the libraries.
boostcpp.declare-targets $(all-libraries) : $(headers) ;

/*=============================================================================
    Copyright 2002 William E. Kempf
    Distributed under the Boost Software License, Version 1.0. (See accompany-
    ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
=============================================================================*/

H1
{
    FONT-SIZE: 200%;
    COLOR: #00008B;
}
H2
{
    FONT-SIZE: 150%;
}
H3
{
    FONT-SIZE: 125%;
}
H4
{
    FONT-SIZE: 108%;
}
BODY
{
    FONT-SIZE: 100%;
    BACKGROUND-COLOR: #ffffff;
    COLOR: #000000;
}
PRE
{
    MARGIN-LEFT: 2em;
    FONT-FAMILY: Courier,
                 monospace;
}
CODE
{
    FONT-FAMILY: Courier,
                 monospace;
}
CODE.as_pre
{
    white-space: pre;
}
.index
{
    TEXT-ALIGN: left;
}
.page-index
{
    TEXT-ALIGN: left;
}
.definition
{
    TEXT-ALIGN: left;
}
.footnote
{
    FONT-SIZE: 66%;
    VERTICAL-ALIGN: super;
    TEXT-DECORATION: none;
}
.function-semantics
{
    CLEAR: left;
}

# Boost.Build support specific for the Boost C++ Libraries.
# Copyright Vladimir Prus 2002-2010.
# Copyright Dave Abrahams 2005-2006.
# Copyright Rene Rivera 2005-2007.
# Copyright Douglas Gregor 2005.
#
# Distributed under the Boost Software License, Version 1.0.
#    (See accompanying file LICENSE_1_0.txt or copy at
#          http://www.boost.org/LICENSE_1_0.txt)

import "class" : new ;
import common ;
import configure ;
import build-system ;
import generate ;
import modules ;
import option ;
import os ;
import package ;
import path ;
import project ;
import regex ;
import set ;
import targets ;


##############################################################################
#
# 0. General setup. Parse options, check them.
#
##############################################################################

BOOST_ROOT = [ modules.binding $(__name__) ] ;
BOOST_ROOT = $(BOOST_ROOT:D) ;

rule set-version ( version )
{
    BOOST_VERSION = $(version) ;

    local version-tag = [ MATCH ^([^.]+)[.]([^.]+)[.]([^.]+) : $(BOOST_VERSION)
        ] ;
    if $(version-tag[3]) = 0
    {
        version-tag = $(version-tag[1-2]) ;
    }
    BOOST_VERSION_TAG = $(version-tag:J=_) ;
}

# Option to choose how many variants to build. The default is "minimal".
build-type = [ option.get build-type ] ;
build-type ?= minimal ;
if ! ( $(build-type) in complete minimal )
{
    EXIT The value of the --build-type option should be either 'complete' or
        'minimal' ;
}

# What kind of layout are we doing?
layout = [ option.get layout : "" ] ;
# On Windows, we used versioned layout by default in order to be compatible with
# autolink. On other systems, we use system layout which is what every other
# program uses. Note that the Windows check is static, and will not be affected
# by specific build properties used.
if ! $(layout)
{
    if [ os.name ] = NT
    {
        layout = versioned ;
    }
    else
    {
        layout = system ;
    }
}
layout-$(layout) = true ;

if $(layout) = system && $(build-type) = complete
{
    ECHO error: Cannot use --layout=system with --build-type complete. ;
    ECHO error: Please use either --layout=versioned or --layout=tagged ;
    ECHO error: if you wish to build multiple variants. ;
    if [ os.name ] != NT
    {
        ECHO error: Note that --layout=system is used by default on Unix
            starting with Boost 1.40. ;
    }
    EXIT ;
}

# Possible stage only location.
stage-locate = [ option.get stagedir ] ;
stage-locate ?= stage ;
BOOST_STAGE_LOCATE = $(stage-locate) ;

# Custom build ID.
build-id = [ option.get buildid ] ;
if $(build-id)
{
    BUILD_ID = [ regex.replace $(build-id) "[*\\/:.\"\' ]" _ ] ;
}

# Python build id (for Python libraries only).
python-id = [ option.get "python-buildid" ] ;
if $(python-id)
{
    PYTHON_ID = [ regex.replace $(python-id) [*\\/:.\"\'] _ ] ;
}


################################################################################
#
# 1. 'tag' function adding decorations suitable to the properties if versioned
# or tagged layout is requested. Called from Jamroot.
#
################################################################################

rule tag ( name : type ? : property-set )
{
    if $(type) in STATIC_LIB SHARED_LIB IMPORT_LIB
    {
        local result ;
        if $(layout) = versioned
        {
            result = [ common.format-name
                <base> <toolset> <threading> <runtime> -$(BOOST_VERSION_TAG)
                -$(BUILD_ID)
                : $(name) : $(type) : $(property-set) ] ;
        }
        else if $(layout) = tagged
        {
            result = [ common.format-name
                <base> <threading> <runtime>
                -$(BUILD_ID)
                : $(name) : $(type) : $(property-set) ] ;
        }
        else if $(layout) = system
        {
            result = [ common.format-name
                <base>
                -$(BUILD_ID)
                : $(name) : $(type) : $(property-set) ] ;
        }
        else
        {
            EXIT error: invalid layout '$(layout:E=)' ;
        }

        # Optionally add version suffix. On NT, library with version suffix will
        # not be recognized by linkers. On CYGWIN, we get strage duplicate
        # symbol errors when library is generated with version suffix. On OSX,
        # version suffix is not needed -- the linker expects the
        # libFoo.1.2.3.dylib format. AIX linkers do not accept version suffixes
        # either. Pgi compilers can not accept a library with version suffix.
        if $(type) = SHARED_LIB &&
          ! [ $(property-set).get <target-os> ] in windows cygwin darwin aix &&
          ! [ $(property-set).get <toolset> ] in pgi
        {
            result = $(result).$(BOOST_VERSION)  ;
        }

        return $(result) ;
    }
}


################################################################################
#
# 2. Declare targets that build and install all libraries. Specifically:
#
#    - 'stage-proper' that puts all libraries in stage/lib
#    - 'install-proper' that install libraries and headers to system location
#    - 'stage-unversioned' that creates links to libraries without boost version
#       in name
#    - 'install-unversioned' which creates unversioned linked to installed
#       libraries.
#
################################################################################

# Worker function suitable to the 'generate' metatarget. Creates a link to
# 'source', striping any version number information from the name.
rule make-unversioned-links ( project name ? : property-set : sources * )
{
    local filter ;
    if [ modules.peek : NT ]
    {
        filter = (.*[.]lib) ;
    }
    else
    {
        filter =
            (.*[.]so)[.0-9]*
            (.*[.]dylib)
            (.*[.]a) ;
    }

    local result ;
    for local s in $(sources)
    {
        local m = [ MATCH ^(.*)-[0-9_]+$(filter)$ : [ $(s).name ] ] ;
        if $(m)
        {
            local ea = [ $(s).action ] ;
            local ep = [ $(ea).properties ] ;
            local a = [ new non-scanning-action $(s) : symlink.ln : $(ep) ] ;
            result += [ new file-target $(m:J=) exact : [ $(s).type ] :
                $(project) : $(a) ] ;
        }
    }
    return $(result) ;
}

rule declare_install_and_stage_proper_targets ( libraries * : headers * )
{
    install-requirements = <install-source-root>$(BOOST_ROOT)/boost ;

    if $(layout-versioned)
    {
        install-requirements +=
            <install-header-subdir>boost-$(BOOST_VERSION_TAG)/boost ;
    }
    else
    {
        install-requirements += <install-header-subdir>boost ;
    }

    if [ os.name ] = NT
    {
        install-requirements += <install-default-prefix>C:/Boost ;
    }
    else
    {
        install-requirements += <install-default-prefix>/usr/local ;
    }

    p = [ project.current ] ;

    # Complete install.
    package.install install-proper
        : $(install-requirements) <install-no-version-symlinks>on
        :
        : libs/$(libraries)/build
        : $(headers)
        ;
    $(p).mark-target-as-explicit install-proper ;

    # Install just library.
    install stage-proper
        : libs/$(libraries)/build
        : <location>$(stage-locate)/lib
          <install-dependencies>on <install-type>LIB
          <install-no-version-symlinks>on
        ;
    $(p).mark-target-as-explicit stage-proper ;

    # Commented out as it does not seem to work. Whoever wrote this originally,
    # left some typos in the code, but when that got corrected and the code got
    # enabled - it started reporting ambiguous/duplicate target Boost Build
    # errors. Anyone requiring unversioned staged libraries needs to correct
    # those errors before reenabling this code. For more detailed information
    # see the related Boost library development mailing list thread at
    # 'http://lists.boost.org/Archives/boost/2012/06/194312.php'.
    #                                                (06.07.2012.) (Jurko)
    #~ if $(layout-versioned) && ( [ modules.peek : NT ] || [ modules.peek : UNIX ] )
    #~ {
    #~     generate stage-unversioned : stage-proper :
    #~         <generating-rule>@boostcpp.make-unversioned-links ;
    #~     $(p).mark-target-as-explicit stage-unversioned ;
    #~
    #~     generate install-unversioned : install-proper :
    #~         <generating-rule>@boostcpp.make-unversioned-links ;
    #~     $(p).mark-target-as-explicit install-unversioned ;
    #~ }
    #~ else
    {
        # Create do-nothing aliases.
        alias stage-unversioned ;
        $(p).mark-target-as-explicit stage-unversioned ;
        alias install-unversioned ;
        $(p).mark-target-as-explicit install-unversioned ;
    }
}


################################################################################
#
#  3. Declare top-level targets 'stage' and 'install'. These examine the
#  --build-type option and, in case it is 'complete', build the 'install-proper'
#  and 'stage-proper' targets with a number of property sets.
#
################################################################################

class top-level-target : alias-target-class
{
    import modules ;

    rule __init__ ( name : project : sources * : requirements *
        : default-build * : usage-requirements * )
    {
        alias-target-class.__init__ $(name) : $(project) : $(sources) :
            $(requirements) : $(default-build) : $(usage-requirements) ;

        self.build-type = [ modules.peek boostcpp : build-type ] ;
        # On Linux, we build the release variant by default, since few users
        # will ever want to debug C++ Boost libraries, and there is no ABI
        # incompatibility between debug and release variants. We build shared
        # and static libraries since that is what most packages seem to provide
        # (.so in libfoo and .a in libfoo-dev).
        self.minimal-properties = [ property-set.create <variant>release
            <threading>multi <link>shared <link>static <runtime-link>shared ] ;
        # On Windows, new IDE projects use:
        #
        #   runtime-link=dynamic, threading=multi, variant=(debug|release)
        #
        # and in addition, C++ Boost's autolink defaults to static linking.
        self.minimal-properties-win = [ property-set.create <variant>debug
            <variant>release <threading>multi <link>static <runtime-link>shared
            ] ;

        self.complete-properties = [ property-set.create
            <variant>debug <variant>release
            <threading>single <threading>multi
            <link>shared <link>static
            <runtime-link>shared <runtime-link>static ] ;
    }

    rule generate ( property-set )
    {
        modules.poke : top-level-targets : [ modules.peek : top-level-targets ]
            $(self.name) ;
        if $(self.build-type) = minimal
        {
            local expanded ;

            local os = [ $(property-set).get <target-os> ] ;
            # Because we completely override the parent's 'generate' we need to
            # check for default feature values ourselves.
            if ! $(os)
            {
                os = [ feature.defaults <target-os> ] ;
                os = $(os:G=) ;
            }

            if $(os) = windows
            {
                expanded = [ targets.apply-default-build $(property-set)
                    : $(self.minimal-properties-win) ] ;
            }
            else
            {
                expanded = [ targets.apply-default-build $(property-set)
                    : $(self.minimal-properties) ] ;
            }
            return [ build-multiple $(expanded) ] ;
        }
        else if $(self.build-type) = complete
        {
            local expanded = [ targets.apply-default-build $(property-set)
                : $(self.complete-properties) ] ;

            # Filter inappopriate combinations.
            local filtered ;
            for local p in $(expanded)
            {
                # See comment in handle-static-runtime regarding this logic.
                if [ $(p).get <link> ] = shared
                    && [ $(p).get <runtime-link> ] = static
                    && [ $(p).get <toolset> ] != cw
                {
                    # Skip this.
                }
                else
                {
                    filtered += $(p) ;
                }
            }
            return [ build-multiple $(filtered) ] ;
        }
        else
        {
            import errors ;
            errors.error "Unknown build type" ;
        }
    }

    rule build-multiple ( property-sets * )
    {
        local usage-requirements = [ property-set.empty ] ;
        local result ;
        for local p in $(property-sets)
        {
            local r = [ alias-target-class.generate $(p) ] ;
            if $(r)
            {
                usage-requirements = [ $(usage-requirements).add $(r[1]) ] ;
                result += $(r[2-]) ;
            }
        }
        return $(usage-requirements) [ sequence.unique $(result) ] ;
    }
}

rule declare_top_level_targets ( libraries * : headers * )
{
    declare_install_and_stage_proper_targets $(libraries) : $(headers) ;

    targets.create-metatarget top-level-target : [ project.current ]
        : install
        : install-proper install-unversioned
        ;
    targets.create-metatarget top-level-target : [ project.current ]
        : stage
        : stage-proper stage-unversioned
        ;

    p = [ project.current ] ;
    $(p).mark-target-as-explicit install stage ;

    # This target is built by default, and will forward to 'stage' after
    # producing some explanations.
    targets.create-metatarget top-level-target : [ project.current ]
        : forward
        : explain stage
        ;
}


stage-abs = [ path.native [ path.root $(stage-locate)/lib [ path.pwd ] ] ] ;


################################################################################
#
# 4. Add hook to report configuration before the build, and confirmation with
# setup instructions after the build.
#
################################################################################

message explain : "\nBuilding the Boost C++ Libraries.\n\n" ;
local p = [ project.current ] ;
$(p).mark-target-as-explicit explain ;

rule pre-build ( )
{
    local tl = [ modules.peek : top-level-targets ] ;
    if stage in $(tl) || install in $(tl)
    {
        # FIXME: Remove 'if' when Boost regression tests start using trunk bjam.
        if PAD in [ RULENAMES ]
        {
            configure.print-component-configuration ;
        }
    }
}
IMPORT $(__name__) : pre-build : : $(__name__).pre-build ;
build-system.set-pre-build-hook $(__name__).pre-build ;

# FIXME: Revise stage_abs.
rule post-build ( ok ? )
{
    if forward in [ modules.peek : top-level-targets ]
    {
        if $(ok)
        {
            ECHO "

The Boost C++ Libraries were successfully built!

The following directory should be added to compiler include paths:

    $(BOOST_ROOT)

The following directory should be added to linker library paths:

    $(stage-abs)
" ;
        }
    }
}
IMPORT $(__name__) : post-build : : $(__name__).post-build ;
build-system.set-post-build-hook $(__name__).post-build ;


################################################################################
#
# 5. Top-level setup.
#
################################################################################

# Decides which libraries are to be installed by looking at --with-<library>
# --without-<library> arguments. Returns the list of directories under "libs"
# which must be built and installed.
#
rule libraries-to-install ( existing-libs * )
{
    local argv = [ modules.peek : ARGV ] ;
    local with-parameter = [ MATCH ^--with-(.*) : $(argv) ] ;
    local without-parameter = [ MATCH ^--without-(.*) : $(argv) ] ;

    if ! $(with-parameter) && ! $(without-parameter)
    {
        # Nothing is specified on command line. See if maybe project-config.jam
        # has some choices.
        local libs = [ modules.peek project-config : libraries ] ;
        with-parameter = [ MATCH ^--with-(.*) : $(libs) ] ;
        without-parameter = [ MATCH ^--without-(.*) : $(libs) ] ;
    }

    # Do some checks.
    if $(with-parameter) && $(without-parameter)
    {
        EXIT error: both --with-<library> and --without-<library> specified ;
    }

    local wrong = [ set.difference $(with-parameter) : $(existing-libs) ] ;
    if $(wrong)
    {
        EXIT error: wrong library name '$(wrong[1])' in the --with-<library>
            option. ;
    }
    local wrong = [ set.difference $(without-parameter) : $(existing-libs) ] ;
    if $(wrong)
    {
        EXIT error: wrong library name '$(wrong[1])' in the --without-<library>
            option. ;
    }

    if $(with-parameter)
    {
        return [ set.intersection $(existing-libs) : $(with-parameter) ] ;
    }
    else
    {
        return [ set.difference $(existing-libs) : $(without-parameter) ] ;
    }
}

rule declare-targets ( all-libraries * : headers * )
{
    configure.register-components $(all-libraries) ;

    # Select the libraries to install.
    libraries = [ libraries-to-install $(all-libraries) ] ;
    configure.components-building $(libraries) ;

    if [ option.get "show-libraries" : : true ]
    {
        ECHO The following libraries require building: ;
        for local l in $(libraries)
        {
            ECHO "    - $(l)" ;
        }
        EXIT ;
    }

    declare_top_level_targets $(libraries) : $(headers) ;
}

@ECHO OFF

REM Copyright (C) 2009 Vladimir Prus
REM
REM Distributed under the Boost Software License, Version 1.0.
REM (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)

ECHO Building Boost.Build engine
if exist ".\tools\build\v2\engine\bin.ntx86\b2.exe" del tools\build\v2\engine\bin.ntx86\b2.exe
if exist ".\tools\build\v2\engine\bin.ntx86\bjam.exe" del tools\build\v2\engine\bin.ntx86\bjam.exe
if exist ".\tools\build\v2\engine\bin.ntx86_64\b2.exe" del tools\build\v2\engine\bin.ntx86_64\b2.exe
if exist ".\tools\build\v2\engine\bin.ntx86_64\bjam.exe" del tools\build\v2\engine\bin.ntx86_64\bjam.exe
pushd tools\build\v2\engine

call .\build.bat %* > ..\..\..\..\bootstrap.log
@ECHO OFF

popd

if exist ".\tools\build\v2\engine\bin.ntx86\bjam.exe" (
   copy .\tools\build\v2\engine\bin.ntx86\b2.exe . > nul
   copy .\tools\build\v2\engine\bin.ntx86\bjam.exe . > nul
   goto :bjam_built)

if exist ".\tools\build\v2\engine\bin.ntx86_64\bjam.exe" (
   copy .\tools\build\v2\engine\bin.ntx86_64\b2.exe . > nul
   copy .\tools\build\v2\engine\bin.ntx86_64\bjam.exe . > nul
   goto :bjam_built)

goto :bjam_failure

:bjam_built

REM Ideally, we should obtain the toolset that build.bat has
REM guessed. However, it uses setlocal at the start and does
REM export BOOST_JAM_TOOLSET, and I don't know how to do that
REM properly. Default to msvc for now.
set toolset=msvc

ECHO import option ; > project-config.jam
ECHO. >> project-config.jam
ECHO using %toolset% ; >> project-config.jam
ECHO. >> project-config.jam
ECHO option.set keep-going : false ; >> project-config.jam
ECHO. >> project-config.jam

ECHO.
ECHO Bootstrapping is done. To build, run:
ECHO.
ECHO     .\b2
ECHO.    
ECHO To adjust configuration, edit 'project-config.jam'.
ECHO Further information:
ECHO.
ECHO     - Command line help:
ECHO     .\b2 --help
ECHO.     
ECHO     - Getting started guide: 
ECHO     http://boost.org/more/getting_started/windows.html
ECHO.     
ECHO     - Boost.Build documentation:
ECHO     http://www.boost.org/boost-build2/doc/html/index.html

goto :end

:bjam_failure

ECHO.
ECHO Failed to build Boost.Build engine.
ECHO Please consult bootstrap.log for furter diagnostics.
ECHO.
ECHO You can try to obtain a prebuilt binary from
ECHO.
ECHO    http://sf.net/project/showfiles.php?group_id=7586^&package_id=72941
ECHO.
ECHO Also, you can file an issue at http://svn.boost.org 
ECHO Please attach bootstrap.log in that case.

goto :end

:end

###
### Using 'darwin' toolset.
###
rm -rf bootstrap
mkdir bootstrap
cc -o bootstrap/jam0 command.c compile.c constants.c debug.c execcmd.c frames.c function.c glob.c hash.c hdrmacro.c headers.c jam.c jambase.c jamgram.c lists.c make.c make1.c object.c option.c output.c parse.c pathsys.c regexp.c rules.c scan.c search.c subst.c timestamp.c variable.c modules.c strings.c filesys.c builtins.c class.c cwd.c native.c md5.c w32_getreg.c modules/set.c modules/path.c modules/regex.c modules/property-set.c modules/sequence.c modules/order.c execunix.c fileunix.c pathunix.c
make.c:296:37: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "make\t--\t%s%s\n", spaces( depth ), object_str( t->name ) );
                                    ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:296:37: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:303:37: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "make\t--\t%s%s\n", spaces( depth ), object_str( t->name ) );
                                    ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:303:37: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:376:45: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
            printf( "bind\t--\t%s%s: %s\n", spaces( depth ),
                                            ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:376:45: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:384:45: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
            printf( "time\t--\t%s%s: %s\n", spaces( depth ),
                                            ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:384:45: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:389:45: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
            printf( "time\t--\t%s%s: %s\n", spaces( depth ),
                                            ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:389:45: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:731:13: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
            spaces( depth ), object_str( t->name ) );
            ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:731:13: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
6 warnings generated.
modules/path.c:16:12: warning: implicit declaration of function 'file_query' is invalid in C99 [-Wimplicit-function-declaration]
    return file_query( list_front( lol_get( frame->args, 0 ) ) ) ?
           ^
1 warning generated.
./bootstrap/jam0 -f build.jam --toolset=darwin --toolset-root= clean
...found 1 target...
...updating 1 target...
...updated 1 target...
./bootstrap/jam0 -f build.jam --toolset=darwin --toolset-root=
...found 158 targets...
...updating 3 targets...
[MKDIR] bin.macosxx86_64
[COMPILE] bin.macosxx86_64/b2
make.c:296:37: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "make\t--\t%s%s\n", spaces( depth ), object_str( t->name ) );
                                    ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:296:37: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:303:37: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "make\t--\t%s%s\n", spaces( depth ), object_str( t->name ) );
                                    ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:303:37: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:376:45: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
            printf( "bind\t--\t%s%s: %s\n", spaces( depth ),
                                            ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:376:45: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:384:45: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
            printf( "time\t--\t%s%s: %s\n", spaces( depth ),
                                            ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:384:45: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:389:45: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
            printf( "time\t--\t%s%s: %s\n", spaces( depth ),
                                            ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:389:45: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:731:13: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
            spaces( depth ), object_str( t->name ) );
            ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:731:13: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:768:43: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
            printf( "->%s%2d Name: %s\n", spaces( depth ), depth, target_name( t
                                          ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:768:43: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:772:43: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
            printf( "  %s%2d Name: %s\n", spaces( depth ), depth, target_name( t
                                          ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:772:43: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:778:38: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "  %s    Loc: %s\n", spaces( depth ), object_str( t->boundname )
                                     ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:778:38: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:784:42: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "  %s       : Stable\n", spaces( depth ) );
                                         ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:784:42: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:787:41: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "  %s       : Newer\n", spaces( depth ) );
                                        ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:787:41: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:790:56: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "  %s       : Up to date temp file\n", spaces( depth ) );
                                                       ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:790:56: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:793:65: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "  %s       : Temporary file, to be updated\n", spaces( depth )
                                                                ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:793:65: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:797:61: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "  %s       : Been touched, updating it\n", spaces( depth ) );
                                                            ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:797:61: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:800:56: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "  %s       : Missing, creating it\n", spaces( depth ) );
                                                       ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:800:56: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:803:57: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "  %s       : Outdated, updating it\n", spaces( depth ) );
                                                        ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:803:57: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:806:56: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "  %s       : Rebuild, updating it\n", spaces( depth ) );
                                                       ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:806:56: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:809:47: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "  %s       : Updating it\n", spaces( depth ) );
                                              ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:809:47: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:812:51: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "  %s       : Can not find it\n", spaces( depth ) );
                                                  ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:812:51: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:815:47: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "  %s       : Can make it\n", spaces( depth ) );
                                              ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:815:47: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:821:34: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "  %s       : ", spaces( depth ) );
                                 ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:821:34: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
make.c:833:52: warning: adding 'int' to a string does not append to the string [-Wstring-plus-int]
        printf( "  %s       : Depends on %s (%s)", spaces( depth ),
                                                   ^~~~~~~~~~~~~~~
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                    ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
make.c:833:52: note: use array indexing to silence this warning
make.c:85:44: note: expanded from macro 'spaces'
#define spaces(x) ( "                    " + ( x > 20 ? 0 : 20-x ) )
                                           ^
22 warnings generated.
modules/path.c:16:12: warning: implicit declaration of function 'file_query' is invalid in C99 [-Wimplicit-function-declaration]
    return file_query( list_front( lol_get( frame->args, 0 ) ) ) ?
           ^
1 warning generated.
[COPY] bin.macosxx86_64/bjam
...updated 3 targets...

#!/bin/sh
# Copyright (C) 2005, 2006 Douglas Gregor.
# Copyright (C) 2006 The Trustees of Indiana University
#
# Distributed under the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)

# boostinspect:notab - Tabs are required for the Makefile.

BJAM=""
TOOLSET=""
BJAM_CONFIG=""
BUILD=""
PREFIX=/usr/local
EPREFIX=
LIBDIR=
INCLUDEDIR=
LIBS=""
PYTHON=python
PYTHON_VERSION=
PYTHON_ROOT=
ICU_ROOT=

# Internal flags
flag_no_python=
flag_icu=
flag_show_libraries=

for option
do
    case $option in

    -help | --help | -h)
      want_help=yes ;;

    -prefix=* | --prefix=*)
      PREFIX=`expr "x$option" : "x-*prefix=\(.*\)"`
      ;;

    -exec-prefix=* | --exec-prefix=*)
      EPREFIX=`expr "x$option" : "x-*exec-prefix=\(.*\)"`
      ;;

    -libdir=* | --libdir=*)
      LIBDIR=`expr "x$option" : "x-*libdir=\(.*\)"`
      ;;

    -includedir=* | --includedir=*)
      INCLUDEDIR=`expr "x$option" : "x-*includedir=\(.*\)"`
      ;;

    -show-libraries | --show-libraries )
      flag_show_libraries=yes
      ;;

    -with-bjam=* | --with-bjam=* )
      BJAM=`expr "x$option" : "x-*with-bjam=\(.*\)"`
      ;;

    -with-icu | --with-icu )
      flag_icu=yes
      ;;

    -with-icu=* | --with-icu=* )
      flag_icu=yes
      ICU_ROOT=`expr "x$option" : "x-*with-icu=\(.*\)"`
      ;;

    -without-icu | --without-icu )
      flag_icu=no
      ;;

    -with-libraries=* | --with-libraries=* )
      library_list=`expr "x$option" : "x-*with-libraries=\(.*\)"`
      if test "$library_list" != "all"; then
          old_IFS=$IFS
          IFS=,
          for library in $library_list
          do
              LIBS="$LIBS --with-$library"

              if test $library = python; then
                  requested_python=yes
              fi
          done
          IFS=$old_IFS

          if test "x$requested_python" != xyes; then
              flag_no_python=yes
          fi
      fi
      ;;

    -without-libraries=* | --without-libraries=* )
      library_list=`expr "x$option" : "x-*without-libraries=\(.*\)"`
      old_IFS=$IFS
      IFS=,
      for library in $library_list
      do
          LIBS="$LIBS --without-$library"

          if test $library = python; then
              flag_no_python=yes
          fi
      done
      IFS=$old_IFS
      ;;

    -with-python=* | --with-python=* )
      PYTHON=`expr "x$option" : "x-*with-python=\(.*\)"`
      ;;

    -with-python-root=* | --with-python-root=* )
      PYTHON_ROOT=`expr "x$option" : "x-*with-python-root=\(.*\)"`
      ;;

    -with-python-version=* | --with-python-version=* )
      PYTHON_VERSION=`expr "x$option" : "x-*with-python-version=\(.*\)"`
      ;;

    -with-toolset=* | --with-toolset=* )
      TOOLSET=`expr "x$option" : "x-*with-toolset=\(.*\)"`
      ;;

    -*)
      { echo "error: unrecognized option: $option
Try \`$0 --help' for more information." >&2
      { (exit 1); exit 1; }; }
      ;; 

    esac
done

if test "x$want_help" = xyes; then
  cat <<EOF
\`./bootstrap.sh' prepares Boost for building on a few kinds of systems.

Usage: $0 [OPTION]... 

Defaults for the options are specified in brackets.

Configuration:
  -h, --help                display this help and exit
  --with-bjam=BJAM          use existing Boost.Jam executable (bjam)
                            [automatically built]
  --with-toolset=TOOLSET    use specific Boost.Build toolset
                            [automatically detected]
  --show-libraries          show the set of libraries that require build
                            and installation steps (i.e., those libraries
                            that can be used with --with-libraries or
                            --without-libraries), then exit
  --with-libraries=list     build only a particular set of libraries,
                            describing using either a comma-separated list of
                            library names or "all"
                            [all]
  --without-libraries=list  build all libraries except the ones listed []
  --with-icu                enable Unicode/ICU support in Regex 
                            [automatically detected]
  --without-icu             disable Unicode/ICU support in Regex
  --with-icu=DIR            specify the root of the ICU library installation
                            and enable Unicode/ICU support in Regex
                            [automatically detected]
  --with-python=PYTHON      specify the Python executable [python]
  --with-python-root=DIR    specify the root of the Python installation
                            [automatically detected]
  --with-python-version=X.Y specify the Python version as X.Y
                            [automatically detected]

Installation directories:
  --prefix=PREFIX           install Boost into the given PREFIX
                            [/usr/local]
  --exec-prefix=EPREFIX     install Boost binaries into the given EPREFIX
                            [PREFIX]

More precise control over installation directories:
  --libdir=DIR              install libraries here [EPREFIX/lib]
  --includedir=DIR          install headers here [PREFIX/include]

EOF
fi
test -n "$want_help" && exit 0

# TBD: Determine where the script is located
my_dir="."

# Determine the toolset, if not already decided
if test "x$TOOLSET" = x; then
  guessed_toolset=`$my_dir/tools/build/v2/engine/build.sh --guess-toolset`
  case $guessed_toolset in
    acc | darwin | gcc | como | mipspro | pathscale | pgi | qcc | vacpp )
    TOOLSET=$guessed_toolset
    ;;
    
    intel-* )
    TOOLSET=intel
    ;;
    
    mingw )
    TOOLSET=gcc
    ;;
    
    sun* )
    TOOLSET=sun
    ;;
    
    * )
    # Not supported by Boost.Build
    ;;
  esac
fi

rm -f config.log

# Build bjam
if test "x$BJAM" = x; then
  echo -n "Building Boost.Build engine with toolset $TOOLSET... "
  pwd=`pwd`
  (cd "$my_dir/tools/build/v2/engine" && ./build.sh "$TOOLSET") > bootstrap.log 2>&1
  if [ $? -ne 0 ]; then
      echo
      echo "Failed to build Boost.Build build engine" 
      echo "Consult 'bootstrap.log' for more details"
      exit 1
  fi
  cd "$pwd"
  arch=`cd $my_dir/tools/build/v2/engine && ./bootstrap/jam0 -d0 -f build.jam --toolset=$TOOLSET --toolset-root= --show-locate-target && cd ..`
  BJAM="$my_dir/tools/build/v2/engine/$arch/b2"
  echo "tools/build/v2/engine/$arch/b2"
  cp "$BJAM" .
  cp "$my_dir/tools/build/v2/engine/$arch/bjam" .

fi

# TBD: Turn BJAM into an absolute path

# If there is a list of libraries 
if test "x$flag_show_libraries" = xyes; then
  cat <<EOF

The following Boost libraries have portions that require a separate build
and installation step. Any library not listed here can be used by including
the headers only.

The Boost libraries requiring separate building and installation are:
EOF
  $BJAM -d0 --show-libraries | grep '^[[:space:]]*-'
  exit 0
fi

# Setup paths
if test "x$EPREFIX" = x; then
  EPREFIX="$PREFIX"
fi

if test "x$LIBDIR" = x; then
  LIBDIR="$EPREFIX/lib"
fi

if test "x$INCLUDEDIR" = x; then
  INCLUDEDIR="$PREFIX/include"
fi

# Find Python
if test "x$flag_no_python" = x; then
  result=`$PYTHON -c "exit" > /dev/null 2>&1`
  if [ "$?" -ne "0" ]; then
    flag_no_python=yes
  fi
fi

if test "x$flag_no_python" = x; then
    if test "x$PYTHON_VERSION" = x; then
        echo -n "Detecting Python version... "
        PYTHON_VERSION=`$PYTHON -c "import sys; print (\"%d.%d\" % (sys.version_info[0], sys.version_info[1]))"`
        echo $PYTHON_VERSION
    fi

    if test "x$PYTHON_ROOT" = x; then
        echo -n "Detecting Python root... "
        PYTHON_ROOT=`$PYTHON -c "import sys; print sys.prefix"`
        echo $PYTHON_ROOT
    fi    
fi

# Configure ICU
echo -n "Unicode/ICU support for Boost.Regex?... "
if test "x$flag_icu" != xno; then
  if test "x$ICU_ROOT" = x; then
    COMMON_ICU_PATHS="/usr /usr/local /sw"
    for p in $COMMON_ICU_PATHS; do
      if test -r $p/include/unicode/utypes.h; then
        ICU_ROOT=$p
      fi
    done
  
    if test "x$ICU_ROOT" = x; then
      echo "not found."
    else      
      BJAM_CONFIG="$BJAM_CONFIG -sICU_PATH=$ICU_ROOT"
      echo "$ICU_ROOT"
    fi
  else
    BJAM_CONFIG="$BJAM_CONFIG -sICU_PATH=$ICU_ROOT"
    echo "$ICU_ROOT"
  fi
else
  echo "disabled."
fi

# Backup the user's existing project-config.jam
JAM_CONFIG_OUT="project-config.jam"
if test -r "project-config.jam"; then
  counter=1
 
  while test -r "project-config.jam.$counter"; do
    counter=`expr $counter + 1`
  done

  echo "Backing up existing Boost.Build configuration in project-config.jam.$counter"
  mv "project-config.jam" "project-config.jam.$counter"
fi

# Generate user-config.jam
echo "Generating Boost.Build configuration in project-config.jam..."
cat > project-config.jam <<EOF
# Boost.Build Configuration
# Automatically generated by bootstrap.sh

import option ;
import feature ;

# Compiler configuration. This definition will be used unless
# you already have defined some toolsets in your user-config.jam
# file.
if ! $TOOLSET in [ feature.values <toolset> ]
{
    using $TOOLSET ; 
}

project : default-build <toolset>$TOOLSET ;
EOF

#  - Python configuration
if test "x$flag_no_python" = x; then
  cat >> project-config.jam <<EOF

# Python configuration
using python : $PYTHON_VERSION : $PYTHON_ROOT ;
EOF
fi

if test "x$ICU_ROOT" != x; then
  cat >> project-config.jam << EOF

path-constant ICU_PATH : $ICU_ROOT ;

EOF
fi

cat >> project-config.jam << EOF

# List of --with-<library> and --without-<library>
# options. If left empty, all libraries will be built.
# Options specified on the command line completely
# override this variable.
libraries = $LIBS ;

# These settings are equivivalent to corresponding command-line
# options.
option.set prefix : $PREFIX ;
option.set exec-prefix : $EPREFIX ;
option.set libdir : $LIBDIR ;
option.set includedir : $INCLUDEDIR ;

# Stop on first error
option.set keep-going : false ;
EOF

cat << EOF

Bootstrapping is done. To build, run:

    ./b2
    
To adjust configuration, edit 'project-config.jam'.
Further information:

   - Command line help:
     ./b2 --help
     
   - Getting started guide: 
     http://www.boost.org/more/getting_started/unix-variants.html
     
   - Boost.Build documentation:
     http://www.boost.org/boost-build2/doc/html/index.html

EOF

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="refresh" content="0; URL=index.html" />

  <title></title>
  <link rel="stylesheet" href="doc/src/boostbook.css" type="text/css" />
</head>

<body>
  Automatic redirection failed, please go to <a href=
  "index.html">index.html</a>.

  <div class="copyright-footer">
    <p>Copyright 2008 Rene Rivera</p>

    <p>Distributed under the Boost Software License, Version 1.0. (See
    accompanying file <a href="LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
    at <a href=
    "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
  </div>
</body>
</html>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>Boost C++ Libraries</title>
  <link rel="stylesheet" href="doc/src/boostbook.css" type="text/css" />
</head>

<body>
  <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
    <tr>
      <td width="277">
        <a href="index.html">
        <img src="boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" border="0"/></a></td>
      <td width="337" align="middle">
      <h2 style="text-align: center">Release 1.55.0</h2>
      </td>
    </tr>
  </table>

  <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" height="26" width="671">
    <tr>
      <td height="16" width="661"><a href="more/getting_started/index.html">Getting Started</a>&nbsp;&nbsp;<font color="#FFFFFF">&nbsp;
      </font>&nbsp; <a href="libs/libraries.htm">Libraries</a>&nbsp;&nbsp;<font color="#FFFFFF">&nbsp;
      </font>&nbsp; <a href="tools/index.html">Tools&nbsp;</a>&nbsp;<font color="#FFFFFF">&nbsp;
      </font>&nbsp; <a href="http://www.boost.org">Web Site</a>&nbsp;&nbsp;<font color="#FFFFFF">&nbsp;
      </font>&nbsp; <a href="http://www.boost.org/users/news/">News</a>&nbsp;&nbsp;<font color="#FFFFFF">&nbsp;
      </font>&nbsp; <a href="http://www.boost.org/community/">Community</a>&nbsp;&nbsp;<font color="#FFFFFF">&nbsp;
      </font>&nbsp; <a href="http://www.boost.org/users/faq.html">FAQ</a>&nbsp;&nbsp;<font color="#FFFFFF">&nbsp;
      </font>&nbsp; <a href="more/index.htm">More Info</a></td>
    </tr>
  </table>


  <h2 class="title">Welcome to the Boost C++ Libraries</h2>

  <p>Boost provides free peer-reviewed portable C++ source libraries.</p>

  <p>We emphasize libraries that work well with the C++ Standard Library.
  Boost libraries are intended to be widely useful, and usable across a broad
  spectrum of applications. The <a href=
  "http://www.boost.org/users/license.html">Boost license</a> encourages both
  commercial and non-commercial use.</p>

  <p>We aim to establish "existing practice" and provide reference
  implementations so that Boost libraries are suitable for eventual
  standardization. Ten Boost libraries are already included in the <a href=
  "http://www.open-std.org/jtc1/sc22/wg21/">C++ Standards Committee's</a>
  Library Technical Report (<a href=
  "http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1745.pdf">TR1</a>)
  and will be included in the upcoming revision of the C++ Standard. More
  Boost libraries are proposed for the upcoming <a href=
  "http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1810.html">TR2</a>.</p>

  <h3>Changes in this release</h3>

  <p>This release includes one new library
  (<a href="libs/predef/index.html">Predef</a>),
  as well as updates to many existing libraries. See
  <a href="http://www.boost.org/users/history/version_1_55_0.html">Release
  History</a> for more information.</p>

  <h3>Getting Started</h3>

  <p>If Boost hasn't already been installed on your system, follow the
  <a href="more/getting_started/index.html">Getting Started Guide</a> to
  complete the installation. But if you've reached to this point by
  installing Boost from a Windows pre-build executable or a pre-built Linux
  and Unix distribution package, that's already been completed. Likewise, if
  you're reading this on your organization's internal web server, the
  installation is probably already complete.</p>

  <h3>Contents</h3>

  <p>The release directory tree contains almost all of Boost; documentation,
  sources, headers, scripts, tools, and everything else a Boost user might
  need!</p>

  <h3>Library Documentation</h3>

  <p>The starting point for the documentation of individual libraries is the
  <a href="libs/libraries.htm">Libraries page</a>, which gives a brief
  description of each library and links to its documentation.</p>

  <h3>Web Site</h3>

  <p>Some general interest or often changing Boost information lives only on
  the <a href="http://www.boost.org">Boost web site</a>. The release contains
  links to the site, so while browsing it you'll see occasional broken links
  if you aren't connected to the Internet. But everything needed to use the
  Boost libraries is contained within the release.</p>

  <h3>Background</h3>

  <p>Read the <a href="http://www.boost.org/users/">introductory material</a>
  to help you understand what Boost is about and to help in educating your
  organization about Boost.</p>

  <h3>Community</h3>

  <p>Boost welcomes and thrives on participation from a variety of
  individuals and organizations. Many avenues for participation are available
  in the <a href="http://www.boost.org/community/">Boost Community</a>.</p>

  <div class="copyright-footer">
    <p>Copyright &copy; 2008 Beman Dawes, Rene Rivera</p>

    <p>Distributed under the Boost Software License, Version 1.0. (See
    accompanying file <a href="LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
    at <a href=
    "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</p>

    <p>This software is <a href="http://www.opensource.org/">Open Source
    Initiative</a> approved Open Source Software.</p>

    <p>Open Source Initiative Approved is a trademark of the Open Source
    Initiative.</p>
  </div>
</body>
</html>

The following people hereby grant permission to replace all existing
licenses on their contributions to Boost with the Boost Software
License, Version 1.0. (boostinspect:nolicense boostinspect:nocopyright)

Aleksey Gurtovoy (agurtovoy@meta-comm.com)
Andrei Alexandrescu (andrewalex - at - hotmail.com) (See Boost list message of August 12, 2004 11:06:58 AM EST)   
Andrew Lumsdaine ()
Anthony Williams (anthony -at- justsoftwaresolutions.co.uk)
Beman Dawes (bdawes@acm.org)
Brad King (brad.king -at- kitware.com) (See Boost list message of Wed, 21 Jul 2004 11:15:46 -0400)
Brian Osman (osman -at- vvisions.com) (See CVS log)
Bruce Barr (schmoost -at- yahoo.com) (See Boost list of Mon, 16 Aug 2004 15:06:43 -0500)
Bruno da Silva de Oliveira (bruno - at - esss.com.br)
Christain Engstrom (christian.engstrom -at- glindra.org) (See Boost list message of Mon, 30 Aug 2004 14:31:49 +0200)
Cromwell D Enage (sponage -at- yahoo.com) (See Boost list message of August 12, 2004 11:49:13 AM EST) 
Dan Gohman (djg -at- cray.com) (See Boost list messsage of Sat, 21 Aug 2004 10:54:59 +0100)
Dan Nuffer (dan -at- nuffer.name)
Daniel Frey (d.frey -at- gmx.de, daniel.frey -at- aixigo.de)
Daniel Nuffer (dan -at- nuffer.name)
Darin Adler (darin -at- bentspoon.com) (Email to Andreas Huber, see change log)
Daryle Walker (darylew - at - hotmail.com)
Dave Abrahams (dave@boost-consulting.com)
Dave Moore (dmoore -at- viefinancial.com) (See Boost list message of 18 Dec 2003 15:35:50 -0500)
David Abrahams (dave@boost-consulting.com)
Dietmar Kuehl (dietmar_kuehl -at- yahoo.com) (Email to Andreas Huber, see change log)
Douglas Gregor (gregod -at- cs.rpi.edu, dgregor -at- cs.indiana.edu, doug.gregor -at- gmail.com)
Dr John Maddock (john - at - johnmaddock.co.uk)
Edward D. Brey (brey -at- ductape.net) (Email to Andreas Huber, see change log)
Eric Ford (un5o6n902 -at- sneakemail.com) (See Boost list message of Sun, 15 Aug 2004 10:29:13 +0100)
Eric Friedman (ebf@users.sourceforge.net)
Eric Niebler (eric@boost-consulting.com)
Fernando Cacciola (fernando_cacciola@ciudad.com.ar)
Fernando Luis Cacciola Carballal (fernando_cacciola@ciudad.com.ar)
Francois Faure (Francois.Faure -at- imag.fr) (See CVS log)
Gary Powell (powellg - at - amazon.com) (See Boost list message of 10 Feb 2004 14:22:46 -0800)
Gennadiy Rozental (rogeeff -at- mail.com) (Email to Andreas Huber, see change log)
Gottfried Ganssauge (Gottfried.Ganssauge -at- HAUFE.DE) (See Boost List message of Mon, 16 Aug 2004 10:09:19 +0200)
Gottfried Gan�auge (Gottfried.Ganssauge -at- HAUFE.DE) (Alternative spelling of Gottfried Ganssauge)
Greg Colvin (gregory.colvin -at- oracle.com) (See Boost list message of Sat, 14 Aug 2004 10:57:00 +0100)
Gregory Colvin (gregory.colvin -at- oracle.com) (See Boost list message of Sat, 14 Aug 2004 10:57:00 +0100)
Gunter Winkler (gunter.winkler -at- unibw-muenchen.de) (See Boost List message of Mon, 16 Aug 2004 10:24:17 +0200)
Hartmut Kaiser (hartmut.kaiser -at- gmail.com)
Herve Bronnimann (hbr -at- poly.edu)
Herv� Br�nnimann (hbr -at- poly.edu)
Housemarque Oy (Ilari Kuittinen ilari.kuittinen -at- housemarque.fi)
Howard Hinnant (hinnant -at- twcny.rr.com) (See Boost list message of July 25, 2004 3:44:49 PM EST)
Hubert Holin (hubert_holin -at- users.sourceforge.net)
Indiana University ()
Itay Maman (imaman -at- users.sourceforge.net)
Jaakko J�rvi (jajarvi -at- osl.iu.edu)
Jaap Suter (j.suter -at- student.utwente.nl) (See Boost list message of Thu, 16 Sep 2004 09:32:43 -0700)
Jeff Garland (jeff - at - crystalclearsoftware.com) (see Boost list post of July 25, 2004 19:31:09 -0700)
Jens Maurer (Jens.Maurer@gmx.net)
Jeremy G Siek (jsiek@osl.iu.edu)
Jeremy Siek (jsiek@osl.iu.edu)
Joel de Guzman (joel -at- boost-consulting.com) (See Boost list message of July 25, 2004 8:32:00 PM EST)
John Bandela (jbandela-at-ufl.edu)
John Maddock (john - at - johnmaddock.co.uk)
John R Bandela (jbandela-at-ufl.edu)
Jonathan Turkanis (turkanis -at- coderage dot com)
Juergen Hunold (hunold -at- ive.uni-hannover.de) (See Boost List Message of Fri, 13 Aug 2004 19:39:55 +0200)
Kevlin Henney (kevlin -at- curbralan.com) (See Boost list message of Wed, 15 Sep 2004 18:15:17 +0200)
Kresimir Fresl (fresl -at- master.grad.hr) (See Boost List message of August 16, 2004 8:23:35 AM EST)
Lars Gullik Bj�nnes (larsbj -at- lyx.org) (See Boost list message of Tue, 17 Aug 2004 15:49:02 +0100)
Lie-Quan Lee (liequan - at - slac.stanford.edu, llee - at - cs.indiana.edu)
Maarten Keijzer (mkeijzer -at- cs.vu.nl) (See Boost list message of Wed, 18 Aug 2004 21:43:18 +0100)
Mac Murrett (mmurrett -at- mac.com)
Marc Wintermantel (wintermantel -at- imes.mavt.ethz.ch, wintermantel -at- even-ag.ch) (See CVS log)
Michael Glassford (glassfordm - at - hotmail.com)
Michael Stevens (Michael.Stevens - at - epost.de)
Multi Media Ltd. (pdimov@mmltd.net)
Nicolai M Josuttis (solutions -at- josuttis.com) (See Boost list message of Mon, 30 Aug 2004 10:52:00 +0100)
Nikolay Mladenov (nickm -at- sitius.com) (See Boost list message of Tue, 17 Aug 2004 15:45:33 +0100)
Paul Mensonides (pmenso57 -at- comcast.net) (See Boost list message of July 21, 2004 1:12:21 AM EST)
Pavol Droba (droba -at- topmail.sk)
Peter Dimov (pdimov@mmltd.net)
R W Grosse-Kunstleve (RWGrosse-Kunstleve@lbl.gov)
Ralf W. Grosse-Kunstleve (RWGrosse-Kunstleve@lbl.gov)
Rational Discovery LLC (Greg Landrum Landrum -at- RationalDiscovery.com) (See Boost list post of Tue, 17 Aug 2004 10:35:36 +0100)
Rene Rivera (grafik/redshift-software.com, rrivera/acm.org)
Robert Ramey (ramey@www.rrsd.com)
Roland Richter (roland -at- flll.jku.at) (See Boost list post of Mon, 16 Aug 2004 22:16:55 +0200)
Roland Schwarz (roland.schwarz -at- chello.at)
Ronald Garcia (garcia -at- cs.indiana.edu) (Email to Andreas Huber, see change log)
Samuel Krempp (krempp -at- crans.ens-cachan.fr) (See Boost list message of Mon, 27 Sep 2004 13:18:36 +0200)
Stefan Seefeld (seefeld -at- sympatico.ca)
Stephen Cleary (scleary -at- jerviswebb.com) (See Boost list message of Tue, 28 Sep 2004 13:11:46 +0100)
Steve Cleary (Variant of Stephen Cleary)
Sylvain Pion (Sylvain.Pion - at - sophia.inria.fr)
The Trustees of Indiana University ()
Thomas Witt (witt - at - ive.uni-hannover.de, witt - at - acm.org, witt - at - styleadvisor.com)
Thorsten J�rgen Ottosen (nesotto - at - cs.auc.dk)
Thorsten Ottosen (nesotto - at - cs.auc.dk)
Toon Knapen (toon dot knapen - at - fft.be)
Trustees of Indiana University ()
University of Notre Dame ()
Vladimir Prus (ghost@cs.msu.su)
William E. Kempf () (email to Beman Dawes, 9/14/2006 4:18 PM)
Joerg Walter (jhr.walter - at - t-online.de : email to ublas mailing list Mon, 17 Sep 2007 10:17:08 +0200)
Mathias Koch (mkoch - at - idesis.de 7 : email to boost-owner@lists.boost.org Sep 2007 13:20:09 +0200)

--- end ---

<html>
<head>
<meta http-equiv="refresh" content="0; URL=getting_started/index.html">
</head>
<body>
Automatically loading index page... if nothing happens, please go to
<a href="getting_started/index.html">getting_started/index.html</a>.
</body>
</html>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->

# Copyright David Abrahams 2006. Distributed under the Boost
# Software License, Version 1.0. (See accompanying
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
import docutils ;

import path ;
sources = [ path.glob . : *.rst ] ;
bases = $(sources:S=) ;
  
# This is a path relative to the html/ subdirectory where the
# generated output will eventually be moved.
stylesheet = "--stylesheet=../../rst.css" ;

for local b in $(bases)
{
    html $(b) : $(b).rst : 
      
    <docutils-html>"--link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript "$(stylesheet)
  ;
}

alias htmls : $(bases) ;
stage . : $(bases) ;

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Prepare to Use a Boost Library Binary
=====================================

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

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

.. [#warnings] 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.

.. [#distinct] 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.

.. [#debug-abi] These libraries were compiled without optimization
   or inlining, with full debug symbols enabled, and without
   ``NDEBUG`` ``#define``\ d.  Although 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.

.. [#native] This feature of STLPort is deprecated because it's
   impossible to make it work transparently to the user; we don't
   recommend it.

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

.. |//| replace:: **/**
.. |/| replace:: ``/``

.. |default-root| replace:: ``/usr/local/``\ |boost_ver|
.. |default-root-bold| replace:: **/usr/local/**\ |boost_ver-bold|

.. |root| replace:: *path/to/*\ |boost_ver|

.. |forward-slashes| replace:: `` ``

.. |precompiled-dir| replace:: `` ``

.. |include-paths| replace:: `` ``

.. |windows-version-name-caveat| replace:: `` ``

.. |command-line tool| replace:: command-line tool

.. |pathsep| replace:: colon

.. |path| replace:: ``echo $PATH``

.. |bootstrap| replace:: ``bootstrap.sh``

.. include:: common.rst

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

.. |//| replace:: **\\**
.. |/| replace:: ``\``

.. |default-root| replace:: ``C:\Program Files\boost\``\ |boost_ver|
.. |default-root-bold| replace:: **C:\\Program Files\\boost\\**\ |boost_ver-bold|

.. |root| replace:: *path\\to\\*\ |boost_ver|

.. |include-paths| replace:: 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.

.. |forward-slashes| replace:: Even Windows users can (and, for
   portability reasons, probably should) use forward slashes in
   ``#include`` directives; your compiler doesn't care.

.. |precompiled-dir| replace:: 

    **lib**\ |//| .....................\ *precompiled library binaries*


.. |windows-version-name-caveat| replace:: **On Windows, append a version
   number even if you only have one version installed** (unless you
   are using the msvc or gcc toolsets, which have special version
   detection code) or `auto-linking`_ will fail.

.. |command-line tool| replace:: `command-line tool`_

.. |pathsep| replace:: semicolon

.. |path| replace:: ``PATH``

.. |bootstrap| replace:: ``bootstrap.bat``

.. include:: common.rst

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

.. |next| replace:: *skip to the next step*

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Conclusion and Further Resources
================================

This concludes your introduction to Boost and to integrating it
with your programs.  As you start using Boost in earnest, there are
surely a few additional points you'll wish we had covered.  One day
we may have a “Book 2 in the Getting Started series” that addresses
them.  Until then, we suggest you pursue the following resources.
If you can't find what you need, or there's anything we can do to
make this document clearer, please post it to the `Boost Users'
mailing list`_.

* `Boost.Build reference manual`_
* `Boost Users' mailing list`_
* `Boost.Build mailing list`_
* `Index of all Boost library documentation`_

.. _Index of all Boost library documentation: ../../libs/index.html

.. Admonition:: Onward

  .. epigraph::

     Good luck, and have fun!

     -- the Boost Developers

.. _Boost.Build reference manual: ../../tools/build/v2/index.html
.. _Boost Users' mailing list: http://www.boost.org/more/mailing_lists.htm#users
.. _Boost.Build mailing list: http://www.boost.org/more/mailing_lists.htm#jamboost

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

The Boost Distribution
======================

This is a sketch of the resulting directory structure:

.. parsed-literal::

 |boost_ver-bold|\ |//| .................\ *The “boost root directory”* 
    **index.htm** .........\ *A copy of www.boost.org starts here*
    **boost**\ |//| .........................\ *All Boost Header files*
    |precompiled-dir|    
    **libs**\ |//| ............\ *Tests, .cpp*\ s\ *, docs, etc., by library*
      **index.html** ........\ *Library documentation starts here*
      **algorithm**\ |//|
      **any**\ |//|
      **array**\ |//|
                      *…more libraries…*
    **status**\ |//| .........................\ *Boost-wide test suite*
    **tools**\ |//| ...........\ *Utilities, e.g. Boost.Build, quickbook, bcp*
    **more**\ |//| ..........................\ *Policy documents, etc.*
    **doc**\ |//| ...............\ *A subset of all Boost library docs*

.. sidebar:: Header Organization

   .. class:: pre-wrap

     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 Python library's ``def.hpp`` header in

       .. parsed-literal::

         ``boost``\ |/|\ ``python``\ |/|\ ``def.hpp``.

     * Some libraries have an “aggregate header” in ``boost``\ |/| that
       ``#include``\ s all of the library's other headers.  For
       example, Boost.Python_'s aggregate header is

       .. parsed-literal::

         ``boost``\ |/|\ ``python.hpp``.

     * Most libraries place private headers in a subdirectory called
       ``detail``\ |/|, or ``aux_``\ |/|.  Don't expect to find
       anything you can use in these directories.

It's important to note the following:

.. _Boost root directory:

1. The path to the **boost root directory** (often |default-root|) is
   sometimes referred to as ``$BOOST_ROOT`` in documentation and
   mailing lists .

2. To compile anything in Boost, you need a directory containing
   the ``boost``\ |/| subdirectory in your ``#include`` path.  |include-paths|

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:

   .. parsed-literal::

     #include <boost/\ *whatever*\ .hpp>

   or

   .. parsed-literal::

     #include "boost/\ *whatever*\ .hpp"

   depending on your preference regarding the use of angle bracket
   includes.  |forward-slashes|

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

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Errors and Warnings
-------------------

Don't be alarmed if you see compiler warnings originating in Boost
headers.  We try to eliminate them, but doing so isn't always
practical.  [#warnings]_ **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`_.

__ `Build a Simple Program Using Boost`_

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

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.

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

.. .. _separate: 

The only Boost libraries that *must* be built separately are:

* Boost.Chrono_
* Boost.Context_
* Boost.Filesystem_
* Boost.GraphParallel_
* Boost.IOStreams_
* Boost.Locale_
* Boost.MPI_
* Boost.ProgramOptions_
* Boost.Python_ (see the `Boost.Python build documentation`__
  before building and installing it)
* Boost.Regex_
* Boost.Serialization_
* Boost.Signals_
* Boost.System_
* Boost.Thread_
* Boost.Timer_
* Boost.Wave_

__ ../../libs/python/doc/building.html

A few libraries have optional separately-compiled binaries:

* Boost.DateTime_ has a binary component that is only needed if
  you're using its ``to_string``\ /\ ``from_string`` or serialization
  features, or if you're targeting Visual C++ 6.x or Borland.

* Boost.Graph_ also has a binary component that is only needed if
  you intend to `parse GraphViz files`__.

* Boost.Math_ has binary components for the TR1 and C99
  cmath functions.

* Boost.Random_ has a binary component which is only needed if
  you're using ``random_device``.

* Boost.Test_ can be used in “header-only” or “separately compiled”
  mode, although **separate compilation is recommended for serious
  use**.

* Boost.Exception_ provides non-intrusive implementation of
  exception_ptr for 32-bit _MSC_VER==1310 and _MSC_VER==1400
  which requires a separately-compiled binary. This is enabled by
  #define BOOST_ENABLE_NON_INTRUSIVE_EXCEPTION_PTR.

__ ../../libs/graph/doc/read_graphviz.html

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

In order to choose the right binary for your build configuration
you need to know how Boost binaries are named.  Each library
filename is composed of a common sequence of elements that describe
how it was built.  For example,
``libboost_regex-vc71-mt-d-1_34.lib`` can be broken down into the
following elements:

``lib`` 
  *Prefix*: except on Microsoft Windows, every Boost library
  name begins with this string.  On Windows, only ordinary static
  libraries use the ``lib`` prefix; import libraries and DLLs do
  not. [#distinct]_

``boost_regex``
  *Library name*: all boost library filenames begin with ``boost_``.

``-vc71``
   *Toolset tag*: identifies the toolset_ and version used to build
   the binary.

``-mt``
   *Threading tag*: indicates that the library was
   built with multithreading support enabled.  Libraries built
   without multithreading support can be identified by the absence
   of ``-mt``.

``-d``
   *ABI tag*: encodes details that affect the library's
   interoperability with other compiled code.  For each such
   feature, a single letter is added to the tag:

     +-----+------------------------------------------------------------------------------+---------------------+
     |Key  |Use this library when:                                                        |Boost.Build option   |
     +=====+==============================================================================+=====================+
     |``s``|linking statically to the C++ standard library and compiler runtime support   |runtime-link=static  |
     |     |libraries.                                                                    |                     |
     +-----+------------------------------------------------------------------------------+---------------------+
     |``g``|using debug versions of the standard and runtime support libraries.           |runtime-debugging=on |
     +-----+------------------------------------------------------------------------------+---------------------+
     |``y``|using a special `debug build of Python`__.                                    |python-debugging=on  |
     +-----+------------------------------------------------------------------------------+---------------------+
     |``d``|building a debug version of your code. [#debug-abi]_                          |variant=debug        |
     +-----+------------------------------------------------------------------------------+---------------------+
     |``p``|using the STLPort standard library rather than the default one supplied with  |stdlib=stlport       |
     |     |your compiler.                                                                |                     |
     +-----+------------------------------------------------------------------------------+---------------------+

   For example, if you build a debug version of your code for use
   with debug versions of the static runtime library and the
   STLPort standard library in “native iostreams” mode,
   the tag would be: ``-sgdpn``.  If none of the above apply, the
   ABI tag is ommitted.

``-1_34``
  *Version tag*: the full Boost release number, with periods
  replaced by underscores. For example, version 1.31.1 would be
  tagged as "-1_31_1".

``.lib``
  *Extension*: determined according to the operating system's usual
  convention.  On most unix-style platforms the extensions are
  ``.a`` and ``.so`` for static libraries (archives) and shared
  libraries, respectively.  On Windows, ``.dll`` indicates a shared
  library and ``.lib`` indicates a
  static or import library.  Where supported by toolsets on unix
  variants, a full version extension is added (e.g. ".so.1.34") and
  a symbolic link to the library file, named without the trailing
  version number, will also be created.

.. .. _Boost.Build toolset names: toolset-name_

__ ../../libs/python/doc/building.html#python-debugging-builds

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

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. Identifying the library binary, among all the build variants,
   whose compile configuration is compatible with the rest of your
   project.

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

.. _Boost.Chrono: ../../libs/chrono/index.html
.. _Boost.Context: ../../libs/context/index.html
.. _Boost.DateTime: ../../libs/date_time/index.html
.. _Boost.Exception: ../../libs/exception/index.html
.. _Boost.Filesystem: ../../libs/filesystem/index.html
.. _Boost.Graph: ../../libs/graph/index.html
.. _Boost.GraphParallel: ../../libs/graph_parallel/index.html
.. _Boost.IOStreams: ../../libs/iostreams/index.html
.. _Boost.Locale: ../../libs/locale/index.html
.. _Boost.Math: ../../libs/math/index.html
.. _Boost.MPI: ../../libs/mpi/index.html
.. _Boost.ProgramOptions: ../../libs/program_options/index.html
.. _Boost.Python: ../../libs/python/doc/building.html
.. _Boost.Random: ../../libs/random/index.html
.. _Boost.Regex: ../../libs/regex/index.html
.. _Boost.Serialization: ../../libs/serialization/index.html
.. _Boost.Signals: ../../libs/signals/index.html
.. _Boost.System: ../../libs/system/index.html
.. _Boost.Test: ../../libs/test/index.html
.. _Boost.Thread: ../../libs/thread/index.html
.. _Boost.Timer: ../../libs/timer/index.html
.. _Boost.Wave: ../../libs/wave/index.html

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

.. This file contains all the definitions that need to be updated
.. for each new release of Boost.

.. |boost-version-number| replace:: 1.55.0
.. |boost_ver| replace:: ``boost_1_55_0``
.. |boost_ver-bold| replace:: **boost_1_55_0**

.. _sf-download: http://www.boost.org/users/history/version_1_55_0.html

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

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.

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.7: http://docutils.sourceforge.net/" />
<title>Boost Getting Started</title>
<link rel="stylesheet" href="../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="logo-getting-started">
<h1 class="title"><a class="reference external" href="../../index.htm"><img alt="Boost" class="boost-logo" src="../../boost.png" /></a> Getting Started</h1>

<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<div class="admonition-use-the-latest-version-of-this-getting-started-guide admonition">
<p class="first admonition-title">Use the latest version of this Getting Started guide</p>
<p class="last">The <a class="reference external" href="http://www.boost.org/more/getting_started/index.html">Boost website version of this Getting Started guide</a> may
have updated information, such as the location of additional installers
or improved installation procedures, so you might want use that version
if you've got an Internet connection available.</p>
</div>
<div class="section" id="welcome">
<h1>Welcome</h1>
<p>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.</p>
</div>
<div class="section" id="what-s-here">
<h1>What's Here</h1>
<p>This document is designed to be an <em>extremely</em> 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.</p>
</div>
<div class="section" id="preliminaries">
<h1>Preliminaries</h1>
<p>We use one typographic convention that might not be immediately
obvious: <em>italic</em> text in examples is meant as a descriptive
placeholder for something else, usually information that you'll
provide.  For example:</p>
<pre class="literal-block">
<strong>$</strong> echo &quot;My name is <em>your name</em>&quot;
</pre>
<p>Here you're expected to imagine replacing the text “your name” with
your actual name.</p>
</div>
<div class="section" id="ready">
<h1>Ready?</h1>
<p>Let's go!</p>
</div>
</div>
<div class="footer">
<hr class="footer" />
<div class="nextpage line-block">
<div class="line"><strong>Next:</strong> <a class="reference external" href="windows.html">Getting Started on Microsoft Windows</a></div>
<div class="line"><strong>or:</strong> <a class="reference external" href="unix-variants.html">Getting Started on Unix variants (e.g. Linux, MacOS)</a></div>
</div>

</div>
</body>
</html>

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

============================
 |(logo)|__ Getting Started
============================

.. |(logo)| image:: ../../boost.png
   :alt: Boost
   :class: boost-logo

__ ../../index.htm

.. Admonition:: Use the latest version of this Getting Started guide

  The `Boost website version of this Getting Started guide`_ may
  have updated information, such as the location of additional installers
  or improved installation procedures, so you might want use that version
  if you've got an Internet connection available.

  .. _`Boost website version of this Getting Started guide`:
       http://www.boost.org/more/getting_started/index.html

Welcome
-------

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.  

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.

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:

.. parsed-literal::

   **$** echo "My name is *your name*\ "

Here you're expected to imagine replacing the text “your name” with
your actual name.

Ready?
------

Let's go!

.. footer::
  .. class:: nextpage

     | **Next:** `Getting Started on Microsoft Windows`__
     | **or:** `Getting Started on Unix variants (e.g. Linux, MacOS)`__

__ windows.html
__ unix-variants.html

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.7: http://docutils.sourceforge.net/" />
<title>Boost Getting Started on Unix Variants</title>
<meta content="Getting Started with Boost on Unix Variants (including Linux and MacOS)" name="description" />
<link rel="stylesheet" href="../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="logo-getting-started-on-unix-variants">
<h1 class="title"><a class="reference external" href="../../index.htm"><img alt="Boost" class="boost-logo" src="../../boost.png" /></a> Getting Started on Unix Variants</h1>

<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<!-- maybe we don't need this
.. Admonition:: A note to Cygwin_ and MinGW_ users

  If you plan to build from the Cygwin_ bash shell, you're in the
  right place.  If you plan to use your tools from the Windows
  command prompt, you should follow the instructions for `getting
  started on Windows`_.  Other command shells, such as MinGW_\ 's
  MSYS, are not supported—they may or may not work.

  .. _`Getting Started on Windows`: windows.html
  .. _Cygwin: http://www.cygwin.com
  .. _MinGW: http://mingw.org -->
<div class="contents topic" id="index">
<p class="topic-title first">Index</p>
<ul class="auto-toc simple">
<li><a class="reference internal" href="#get-boost" id="id19">1&nbsp;&nbsp;&nbsp;Get Boost</a></li>
<li><a class="reference internal" href="#the-boost-distribution" id="id20">2&nbsp;&nbsp;&nbsp;The Boost Distribution</a></li>
<li><a class="reference internal" href="#header-only-libraries" id="id21">3&nbsp;&nbsp;&nbsp;Header-Only Libraries</a></li>
<li><a class="reference internal" href="#build-a-simple-program-using-boost" id="id22">4&nbsp;&nbsp;&nbsp;Build a Simple Program Using Boost</a><ul class="auto-toc">
<li><a class="reference internal" href="#errors-and-warnings" id="id23">4.1&nbsp;&nbsp;&nbsp;Errors and Warnings</a></li>
</ul>
</li>
<li><a class="reference internal" href="#prepare-to-use-a-boost-library-binary" id="id24">5&nbsp;&nbsp;&nbsp;Prepare to Use a Boost Library Binary</a><ul class="auto-toc">
<li><a class="reference internal" href="#easy-build-and-install" id="id25">5.1&nbsp;&nbsp;&nbsp;Easy Build and Install</a></li>
<li><a class="reference internal" href="#or-build-custom-binaries" id="id26">5.2&nbsp;&nbsp;&nbsp;Or, Build Custom Binaries</a><ul class="auto-toc">
<li><a class="reference internal" href="#install-boost-build" id="id27">5.2.1&nbsp;&nbsp;&nbsp;Install Boost.Build</a></li>
<li><a class="reference internal" href="#identify-your-toolset" id="id28">5.2.2&nbsp;&nbsp;&nbsp;Identify Your Toolset</a></li>
<li><a class="reference internal" href="#select-a-build-directory" id="id29">5.2.3&nbsp;&nbsp;&nbsp;Select a Build Directory</a></li>
<li><a class="reference internal" href="#invoke-b2" id="id30">5.2.4&nbsp;&nbsp;&nbsp;Invoke <tt class="docutils literal">b2</tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#expected-build-output" id="id31">5.3&nbsp;&nbsp;&nbsp;Expected Build Output</a></li>
<li><a class="reference internal" href="#in-case-of-build-errors" id="id32">5.4&nbsp;&nbsp;&nbsp;In Case of Build Errors</a></li>
</ul>
</li>
<li><a class="reference internal" href="#link-your-program-to-a-boost-library" id="id33">6&nbsp;&nbsp;&nbsp;Link Your Program to a Boost Library</a><ul class="auto-toc">
<li><a class="reference internal" href="#library-naming" id="id34">6.1&nbsp;&nbsp;&nbsp;Library Naming</a></li>
<li><a class="reference internal" href="#test-your-program" id="id35">6.2&nbsp;&nbsp;&nbsp;Test Your Program</a></li>
</ul>
</li>
<li><a class="reference internal" href="#conclusion-and-further-resources" id="id36">7&nbsp;&nbsp;&nbsp;Conclusion and Further Resources</a></li>
</ul>
</div>
<div class="section" id="get-boost">
<h1><a class="toc-backref" href="#id19">1&nbsp;&nbsp;&nbsp;Get Boost</a></h1>
<p>The most reliable way to get a copy of Boost is to download a
distribution from <a class="reference external" href="http://www.boost.org/users/history/version_1_55_0.html">SourceForge</a>:</p>
<ol class="arabic">
<li><p class="first">Download <a class="reference external" href="http://www.boost.org/users/history/version_1_55_0.html"><tt class="docutils literal">boost_1_55_0</tt><tt class="docutils literal">.tar.bz2</tt></a>.</p>
</li>
<li><p class="first">In the directory where you want to put the Boost installation,
execute</p>
<pre class="literal-block">
tar --bzip2 -xf <em>/path/to/</em><tt class="docutils literal">boost_1_55_0</tt>.tar.bz2
</pre>
</li>
</ol>
<div class="admonition-other-packages admonition">
<p class="first admonition-title">Other Packages</p>
<p class="last">RedHat, Debian, and other distribution packagers supply Boost
library packages, however you may need to adapt these
instructions if you use third-party packages, because their
creators usually choose to break Boost up into several packages,
reorganize the directory structure of the Boost distribution,
and/or rename the library binaries.<a class="footnote-reference" href="#packagers" id="id2"><sup>1</sup></a> If you have
any trouble, we suggest using an official Boost distribution
from <a class="reference external" href="http://www.boost.org/users/history/version_1_55_0.html">SourceForge</a>.</p>
</div>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
</div>
<div class="section" id="the-boost-distribution">
<h1><a class="toc-backref" href="#id20">2&nbsp;&nbsp;&nbsp;The Boost Distribution</a></h1>
<p>This is a sketch of the resulting directory structure:</p>
<pre class="literal-block">
<strong>boost_1_55_0</strong><strong>/</strong> .................<em>The “boost root directory”</em>
   <strong>index.htm</strong> .........<em>A copy of www.boost.org starts here</em>
   <strong>boost</strong><strong>/</strong> .........................<em>All Boost Header files</em>
   <tt class="docutils literal"> </tt>
   <strong>libs</strong><strong>/</strong> ............<em>Tests, .cpp</em>s<em>, docs, etc., by library</em>
     <strong>index.html</strong> ........<em>Library documentation starts here</em>
     <strong>algorithm</strong><strong>/</strong>
     <strong>any</strong><strong>/</strong>
     <strong>array</strong><strong>/</strong>
                     <em>…more libraries…</em>
   <strong>status</strong><strong>/</strong> .........................<em>Boost-wide test suite</em>
   <strong>tools</strong><strong>/</strong> ...........<em>Utilities, e.g. Boost.Build, quickbook, bcp</em>
   <strong>more</strong><strong>/</strong> ..........................<em>Policy documents, etc.</em>
   <strong>doc</strong><strong>/</strong> ...............<em>A subset of all Boost library docs</em>
</pre>
<div class="sidebar">
<p class="first sidebar-title">Header Organization</p>
<p class="pre-wrap">The organization of Boost library headers isn't entirely uniform,
but most libraries follow a few patterns:</p>
<ul class="pre-wrap last">
<li><p class="first">Some older libraries and most very small libraries place all
public headers directly into <tt class="docutils literal">boost</tt><tt class="docutils literal">/</tt>.</p>
</li>
<li><p class="first">Most libraries' public headers live in a subdirectory of
<tt class="docutils literal">boost</tt><tt class="docutils literal">/</tt>, named after the library.  For example, you'll find
the Python library's <tt class="docutils literal">def.hpp</tt> header in</p>
<pre class="literal-block">
<tt class="docutils literal">boost</tt><tt class="docutils literal">/</tt><tt class="docutils literal">python</tt><tt class="docutils literal">/</tt><tt class="docutils literal">def.hpp</tt>.
</pre>
</li>
<li><p class="first">Some libraries have an “aggregate header” in <tt class="docutils literal">boost</tt><tt class="docutils literal">/</tt> that
<tt class="docutils literal">#include</tt>s all of the library's other headers.  For
example, <a class="reference external" href="../../libs/python/doc/building.html">Boost.Python</a>'s aggregate header is</p>
<pre class="literal-block">
<tt class="docutils literal">boost</tt><tt class="docutils literal">/</tt><tt class="docutils literal">python.hpp</tt>.
</pre>
</li>
<li><p class="first">Most libraries place private headers in a subdirectory called
<tt class="docutils literal">detail</tt><tt class="docutils literal">/</tt>, or <tt class="docutils literal">aux_</tt><tt class="docutils literal">/</tt>.  Don't expect to find
anything you can use in these directories.</p>
</li>
</ul>
</div>
<p>It's important to note the following:</p>
<ol class="arabic" id="boost-root-directory">
<li><p class="first">The path to the <strong>boost root directory</strong> (often <tt class="docutils literal">/usr/local/</tt><tt class="docutils literal">boost_1_55_0</tt>) is
sometimes referred to as <tt class="docutils literal">$BOOST_ROOT</tt> in documentation and
mailing lists .</p>
</li>
<li><p class="first">To compile anything in Boost, you need a directory containing
the <tt class="docutils literal">boost</tt><tt class="docutils literal">/</tt> subdirectory in your <tt class="docutils literal">#include</tt> path.  <tt class="docutils literal"> </tt></p>
</li>
<li><p class="first">Since all of Boost's header files have the <tt class="docutils literal">.hpp</tt> extension,
and live in the <tt class="docutils literal">boost</tt><tt class="docutils literal">/</tt> subdirectory of the boost root, your
Boost <tt class="docutils literal">#include</tt> directives will look like:</p>
<pre class="literal-block">
#include &lt;boost/<em>whatever</em>.hpp&gt;
</pre>
<p>or</p>
<pre class="literal-block">
#include &quot;boost/<em>whatever</em>.hpp&quot;
</pre>
<p>depending on your preference regarding the use of angle bracket
includes.  <tt class="docutils literal"> </tt></p>
</li>
<li><p class="first">Don't be distracted by the <tt class="docutils literal">doc</tt><tt class="docutils literal">/</tt> subdirectory; it only
contains a subset of the Boost documentation.  Start with
<tt class="docutils literal">libs</tt><tt class="docutils literal">/</tt><tt class="docutils literal">index.html</tt> if you're looking for the whole enchilada.</p>
</li>
</ol>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
</div>
<div class="section" id="header-only-libraries">
<h1><a class="toc-backref" href="#id21">3&nbsp;&nbsp;&nbsp;Header-Only Libraries</a></h1>
<p>The first thing many people want to know is, “how do I build
Boost?”  The good news is that often, there's nothing to build.</p>
<div class="admonition-nothing-to-build admonition">
<p class="first admonition-title">Nothing to Build?</p>
<p class="last">Most Boost libraries are <strong>header-only</strong>: they consist <em>entirely
of header files</em> containing templates and inline functions, and
require no separately-compiled library binaries or special
treatment when linking.</p>
</div>
<!-- .. _separate: -->
<p>The only Boost libraries that <em>must</em> be built separately are:</p>
<ul class="simple">
<li><a class="reference external" href="../../libs/chrono/index.html">Boost.Chrono</a></li>
<li><a class="reference external" href="../../libs/context/index.html">Boost.Context</a></li>
<li><a class="reference external" href="../../libs/filesystem/index.html">Boost.Filesystem</a></li>
<li><a class="reference external" href="../../libs/graph_parallel/index.html">Boost.GraphParallel</a></li>
<li><a class="reference external" href="../../libs/iostreams/index.html">Boost.IOStreams</a></li>
<li><a class="reference external" href="../../libs/locale/index.html">Boost.Locale</a></li>
<li><a class="reference external" href="../../libs/mpi/index.html">Boost.MPI</a></li>
<li><a class="reference external" href="../../libs/program_options/index.html">Boost.ProgramOptions</a></li>
<li><a class="reference external" href="../../libs/python/doc/building.html">Boost.Python</a> (see the <a class="reference external" href="../../libs/python/doc/building.html">Boost.Python build documentation</a>
before building and installing it)</li>
<li><a class="reference external" href="../../libs/regex/index.html">Boost.Regex</a></li>
<li><a class="reference external" href="../../libs/serialization/index.html">Boost.Serialization</a></li>
<li><a class="reference external" href="../../libs/signals/index.html">Boost.Signals</a></li>
<li><a class="reference external" href="../../libs/system/index.html">Boost.System</a></li>
<li><a class="reference external" href="../../libs/thread/index.html">Boost.Thread</a></li>
<li><a class="reference external" href="../../libs/timer/index.html">Boost.Timer</a></li>
<li><a class="reference external" href="../../libs/wave/index.html">Boost.Wave</a></li>
</ul>
<p>A few libraries have optional separately-compiled binaries:</p>
<ul class="simple">
<li><a class="reference external" href="../../libs/date_time/index.html">Boost.DateTime</a> has a binary component that is only needed if
you're using its <tt class="docutils literal">to_string</tt>/<tt class="docutils literal">from_string</tt> or serialization
features, or if you're targeting Visual C++ 6.x or Borland.</li>
<li><a class="reference external" href="../../libs/graph/index.html">Boost.Graph</a> also has a binary component that is only needed if
you intend to <a class="reference external" href="../../libs/graph/doc/read_graphviz.html">parse GraphViz files</a>.</li>
<li><a class="reference external" href="../../libs/math/index.html">Boost.Math</a> has binary components for the TR1 and C99
cmath functions.</li>
<li><a class="reference external" href="../../libs/random/index.html">Boost.Random</a> has a binary component which is only needed if
you're using <tt class="docutils literal">random_device</tt>.</li>
<li><a class="reference external" href="../../libs/test/index.html">Boost.Test</a> can be used in “header-only” or “separately compiled”
mode, although <strong>separate compilation is recommended for serious
use</strong>.</li>
<li><a class="reference external" href="../../libs/exception/index.html">Boost.Exception</a> provides non-intrusive implementation of
exception_ptr for 32-bit _MSC_VER==1310 and _MSC_VER==1400
which requires a separately-compiled binary. This is enabled by
#define BOOST_ENABLE_NON_INTRUSIVE_EXCEPTION_PTR.</li>
</ul>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
</div>
<div class="section" id="build-a-simple-program-using-boost">
<h1><a class="toc-backref" href="#id22">4&nbsp;&nbsp;&nbsp;Build a Simple Program Using Boost</a></h1>
<p>To keep things simple, let's start by using a header-only library.
The following program reads a sequence of integers from standard
input, uses Boost.Lambda to multiply each number by three, and
writes them to standard output:</p>
<pre class="literal-block">
#include &lt;boost/lambda/lambda.hpp&gt;
#include &lt;iostream&gt;
#include &lt;iterator&gt;
#include &lt;algorithm&gt;

int main()
{
    using namespace boost::lambda;
    typedef std::istream_iterator&lt;int&gt; in;

    std::for_each(
        in(std::cin), in(), std::cout &lt;&lt; (_1 * 3) &lt;&lt; &quot; &quot; );
}
</pre>
<p>Copy the text of this program into a file called <tt class="docutils literal">example.cpp</tt>.</p>
<p>Now, in the directory where you saved <tt class="docutils literal">example.cpp</tt>, issue the
following command:</p>
<pre class="literal-block">
c++ -I <em>path/to/</em><tt class="docutils literal">boost_1_55_0</tt> example.cpp -o example
</pre>
<p>To test the result, type:</p>
<pre class="literal-block">
echo 1 2 3 | ./example
</pre>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<div class="section" id="errors-and-warnings">
<h2><a class="toc-backref" href="#id23">4.1&nbsp;&nbsp;&nbsp;Errors and Warnings</a></h2>
<p>Don't be alarmed if you see compiler warnings originating in Boost
headers.  We try to eliminate them, but doing so isn't always
practical.<a class="footnote-reference" href="#warnings" id="id5"><sup>3</sup></a> <strong>Errors are another matter</strong>.  If you're
seeing compilation errors at this point in the tutorial, check to
be sure you've copied the <a class="reference internal" href="#build-a-simple-program-using-boost">example program</a> correctly and that you've
correctly identified the <a class="reference internal" href="#boost-root-directory">Boost root directory</a>.</p>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
</div>
</div>
<div class="section" id="prepare-to-use-a-boost-library-binary">
<h1><a class="toc-backref" href="#id24">5&nbsp;&nbsp;&nbsp;Prepare to Use a Boost Library Binary</a></h1>
<p>If you want to use any of the separately-compiled Boost libraries,
you'll need to acquire library binaries.</p>
<div class="section" id="easy-build-and-install">
<h2><a class="toc-backref" href="#id25">5.1&nbsp;&nbsp;&nbsp;Easy Build and Install</a></h2>
<p>Issue the following commands in the shell (don't type <tt class="docutils literal">$</tt>; that
represents the shell's prompt):</p>
<pre class="literal-block">
<strong>$</strong> cd <em>path/to/</em><tt class="docutils literal">boost_1_55_0</tt>
<strong>$</strong> ./bootstrap.sh --help
</pre>
<p>Select your configuration options and invoke <tt class="docutils literal">./bootstrap.sh</tt> again
without the <tt class="docutils literal"><span class="pre">--help</span></tt> option.  Unless you have write permission in
your system's <tt class="docutils literal">/usr/local/</tt> directory, you'll probably want to at
least use</p>
<pre class="literal-block">
<strong>$</strong> ./bootstrap.sh <strong>--prefix=</strong><em>path</em>/<em>to</em>/<em>installation</em>/<em>prefix</em>
</pre>
<p>to install somewhere else.  Also, consider using the
<tt class="docutils literal"><span class="pre">--show-libraries</span></tt> and <tt class="docutils literal"><span class="pre">--with-libraries=</span></tt><em>library-name-list</em> options to limit the
long wait you'll experience if you build everything.  Finally,</p>
<pre class="literal-block">
<strong>$</strong> ./b2 install
</pre>
<p>will leave Boost binaries in the <tt class="docutils literal">lib/</tt> subdirectory of your
installation prefix.  You will also find a copy of the Boost
headers in the <tt class="docutils literal">include/</tt> subdirectory of the installation
prefix, so you can henceforth use that directory as an <tt class="docutils literal">#include</tt>
path in place of the Boost root directory.</p>
<p><a class="reference internal" href="#link-your-program-to-a-boost-library"><em>skip to the next step</em></a></p>
</div>
<div class="section" id="or-build-custom-binaries">
<h2><a class="toc-backref" href="#id26">5.2&nbsp;&nbsp;&nbsp;Or, Build Custom Binaries</a></h2>
<p>If you're using a compiler other than your system's default, you'll
need to use <a class="reference external" href="../../tools/build/index.html">Boost.Build</a> to create binaries.</p>
<p>You'll also
use this method if you need a nonstandard build variant (see the
<a class="reference external" href="../../tools/build/index.html">Boost.Build documentation</a> for more details).</p>
<div class="admonition-boost-cmake admonition">
<p class="first admonition-title">Boost.CMake</p>
<p class="last">There is also an experimental CMake build for boost, supported and distributed
separately.  See the <a class="reference external" href="https://svn.boost.org/trac/boost/wiki/CMake">Boost.CMake</a> wiki page for more information.</p>
</div>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<div class="section" id="install-boost-build">
<h3><a class="toc-backref" href="#id27">5.2.1&nbsp;&nbsp;&nbsp;Install Boost.Build</a></h3>
<p><a class="reference external" href="../../tools/build/index.html">Boost.Build</a> is a text-based system for developing, testing, and
installing software. First, you'll need to build and
install it. To do this:</p>
<ol class="arabic simple">
<li>Go to the directory <tt class="docutils literal">tools</tt><tt class="docutils literal">/</tt><tt class="docutils literal">build</tt><tt class="docutils literal">/</tt><tt class="docutils literal">v2</tt><tt class="docutils literal">/</tt>.</li>
<li>Run <tt class="docutils literal">bootstrap.sh</tt></li>
<li>Run <tt class="docutils literal">b2 install <span class="pre">--prefix=</span></tt><em>PREFIX</em> where <em>PREFIX</em> is
the directory where you want Boost.Build to be installed</li>
<li>Add <em>PREFIX</em><tt class="docutils literal">/</tt><tt class="docutils literal">bin</tt> to your PATH environment variable.</li>
</ol>
</div>
<div class="section" id="identify-your-toolset">
<span id="toolset-name"></span><span id="toolset"></span><h3><a class="toc-backref" href="#id28">5.2.2&nbsp;&nbsp;&nbsp;Identify Your Toolset</a></h3>
<p>First, find the toolset corresponding to your compiler in the
following table (an up-to-date list is always available <a class="reference external" href="http://www.boost.org/boost-build2/doc/html/bbv2/reference/tools.html">in the
Boost.Build documentation</a>).</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">If you previously chose a toolset for the purposes of
<a class="reference external" href="../../doc/html/bbv2/installation.html">building b2</a>, you should assume it won't work and instead
choose newly from the table below.</p>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="33%" />
<col width="48%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Toolset
Name</th>
<th class="head">Vendor</th>
<th class="head">Notes</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal">acc</tt></td>
<td>Hewlett Packard</td>
<td>Only very recent versions are
known to work well with Boost</td>
</tr>
<tr><td><tt class="docutils literal">borland</tt></td>
<td>Borland</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal">como</tt></td>
<td>Comeau Computing</td>
<td>Using this toolset may
require <a class="reference external" href="../../tools/build/index.html">configuring</a> another
toolset to act as its backend</td>
</tr>
<tr><td><tt class="docutils literal">darwin</tt></td>
<td>Apple Computer</td>
<td>Apple's version of the GCC
toolchain with support for
Darwin and MacOS X features
such as frameworks.</td>
</tr>
<tr><td><tt class="docutils literal">gcc</tt></td>
<td>The Gnu Project</td>
<td>Includes support for Cygwin
and MinGW compilers.</td>
</tr>
<tr><td><tt class="docutils literal">hp_cxx</tt></td>
<td>Hewlett Packard</td>
<td>Targeted at the Tru64
operating system.</td>
</tr>
<tr><td><tt class="docutils literal">intel</tt></td>
<td>Intel</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal">msvc</tt></td>
<td>Microsoft</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal">sun</tt></td>
<td>Sun</td>
<td>Only very recent versions are
known to work well with
Boost.</td>
</tr>
<tr><td><tt class="docutils literal">vacpp</tt></td>
<td>IBM</td>
<td>The VisualAge C++ compiler.</td>
</tr>
</tbody>
</table>
<p>If you have multiple versions of a particular compiler installed,
you can append the version number to the toolset name, preceded by
a hyphen, e.g. <tt class="docutils literal"><span class="pre">intel-9.0</span></tt> or
<tt class="docutils literal"><span class="pre">borland-5.4.3</span></tt>. <tt class="docutils literal"> </tt></p>
</div>
<div class="section" id="select-a-build-directory">
<span id="id10"></span><span id="build-directory"></span><h3><a class="toc-backref" href="#id29">5.2.3&nbsp;&nbsp;&nbsp;Select a Build Directory</a></h3>
<p><a class="reference external" href="../../tools/build/index.html">Boost.Build</a> will place all intermediate files it generates while
building into the <strong>build directory</strong>.  If your Boost root
directory is writable, this step isn't strictly necessary: by
default Boost.Build will create a <tt class="docutils literal">bin.v2/</tt> subdirectory for that
purpose in your current working directory.</p>
</div>
<div class="section" id="invoke-b2">
<h3><a class="toc-backref" href="#id30">5.2.4&nbsp;&nbsp;&nbsp;Invoke <tt class="docutils literal">b2</tt></a></h3>
<p>Change your current directory to the Boost root directory and
invoke <tt class="docutils literal">b2</tt> as follows:</p>
<pre class="literal-block">
b2 <strong>--build-dir=</strong><a class="reference internal" href="#id10"><em>build-directory</em></a> <strong>toolset=</strong><a class="reference internal" href="#toolset-name"><em>toolset-name</em></a> <tt class="docutils literal"> </tt> stage
</pre>
<p>For a complete description of these and other invocation options,
please see the <a class="reference external" href="http://www.boost.org/boost-build2/doc/html/bbv2/advanced/invocation.html">Boost.Build documentation</a>.</p>
<p>For example, your session might look like this:</p>
<pre class="literal-block">
$ cd ~/<tt class="docutils literal">boost_1_55_0</tt>
$ b2 <strong>--build-dir=</strong>/tmp/build-boost <strong>toolset=</strong>gcc stage
</pre>
<p>That will build static and shared non-debug multi-threaded variants of the libraries. To build all variants, pass the additional option, “<tt class="docutils literal"><span class="pre">--build-type=complete</span></tt>”.</p>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<p>Building the special <tt class="docutils literal">stage</tt> target places Boost
library binaries in the <tt class="docutils literal">stage</tt><tt class="docutils literal">/</tt><tt class="docutils literal">lib</tt><tt class="docutils literal">/</tt> subdirectory of
the Boost tree.  To use a different directory pass the
<tt class="docutils literal"><span class="pre">--stagedir=</span></tt><em>directory</em> option to <tt class="docutils literal">b2</tt>.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last"><tt class="docutils literal">b2</tt> is case-sensitive; it is important that all the
parts shown in <strong>bold</strong> type above be entirely lower-case.</p>
</div>
<p>For a description of other options you can pass when invoking
<tt class="docutils literal">b2</tt>, type:</p>
<pre class="literal-block">
b2 --help
</pre>
<p>In particular, to limit the amount of time spent building, you may
be interested in:</p>
<ul class="simple">
<li>reviewing the list of library names with <tt class="docutils literal"><span class="pre">--show-libraries</span></tt></li>
<li>limiting which libraries get built with the <tt class="docutils literal"><span class="pre">--with-</span></tt><em>library-name</em> or <tt class="docutils literal"><span class="pre">--without-</span></tt><em>library-name</em> options</li>
<li>choosing a specific build variant by adding <tt class="docutils literal">release</tt> or
<tt class="docutils literal">debug</tt> to the command line.</li>
</ul>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Boost.Build can produce a great deal of output, which can
make it easy to miss problems.  If you want to make sure
everything is went well, you might redirect the output into a
file by appending “<tt class="docutils literal">&gt;build.log <span class="pre">2&gt;&amp;1</span></tt>” to your command line.</p>
</div>
</div>
</div>
<div class="section" id="expected-build-output">
<h2><a class="toc-backref" href="#id31">5.3&nbsp;&nbsp;&nbsp;Expected Build Output</a></h2>
<p>During the process of building Boost libraries, you can expect to
see some messages printed on the console.  These may include</p>
<ul>
<li><p class="first">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.</p>
</li>
<li><p class="first">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.</p>
</li>
<li><p class="first">Build action messages describing what the tool is doing, which
look something like:</p>
<pre class="literal-block">
<em>toolset-name</em>.c++ <em>long</em>/<em>path</em>/<em>to</em>/<em>file</em>/<em>being</em>/<em>built</em>
</pre>
</li>
<li><p class="first">Compiler warnings.</p>
</li>
</ul>
</div>
<div class="section" id="in-case-of-build-errors">
<h2><a class="toc-backref" href="#id32">5.4&nbsp;&nbsp;&nbsp;In Case of Build Errors</a></h2>
<p>The only error messages you see when building Boost—if any—should
be related to the IOStreams library's support of zip and bzip2
formats as described <a class="reference external" href="../../libs/iostreams/doc/installation.html">here</a>.  Install the relevant development
packages for libz and libbz2 if you need those features.  Other
errors when building Boost libraries are cause for concern.</p>
<p>If it seems like the build system can't find your compiler and/or
linker, consider setting up a <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file as described
<a class="reference external" href="http://www.boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html">here</a>.  If that isn't your problem or the <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file
doesn't work for you, please address questions about configuring Boost
for your compiler to the <a class="reference external" href="http://www.boost.org/more/mailing_lists.htm#jamboost">Boost.Build mailing list</a>.</p>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
</div>
</div>
<div class="section" id="link-your-program-to-a-boost-library">
<h1><a class="toc-backref" href="#id33">6&nbsp;&nbsp;&nbsp;Link Your Program to a Boost Library</a></h1>
<p>To demonstrate linking with a Boost binary library, we'll use the
following simple program that extracts the subject lines from
emails.  It uses the <a class="reference external" href="../../libs/regex/index.html">Boost.Regex</a> library, which has a
separately-compiled binary component.</p>
<pre class="literal-block">
#include &lt;boost/regex.hpp&gt;
#include &lt;iostream&gt;
#include &lt;string&gt;

int main()
{
    std::string line;
    boost::regex pat( &quot;^Subject: (Re: |Aw: )*(.*)&quot; );

    while (std::cin)
    {
        std::getline(std::cin, line);
        boost::smatch matches;
        if (boost::regex_match(line, matches, pat))
            std::cout &lt;&lt; matches[2] &lt;&lt; std::endl;
    }
}
</pre>
<p>There are two main challenges associated with linking:</p>
<ol class="arabic simple">
<li>Tool configuration, e.g. choosing command-line options or IDE
build settings.</li>
<li>Identifying the library binary, among all the build variants,
whose compile configuration is compatible with the rest of your
project.</li>
</ol>
<p>There are two main ways to link to libraries:</p>
<ol class="upperalpha">
<li><p class="first">You can specify the full path to each library:</p>
<pre class="literal-block">
$ c++ -I <em>path/to/</em><tt class="docutils literal">boost_1_55_0</tt> example.cpp -o example <strong>\</strong>
   <strong>~/boost/stage/lib/libboost_regex-gcc34-mt-d-1_36.a</strong>
</pre>
</li>
<li><p class="first">You can separately specify a directory to search (with <tt class="docutils literal"><span class="pre">-L</span></tt><em>directory</em>) and a library name to search for (with <tt class="docutils literal"><span class="pre">-l</span></tt><em>library</em>,<a class="footnote-reference" href="#lowercase-l" id="id14"><sup>2</sup></a> dropping the filename's leading <tt class="docutils literal">lib</tt> and trailing
suffix (<tt class="docutils literal">.a</tt> in this case):</p>
<pre class="literal-block">
$ c++ -I <em>path/to/</em><tt class="docutils literal">boost_1_55_0</tt> example.cpp -o example <strong>\</strong>
   <strong>-L~/boost/stage/lib/ -lboost_regex-gcc34-mt-d-1_36</strong>
</pre>
<p>As you can see, this method is just as terse as method A for one
library; it <em>really</em> 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 (<tt class="docutils literal">.a</tt>) and
dynamic (<tt class="docutils literal">.so</tt>) builds, the system may choose one
automatically for you unless you pass a special option such as
<tt class="docutils literal"><span class="pre">-static</span></tt> on the command line.</p>
</li>
</ol>
<p>In both cases above, the bold text is what you'd add to <a class="reference internal" href="#build-a-simple-program-using-boost">the
command lines we explored earlier</a>.</p>
<div class="section" id="library-naming">
<h2><a class="toc-backref" href="#id34">6.1&nbsp;&nbsp;&nbsp;Library Naming</a></h2>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<p>In order to choose the right binary for your build configuration
you need to know how Boost binaries are named.  Each library
filename is composed of a common sequence of elements that describe
how it was built.  For example,
<tt class="docutils literal"><span class="pre">libboost_regex-vc71-mt-d-1_34.lib</span></tt> can be broken down into the
following elements:</p>
<dl class="docutils">
<dt><tt class="docutils literal">lib</tt></dt>
<dd><em>Prefix</em>: except on Microsoft Windows, every Boost library
name begins with this string.  On Windows, only ordinary static
libraries use the <tt class="docutils literal">lib</tt> prefix; import libraries and DLLs do
not.<a class="footnote-reference" href="#distinct" id="id16"><sup>4</sup></a></dd>
<dt><tt class="docutils literal">boost_regex</tt></dt>
<dd><em>Library name</em>: all boost library filenames begin with <tt class="docutils literal">boost_</tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">-vc71</span></tt></dt>
<dd><em>Toolset tag</em>: identifies the <a class="reference internal" href="#toolset">toolset</a> and version used to build
the binary.</dd>
<dt><tt class="docutils literal"><span class="pre">-mt</span></tt></dt>
<dd><em>Threading tag</em>: indicates that the library was
built with multithreading support enabled.  Libraries built
without multithreading support can be identified by the absence
of <tt class="docutils literal"><span class="pre">-mt</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">-d</span></tt></dt>
<dd><p class="first"><em>ABI tag</em>: encodes details that affect the library's
interoperability with other compiled code.  For each such
feature, a single letter is added to the tag:</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="5%" />
<col width="75%" />
<col width="20%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Key</th>
<th class="head">Use this library when:</th>
<th class="head">Boost.Build option</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal">s</tt></td>
<td>linking statically to the C++ standard library and compiler runtime support
libraries.</td>
<td>runtime-link=static</td>
</tr>
<tr><td><tt class="docutils literal">g</tt></td>
<td>using debug versions of the standard and runtime support libraries.</td>
<td>runtime-debugging=on</td>
</tr>
<tr><td><tt class="docutils literal">y</tt></td>
<td>using a special <a class="reference external" href="../../libs/python/doc/building.html#python-debugging-builds">debug build of Python</a>.</td>
<td>python-debugging=on</td>
</tr>
<tr><td><tt class="docutils literal">d</tt></td>
<td>building a debug version of your code.<a class="footnote-reference" href="#debug-abi" id="id17"><sup>5</sup></a></td>
<td>variant=debug</td>
</tr>
<tr><td><tt class="docutils literal">p</tt></td>
<td>using the STLPort standard library rather than the default one supplied with
your compiler.</td>
<td>stdlib=stlport</td>
</tr>
</tbody>
</table>
</blockquote>
<p class="last">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: <tt class="docutils literal"><span class="pre">-sgdpn</span></tt>.  If none of the above apply, the
ABI tag is ommitted.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">-1_34</span></tt></dt>
<dd><em>Version tag</em>: the full Boost release number, with periods
replaced by underscores. For example, version 1.31.1 would be
tagged as &quot;-1_31_1&quot;.</dd>
<dt><tt class="docutils literal">.lib</tt></dt>
<dd><em>Extension</em>: determined according to the operating system's usual
convention.  On most unix-style platforms the extensions are
<tt class="docutils literal">.a</tt> and <tt class="docutils literal">.so</tt> for static libraries (archives) and shared
libraries, respectively.  On Windows, <tt class="docutils literal">.dll</tt> indicates a shared
library and <tt class="docutils literal">.lib</tt> indicates a
static or import library.  Where supported by toolsets on unix
variants, a full version extension is added (e.g. &quot;.so.1.34&quot;) and
a symbolic link to the library file, named without the trailing
version number, will also be created.</dd>
</dl>
<!-- .. _Boost.Build toolset names: toolset-name_ -->
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
</div>
<div class="section" id="test-your-program">
<h2><a class="toc-backref" href="#id35">6.2&nbsp;&nbsp;&nbsp;Test Your Program</a></h2>
<p>To test our subject extraction, we'll filter the following text
file.  Copy it out of your browser and save it as <tt class="docutils literal">jayne.txt</tt>:</p>
<pre class="literal-block">
To: George Shmidlap
From: Rita Marlowe
Subject: Will Success Spoil Rock Hunter?
---
See subject.
</pre>
<p>If you linked to a shared library, you may need to prepare some
platform-specific settings so that the system will be able to find
and load it when your program is run.  Most platforms have an
environment variable to which you can add the directory containing
the library.  On many platforms (Linux, FreeBSD) that variable is
<tt class="docutils literal">LD_LIBRARY_PATH</tt>, but on MacOS it's <tt class="docutils literal">DYLD_LIBRARY_PATH</tt>, and
on Cygwin it's simply <tt class="docutils literal">PATH</tt>.  In most shells other than <tt class="docutils literal">csh</tt>
and <tt class="docutils literal">tcsh</tt>, you can adjust the variable as follows (again, don't
type the <tt class="docutils literal">$</tt>—that represents the shell prompt):</p>
<pre class="literal-block">
<strong>$</strong> <em>VARIABLE_NAME</em>=<em>path/to/lib/directory</em>:${<em>VARIABLE_NAME</em>}
<strong>$</strong> export <em>VARIABLE_NAME</em>
</pre>
<p>On <tt class="docutils literal">csh</tt> and <tt class="docutils literal">tcsh</tt>, it's</p>
<pre class="literal-block">
<strong>$</strong> setenv <em>VARIABLE_NAME</em> <em>path/to/lib/directory</em>:${<em>VARIABLE_NAME</em>}
</pre>
<p>Once the necessary variable (if any) is set, you can run your
program as follows:</p>
<pre class="literal-block">
<strong>$</strong> <em>path</em>/<em>to</em>/<em>compiled</em>/example &lt; <em>path</em>/<em>to</em>/jayne.txt
</pre>
<p>The program should respond with the email subject, “Will Success
Spoil Rock Hunter?”</p>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
</div>
</div>
<div class="section" id="conclusion-and-further-resources">
<h1><a class="toc-backref" href="#id36">7&nbsp;&nbsp;&nbsp;Conclusion and Further Resources</a></h1>
<p>This concludes your introduction to Boost and to integrating it
with your programs.  As you start using Boost in earnest, there are
surely a few additional points you'll wish we had covered.  One day
we may have a “Book 2 in the Getting Started series” that addresses
them.  Until then, we suggest you pursue the following resources.
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 <a class="reference external" href="http://www.boost.org/more/mailing_lists.htm#users">Boost Users'
mailing list</a>.</p>
<ul class="simple">
<li><a class="reference external" href="../../tools/build/v2/index.html">Boost.Build reference manual</a></li>
<li><a class="reference external" href="http://www.boost.org/more/mailing_lists.htm#users">Boost Users' mailing list</a></li>
<li><a class="reference external" href="http://www.boost.org/more/mailing_lists.htm#jamboost">Boost.Build mailing list</a></li>
<li><a class="reference external" href="../../libs/index.html">Index of all Boost library documentation</a></li>
</ul>
<div class="admonition-onward admonition">
<p class="first admonition-title">Onward</p>
<blockquote class="epigraph last">
<p>Good luck, and have fun!</p>
<p class="attribution">&mdash;the Boost Developers</p>
</blockquote>
</div>
<hr class="docutils" />
<table class="docutils footnote" frame="void" id="packagers" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[1]</a></td><td>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 <a class="reference external" href="http://www.boost.org/more/mailing_lists.htm#main">Boost developers' list</a>.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="lowercase-l" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id14">[2]</a></td><td>That option is a dash followed by a lowercase “L”
character, which looks very much like a numeral 1 in some fonts.</td></tr>
</tbody>
</table>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<table class="docutils footnote" frame="void" id="warnings" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id5">[3]</a></td><td>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.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="distinct" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id16">[4]</a></td><td>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.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="debug-abi" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id17">[5]</a></td><td>These libraries were compiled without optimization
or inlining, with full debug symbols enabled, and without
<tt class="docutils literal">NDEBUG</tt> <tt class="docutils literal">#define</tt>d.  Although it's true that sometimes
these choices don't affect binary compatibility with other
compiled code, you can't count on that with Boost libraries.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="native" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[6]</td><td>This feature of STLPort is deprecated because it's
impossible to make it work transparently to the user; we don't
recommend it.</td></tr>
</tbody>
</table>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<!-- This file contains all the definitions that need to be updated -->
<!-- for each new release of Boost. -->
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
</div>
</div>
</body>
</html>

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

=============================================
 |(logo)|__ Getting Started on Unix Variants
=============================================

.. meta::
    :description: Getting Started with Boost on Unix Variants (including Linux and MacOS)

.. |(logo)| image:: ../../boost.png
   :alt: Boost
   :class: boost-logo

__ ../../index.htm

.. section-numbering::

.. maybe we don't need this
   .. Admonition:: A note to Cygwin_ and MinGW_ users

     If you plan to build from the Cygwin_ bash shell, you're in the
     right place.  If you plan to use your tools from the Windows
     command prompt, you should follow the instructions for `getting
     started on Windows`_.  Other command shells, such as MinGW_\ 's
     MSYS, are not supported—they may or may not work.

     .. _`Getting Started on Windows`: windows.html
     .. _Cygwin: http://www.cygwin.com
     .. _MinGW: http://mingw.org

.. Contents:: Index

Get Boost
=========

The most reliable way to get a copy of Boost is to download a
distribution from SourceForge_:

.. _SourceForge: `sf-download`_

1. Download |boost.tar.bz2|_.  

2. In the directory where you want to put the Boost installation,
   execute

   .. parsed-literal::

      tar --bzip2 -xf */path/to/*\ |boost_ver|\ .tar.bz2

.. |boost.tar.bz2| replace:: |boost_ver|\ ``.tar.bz2``

.. _`boost.tar.bz2`: `sf-download`_

.. Admonition:: Other Packages

   RedHat, Debian, and other distribution packagers supply Boost
   library packages, however you may need to adapt these
   instructions if you use third-party packages, because their
   creators usually choose to break Boost up into several packages,
   reorganize the directory structure of the Boost distribution,
   and/or rename the library binaries. [#packagers]_ If you have
   any trouble, we suggest using an official Boost distribution
   from SourceForge_.

.. include:: detail/distro.rst

.. include:: detail/header-only.rst

.. include:: detail/build-simple-head.rst

Now, in the directory where you saved ``example.cpp``, issue the
following command:

.. parsed-literal::

  c++ -I |root| example.cpp -o example

To test the result, type:

.. parsed-literal::

  echo 1 2 3 | ./example

.. include:: detail/errors-and-warnings.rst

.. include:: detail/binary-head.rst

Easy Build and Install
----------------------

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

.. parsed-literal::

  **$** cd |root|
  **$** ./bootstrap.sh --help

Select your configuration options and invoke ``./bootstrap.sh`` again
without the ``--help`` option.  Unless you have write permission in
your system's ``/usr/local/`` directory, you'll probably want to at
least use

.. parsed-literal::

  **$** ./bootstrap.sh **--prefix=**\ *path*\ /\ *to*\ /\ *installation*\ /\ *prefix* 

to install somewhere else.  Also, consider using the
``--show-libraries`` and ``--with-libraries=``\ *library-name-list* options to limit the
long wait you'll experience if you build everything.  Finally,

.. parsed-literal::

  **$** ./b2 install

will leave Boost binaries in the ``lib/`` subdirectory of your
installation prefix.  You will also find a copy of the Boost
headers in the ``include/`` subdirectory of the installation
prefix, so you can henceforth use that directory as an ``#include``
path in place of the Boost root directory.

|next|__

__ `Link Your Program to a Boost Library`_

Or, Build Custom Binaries
-------------------------

If you're using a compiler other than your system's default, you'll
need to use Boost.Build_ to create binaries.

You'll also
use this method if you need a nonstandard build variant (see the
`Boost.Build documentation`_ for more details).

.. Admonition:: Boost.CMake

  There is also an experimental CMake build for boost, supported and distributed
  separately.  See the `Boost.CMake`_ wiki page for more information.

  .. _`Boost.CMake`:
       https://svn.boost.org/trac/boost/wiki/CMake

.. include:: detail/build-from-source-head.rst

For example, your session might look like this:

.. parsed-literal::

   $ cd ~/|boost_ver|
   $ b2 **--build-dir=**\ /tmp/build-boost **toolset=**\ gcc stage

That will build static and shared non-debug multi-threaded variants of the libraries. To build all variants, pass the additional option, “``--build-type=complete``”.

.. include:: detail/build-from-source-tail.rst

.. include:: detail/link-head.rst

There are two main ways to link to libraries:

A. You can specify the full path to each library:

   .. parsed-literal::

     $ c++ -I |root| example.cpp -o example **\\**
        **~/boost/stage/lib/libboost_regex-gcc34-mt-d-1_36.a**

B. You can separately specify a directory to search (with ``-L``\
   *directory*) and a library name to search for (with ``-l``\
   *library*, [#lowercase-l]_ dropping the filename's leading ``lib`` and trailing
   suffix (``.a`` in this case): 

   .. parsed-literal::

     $ c++ -I |root| example.cpp -o example **\\**
        **-L~/boost/stage/lib/ -lboost_regex-gcc34-mt-d-1_36**

   As you can see, this method is just as terse as method A for one
   library; it *really* pays off when you're using multiple
   libraries from the same directory.  Note, however, that if you
   use this method with a library that has both static (``.a``) and
   dynamic (``.so``) builds, the system may choose one
   automatically for you unless you pass a special option such as
   ``-static`` on the command line.

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

__ `build a simple program using boost`_

Library Naming
--------------

.. include:: detail/library-naming.rst

.. include:: detail/test-head.rst

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):

.. parsed-literal::

   **$** *VARIABLE_NAME*\ =\ *path/to/lib/directory*\ :${\ *VARIABLE_NAME*\ }
   **$** export *VARIABLE_NAME*

On ``csh`` and ``tcsh``, it's

.. parsed-literal::

   **$** setenv *VARIABLE_NAME* *path/to/lib/directory*\ :${\ *VARIABLE_NAME*\ }

Once the necessary variable (if any) is set, you can run your
program as follows:

.. parsed-literal::

   **$** *path*\ /\ *to*\ /\ *compiled*\ /\ example < *path*\ /\ *to*\ /\ jayne.txt

The program should respond with the email subject, “Will Success
Spoil Rock Hunter?”

.. include:: detail/conclusion.rst

------------------------------

.. [#packagers] 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`_.

   .. _Boost developers' list: http://www.boost.org/more/mailing_lists.htm#main

.. [#lowercase-l] That option is a dash followed by a lowercase “L”
   character, which looks very much like a numeral 1 in some fonts.

.. |build-type-complete| replace:: `` `` 

.. include:: detail/common-footnotes.rst
.. include:: detail/release-variables.rst
.. include:: detail/common-unix.rst
.. include:: detail/links.rst

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.7: http://docutils.sourceforge.net/" />
<title>Boost Getting Started on Windows</title>
<link rel="stylesheet" href="../../rst.css" type="text/css" />
</head>
<body>
<div class="document" id="logo-getting-started-on-windows">
<h1 class="title"><a class="reference external" href="../../index.htm"><img alt="Boost" class="boost-logo" src="../../boost.png" /></a> Getting Started on Windows</h1>

<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<div class="admonition-a-note-to-cygwin-and-mingw-users admonition">
<p class="first admonition-title">A note to <a class="reference external" href="http://www.cygwin.com">Cygwin</a> and <a class="reference external" href="http://mingw.org">MinGW</a> users</p>
<p class="last">If you plan to use your tools from the Windows command prompt,
you're in the right place.  If you plan to build from the <a class="reference external" href="http://www.cygwin.com">Cygwin</a>
bash shell, you're actually running on a POSIX platform and
should follow the instructions for <a class="reference external" href="unix-variants.html">getting started on Unix
variants</a>.  Other command shells, such as <a class="reference external" href="http://mingw.org">MinGW</a>'s MSYS, are
not supported—they may or may not work.</p>
</div>
<div class="contents topic" id="index">
<p class="topic-title first">Index</p>
<ul class="auto-toc simple">
<li><a class="reference internal" href="#get-boost" id="id27">1&nbsp;&nbsp;&nbsp;Get Boost</a></li>
<li><a class="reference internal" href="#the-boost-distribution" id="id28">2&nbsp;&nbsp;&nbsp;The Boost Distribution</a></li>
<li><a class="reference internal" href="#header-only-libraries" id="id29">3&nbsp;&nbsp;&nbsp;Header-Only Libraries</a></li>
<li><a class="reference internal" href="#build-a-simple-program-using-boost" id="id30">4&nbsp;&nbsp;&nbsp;Build a Simple Program Using Boost</a><ul class="auto-toc">
<li><a class="reference internal" href="#build-from-the-visual-studio-ide" id="id31">4.1&nbsp;&nbsp;&nbsp;Build From the Visual Studio IDE</a></li>
<li><a class="reference internal" href="#or-build-from-the-command-prompt" id="id32">4.2&nbsp;&nbsp;&nbsp;Or, Build From the Command Prompt</a></li>
<li><a class="reference internal" href="#errors-and-warnings" id="id33">4.3&nbsp;&nbsp;&nbsp;Errors and Warnings</a></li>
</ul>
</li>
<li><a class="reference internal" href="#prepare-to-use-a-boost-library-binary" id="id34">5&nbsp;&nbsp;&nbsp;Prepare to Use a Boost Library Binary</a><ul class="auto-toc">
<li><a class="reference internal" href="#simplified-build-from-source" id="id35">5.1&nbsp;&nbsp;&nbsp;Simplified Build From Source</a></li>
<li><a class="reference internal" href="#or-build-binaries-from-source" id="id36">5.2&nbsp;&nbsp;&nbsp;Or, Build Binaries From Source</a><ul class="auto-toc">
<li><a class="reference internal" href="#install-boost-build" id="id37">5.2.1&nbsp;&nbsp;&nbsp;Install Boost.Build</a></li>
<li><a class="reference internal" href="#identify-your-toolset" id="id38">5.2.2&nbsp;&nbsp;&nbsp;Identify Your Toolset</a></li>
<li><a class="reference internal" href="#select-a-build-directory" id="id39">5.2.3&nbsp;&nbsp;&nbsp;Select a Build Directory</a></li>
<li><a class="reference internal" href="#invoke-b2" id="id40">5.2.4&nbsp;&nbsp;&nbsp;Invoke <tt class="docutils literal">b2</tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#expected-build-output" id="id41">5.3&nbsp;&nbsp;&nbsp;Expected Build Output</a></li>
<li><a class="reference internal" href="#in-case-of-build-errors" id="id42">5.4&nbsp;&nbsp;&nbsp;In Case of Build Errors</a></li>
</ul>
</li>
<li><a class="reference internal" href="#link-your-program-to-a-boost-library" id="id43">6&nbsp;&nbsp;&nbsp;Link Your Program to a Boost Library</a><ul class="auto-toc">
<li><a class="reference internal" href="#link-from-within-the-visual-studio-ide" id="id44">6.1&nbsp;&nbsp;&nbsp;Link From Within the Visual Studio IDE</a></li>
<li><a class="reference internal" href="#or-link-from-the-command-prompt" id="id45">6.2&nbsp;&nbsp;&nbsp;Or, Link From the Command Prompt</a></li>
<li><a class="reference internal" href="#library-naming" id="id46">6.3&nbsp;&nbsp;&nbsp;Library Naming</a></li>
<li><a class="reference internal" href="#test-your-program" id="id47">6.4&nbsp;&nbsp;&nbsp;Test Your Program</a></li>
</ul>
</li>
<li><a class="reference internal" href="#conclusion-and-further-resources" id="id48">7&nbsp;&nbsp;&nbsp;Conclusion and Further Resources</a></li>
</ul>
</div>
<div class="section" id="get-boost">
<h1><a class="toc-backref" href="#id27">1&nbsp;&nbsp;&nbsp;Get Boost</a></h1>
<p>The most reliable way to get a copy of Boost is to
download <a class="reference external" href="http://www.boost.org/users/history/version_1_55_0.html"><tt class="docutils literal">boost_1_55_0</tt><tt class="docutils literal">.7z</tt></a> or <a class="reference external" href="http://www.boost.org/users/history/version_1_55_0.html"><tt class="docutils literal">boost_1_55_0</tt><tt class="docutils literal">.zip</tt></a> and unpack it to install a complete Boost
distribution.<a class="footnote-reference" href="#zip" id="id2"><sup>1</sup></a></p>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
</div>
<div class="section" id="the-boost-distribution">
<h1><a class="toc-backref" href="#id28">2&nbsp;&nbsp;&nbsp;The Boost Distribution</a></h1>
<p>This is a sketch of the resulting directory structure:</p>
<pre class="literal-block">
<strong>boost_1_55_0</strong><strong>\</strong> .................<em>The “boost root directory”</em>
   <strong>index.htm</strong> .........<em>A copy of www.boost.org starts here</em>
   <strong>boost</strong><strong>\</strong> .........................<em>All Boost Header files</em>
   <strong>lib</strong><strong>\</strong> .....................<em>precompiled library binaries</em>
   <strong>libs</strong><strong>\</strong> ............<em>Tests, .cpp</em>s<em>, docs, etc., by library</em>
     <strong>index.html</strong> ........<em>Library documentation starts here</em>
     <strong>algorithm</strong><strong>\</strong>
     <strong>any</strong><strong>\</strong>
     <strong>array</strong><strong>\</strong>
                     <em>…more libraries…</em>
   <strong>status</strong><strong>\</strong> .........................<em>Boost-wide test suite</em>
   <strong>tools</strong><strong>\</strong> ...........<em>Utilities, e.g. Boost.Build, quickbook, bcp</em>
   <strong>more</strong><strong>\</strong> ..........................<em>Policy documents, etc.</em>
   <strong>doc</strong><strong>\</strong> ...............<em>A subset of all Boost library docs</em>
</pre>
<div class="sidebar">
<p class="first sidebar-title">Header Organization</p>
<p class="pre-wrap">The organization of Boost library headers isn't entirely uniform,
but most libraries follow a few patterns:</p>
<ul class="pre-wrap last">
<li><p class="first">Some older libraries and most very small libraries place all
public headers directly into <tt class="docutils literal">boost</tt><tt class="docutils literal">\</tt>.</p>
</li>
<li><p class="first">Most libraries' public headers live in a subdirectory of
<tt class="docutils literal">boost</tt><tt class="docutils literal">\</tt>, named after the library.  For example, you'll find
the Python library's <tt class="docutils literal">def.hpp</tt> header in</p>
<pre class="literal-block">
<tt class="docutils literal">boost</tt><tt class="docutils literal">\</tt><tt class="docutils literal">python</tt><tt class="docutils literal">\</tt><tt class="docutils literal">def.hpp</tt>.
</pre>
</li>
<li><p class="first">Some libraries have an “aggregate header” in <tt class="docutils literal">boost</tt><tt class="docutils literal">\</tt> that
<tt class="docutils literal">#include</tt>s all of the library's other headers.  For
example, <a class="reference external" href="../../libs/python/doc/building.html">Boost.Python</a>'s aggregate header is</p>
<pre class="literal-block">
<tt class="docutils literal">boost</tt><tt class="docutils literal">\</tt><tt class="docutils literal">python.hpp</tt>.
</pre>
</li>
<li><p class="first">Most libraries place private headers in a subdirectory called
<tt class="docutils literal">detail</tt><tt class="docutils literal">\</tt>, or <tt class="docutils literal">aux_</tt><tt class="docutils literal">\</tt>.  Don't expect to find
anything you can use in these directories.</p>
</li>
</ul>
</div>
<p>It's important to note the following:</p>
<ol class="arabic" id="boost-root-directory">
<li><p class="first">The path to the <strong>boost root directory</strong> (often <tt class="docutils literal"><span class="pre">C:\Program</span> Files\boost\</tt><tt class="docutils literal">boost_1_55_0</tt>) is
sometimes referred to as <tt class="docutils literal">$BOOST_ROOT</tt> in documentation and
mailing lists .</p>
</li>
<li><p class="first">To compile anything in Boost, you need a directory containing
the <tt class="docutils literal">boost</tt><tt class="docutils literal">\</tt> subdirectory in your <tt class="docutils literal">#include</tt> path.  Specific steps for setting up <tt class="docutils literal">#include</tt>
paths in Microsoft Visual Studio follow later in this document;
if you use another IDE, please consult your product's
documentation for instructions.</p>
</li>
<li><p class="first">Since all of Boost's header files have the <tt class="docutils literal">.hpp</tt> extension,
and live in the <tt class="docutils literal">boost</tt><tt class="docutils literal">\</tt> subdirectory of the boost root, your
Boost <tt class="docutils literal">#include</tt> directives will look like:</p>
<pre class="literal-block">
#include &lt;boost/<em>whatever</em>.hpp&gt;
</pre>
<p>or</p>
<pre class="literal-block">
#include &quot;boost/<em>whatever</em>.hpp&quot;
</pre>
<p>depending on your preference regarding the use of angle bracket
includes.  Even Windows users can (and, for
portability reasons, probably should) use forward slashes in
<tt class="docutils literal">#include</tt> directives; your compiler doesn't care.</p>
</li>
<li><p class="first">Don't be distracted by the <tt class="docutils literal">doc</tt><tt class="docutils literal">\</tt> subdirectory; it only
contains a subset of the Boost documentation.  Start with
<tt class="docutils literal">libs</tt><tt class="docutils literal">\</tt><tt class="docutils literal">index.html</tt> if you're looking for the whole enchilada.</p>
</li>
</ol>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
</div>
<div class="section" id="header-only-libraries">
<h1><a class="toc-backref" href="#id29">3&nbsp;&nbsp;&nbsp;Header-Only Libraries</a></h1>
<p>The first thing many people want to know is, “how do I build
Boost?”  The good news is that often, there's nothing to build.</p>
<div class="admonition-nothing-to-build admonition">
<p class="first admonition-title">Nothing to Build?</p>
<p class="last">Most Boost libraries are <strong>header-only</strong>: they consist <em>entirely
of header files</em> containing templates and inline functions, and
require no separately-compiled library binaries or special
treatment when linking.</p>
</div>
<!-- .. _separate: -->
<p>The only Boost libraries that <em>must</em> be built separately are:</p>
<ul class="simple">
<li><a class="reference external" href="../../libs/chrono/index.html">Boost.Chrono</a></li>
<li><a class="reference external" href="../../libs/context/index.html">Boost.Context</a></li>
<li><a class="reference external" href="../../libs/filesystem/index.html">Boost.Filesystem</a></li>
<li><a class="reference external" href="../../libs/graph_parallel/index.html">Boost.GraphParallel</a></li>
<li><a class="reference external" href="../../libs/iostreams/index.html">Boost.IOStreams</a></li>
<li><a class="reference external" href="../../libs/locale/index.html">Boost.Locale</a></li>
<li><a class="reference external" href="../../libs/mpi/index.html">Boost.MPI</a></li>
<li><a class="reference external" href="../../libs/program_options/index.html">Boost.ProgramOptions</a></li>
<li><a class="reference external" href="../../libs/python/doc/building.html">Boost.Python</a> (see the <a class="reference external" href="../../libs/python/doc/building.html">Boost.Python build documentation</a>
before building and installing it)</li>
<li><a class="reference external" href="../../libs/regex/index.html">Boost.Regex</a></li>
<li><a class="reference external" href="../../libs/serialization/index.html">Boost.Serialization</a></li>
<li><a class="reference external" href="../../libs/signals/index.html">Boost.Signals</a></li>
<li><a class="reference external" href="../../libs/system/index.html">Boost.System</a></li>
<li><a class="reference external" href="../../libs/thread/index.html">Boost.Thread</a></li>
<li><a class="reference external" href="../../libs/timer/index.html">Boost.Timer</a></li>
<li><a class="reference external" href="../../libs/wave/index.html">Boost.Wave</a></li>
</ul>
<p>A few libraries have optional separately-compiled binaries:</p>
<ul class="simple">
<li><a class="reference external" href="../../libs/date_time/index.html">Boost.DateTime</a> has a binary component that is only needed if
you're using its <tt class="docutils literal">to_string</tt>/<tt class="docutils literal">from_string</tt> or serialization
features, or if you're targeting Visual C++ 6.x or Borland.</li>
<li><a class="reference external" href="../../libs/graph/index.html">Boost.Graph</a> also has a binary component that is only needed if
you intend to <a class="reference external" href="../../libs/graph/doc/read_graphviz.html">parse GraphViz files</a>.</li>
<li><a class="reference external" href="../../libs/math/index.html">Boost.Math</a> has binary components for the TR1 and C99
cmath functions.</li>
<li><a class="reference external" href="../../libs/random/index.html">Boost.Random</a> has a binary component which is only needed if
you're using <tt class="docutils literal">random_device</tt>.</li>
<li><a class="reference external" href="../../libs/test/index.html">Boost.Test</a> can be used in “header-only” or “separately compiled”
mode, although <strong>separate compilation is recommended for serious
use</strong>.</li>
<li><a class="reference external" href="../../libs/exception/index.html">Boost.Exception</a> provides non-intrusive implementation of
exception_ptr for 32-bit _MSC_VER==1310 and _MSC_VER==1400
which requires a separately-compiled binary. This is enabled by
#define BOOST_ENABLE_NON_INTRUSIVE_EXCEPTION_PTR.</li>
</ul>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
</div>
<div class="section" id="build-a-simple-program-using-boost">
<h1><a class="toc-backref" href="#id30">4&nbsp;&nbsp;&nbsp;Build a Simple Program Using Boost</a></h1>
<p>To keep things simple, let's start by using a header-only library.
The following program reads a sequence of integers from standard
input, uses Boost.Lambda to multiply each number by three, and
writes them to standard output:</p>
<pre class="literal-block">
#include &lt;boost/lambda/lambda.hpp&gt;
#include &lt;iostream&gt;
#include &lt;iterator&gt;
#include &lt;algorithm&gt;

int main()
{
    using namespace boost::lambda;
    typedef std::istream_iterator&lt;int&gt; in;

    std::for_each(
        in(std::cin), in(), std::cout &lt;&lt; (_1 * 3) &lt;&lt; &quot; &quot; );
}
</pre>
<p>Copy the text of this program into a file called <tt class="docutils literal">example.cpp</tt>.</p>
<div class="note" id="command-line-tool">
<span id="command-prompt"></span><p class="first admonition-title">Note</p>
<p class="last">To build the examples in this guide, you can use an
Integrated Development Environment (IDE) like Visual Studio, or
you can issue commands from the <a class="reference internal" href="#command-prompt">command prompt</a>.  Since every
IDE and compiler has different options and Microsoft's are by
far the dominant compilers on Windows, we only give specific
directions here for Visual Studio 2005 and .NET 2003 IDEs and
their respective command prompt compilers (using the command
prompt is a bit simpler).  If you are using another compiler or
IDE, it should be relatively easy to adapt these instructions to
your environment.</p>
</div>
<div class="small sidebar">
<p class="first sidebar-title">Command Prompt Basics</p>
<p>In Windows, a command-line tool is invoked by typing its name,
optionally followed by arguments, into a <em>Command Prompt</em> window
and pressing the Return (or Enter) key.</p>
<p>To open a generic <em>Command Prompt</em>, click the <em>Start</em> menu
button, click <em>Run</em>, type “cmd”, and then click <em>OK</em>.</p>
<p id="current-directory">All commands are executed within the context of a <strong>current
directory</strong> in the filesystem.  To set the current directory,
type:</p>
<pre class="literal-block">
cd <em>path</em>\<em>to</em>\<em>some</em>\<em>directory</em>
</pre>
<p>followed by Return.  For example,</p>
<pre class="literal-block">
cd <tt class="docutils literal"><span class="pre">C:\Program</span> Files\boost\</tt><tt class="docutils literal">boost_1_55_0</tt>
</pre>
<p class="last">Long commands can be continued across several lines by typing a
caret (<tt class="docutils literal">^</tt>) at the end of all but the last line.  Some examples
on this page use that technique to save horizontal space.</p>
</div>
<div class="section" id="build-from-the-visual-studio-ide">
<span id="vs-header-only"></span><h2><a class="toc-backref" href="#id31">4.1&nbsp;&nbsp;&nbsp;Build From the Visual Studio IDE</a></h2>
<ul>
<li><p class="first">From Visual Studio's <em>File</em> menu, select <em>New</em> &gt; <em>Project…</em></p>
</li>
<li><p class="first">In the left-hand pane of the resulting <em>New Project</em> dialog,
select <em>Visual C++</em> &gt; <em>Win32</em>.</p>
</li>
<li><p class="first">In the right-hand pane, select <em>Win32 Console Application</em>
(VS8.0) or <em>Win32 Console Project</em> (VS7.1).</p>
</li>
<li><p class="first">In the <em>name</em> field, enter “example”</p>
</li>
<li><p class="first">Right-click <strong>example</strong> in the <em>Solution Explorer</em> pane and
select <em>Properties</em> from the resulting pop-up menu</p>
</li>
<li><p class="first">In <em>Configuration Properties</em> &gt; <em>C/C++</em> &gt; <em>General</em> &gt; <em>Additional Include
Directories</em>, enter the path to the Boost root directory, for example</p>
<blockquote>
<p><tt class="docutils literal"><span class="pre">C:\Program</span> Files\boost\</tt><tt class="docutils literal">boost_1_55_0</tt></p>
</blockquote>
</li>
<li><p class="first">In <em>Configuration Properties</em> &gt; <em>C/C++</em> &gt; <em>Precompiled Headers</em>, change
<em>Use Precompiled Header (/Yu)</em> to <em>Not Using Precompiled
Headers</em>.<a class="footnote-reference" href="#pch" id="id5"><sup>2</sup></a></p>
</li>
<li><p class="first">Replace the contents of the <tt class="docutils literal">example.cpp</tt> generated by the IDE
with the example code above.</p>
</li>
<li><p class="first">From the <em>Build</em> menu, select <em>Build Solution</em>.</p>
</li>
</ul>
<p>To test your application, hit the F5 key and type the following
into the resulting window, followed by the Return key:</p>
<pre class="literal-block">
1 2 3
</pre>
<p>Then hold down the control key and press &quot;Z&quot;, followed by the
Return key.</p>
<p><a class="reference internal" href="#errors-and-warnings"><em>skip to the next step</em></a></p>
</div>
<div class="section" id="or-build-from-the-command-prompt">
<h2><a class="toc-backref" href="#id32">4.2&nbsp;&nbsp;&nbsp;Or, Build From the Command Prompt</a></h2>
<p>From your computer's <em>Start</em> menu, if you are a Visual
Studio 2005 user, select</p>
<blockquote>
<em>All Programs</em> &gt; <em>Microsoft Visual Studio 2005</em>
&gt; <em>Visual Studio Tools</em> &gt; <em>Visual Studio 2005 Command Prompt</em></blockquote>
<p>or, if you're a Visual Studio .NET 2003 user, select</p>
<blockquote>
<em>All Programs</em> &gt; <em>Microsoft Visual Studio .NET 2003</em>
&gt; <em>Visual Studio .NET Tools</em> &gt; <em>Visual Studio .NET 2003 Command Prompt</em></blockquote>
<p>to bring up a special <a class="reference internal" href="#command-prompt">command prompt</a> window set up for the
Visual Studio compiler.  In that window, set the <a class="reference internal" href="#current-directory">current
directory</a> to a suitable location for creating some temporary
files and type the following command followed by the Return key:</p>
<pre class="literal-block">
cl /EHsc /I <em>path\to\</em><tt class="docutils literal">boost_1_55_0</tt> <em>path</em>\<em>to</em>\example.cpp
</pre>
<p>To test the result, type:</p>
<pre class="literal-block">
echo 1 2 3 | example
</pre>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
</div>
<div class="section" id="errors-and-warnings">
<h2><a class="toc-backref" href="#id33">4.3&nbsp;&nbsp;&nbsp;Errors and Warnings</a></h2>
<p>Don't be alarmed if you see compiler warnings originating in Boost
headers.  We try to eliminate them, but doing so isn't always
practical.<a class="footnote-reference" href="#warnings" id="id7"><sup>4</sup></a> <strong>Errors are another matter</strong>.  If you're
seeing compilation errors at this point in the tutorial, check to
be sure you've copied the <a class="reference internal" href="#build-a-simple-program-using-boost">example program</a> correctly and that you've
correctly identified the <a class="reference internal" href="#boost-root-directory">Boost root directory</a>.</p>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
</div>
</div>
<div class="section" id="prepare-to-use-a-boost-library-binary">
<h1><a class="toc-backref" href="#id34">5&nbsp;&nbsp;&nbsp;Prepare to Use a Boost Library Binary</a></h1>
<p>If you want to use any of the separately-compiled Boost libraries,
you'll need to acquire library binaries.</p>
<div class="section" id="simplified-build-from-source">
<h2><a class="toc-backref" href="#id35">5.1&nbsp;&nbsp;&nbsp;Simplified Build From Source</a></h2>
<p>If you wish to build from source with Visual C++, you can use a
simple build procedure described in this section. Open the command prompt
and change your current directory to the Boost root directory. Then, type
the following commands:</p>
<pre class="literal-block">
bootstrap
.\b2
</pre>
<p>The first command prepares the Boost.Build system for use. The second
command invokes Boost.Build to build the separately-compiled Boost
libraries. Please consult the <a class="reference external" href="http://www.boost.org/boost-build2/doc/html/bbv2/overview/invocation.html">Boost.Build documentation</a> for a list
of allowed options.</p>
</div>
<div class="section" id="or-build-binaries-from-source">
<h2><a class="toc-backref" href="#id36">5.2&nbsp;&nbsp;&nbsp;Or, Build Binaries From Source</a></h2>
<p>If you're using an earlier version of Visual C++, or a compiler
from another vendor, you'll need to use <a class="reference external" href="../../tools/build/index.html">Boost.Build</a> to create your
own binaries.</p>
<div class="admonition-boost-cmake admonition">
<p class="first admonition-title">Boost.CMake</p>
<p class="last">There is also an experimental CMake build for boost, supported and distributed
separately.  See the <a class="reference external" href="https://svn.boost.org/trac/boost/wiki/CMake">Boost.CMake</a> wiki page for more information.</p>
</div>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<div class="section" id="install-boost-build">
<h3><a class="toc-backref" href="#id37">5.2.1&nbsp;&nbsp;&nbsp;Install Boost.Build</a></h3>
<p><a class="reference external" href="../../tools/build/index.html">Boost.Build</a> is a text-based system for developing, testing, and
installing software. First, you'll need to build and
install it. To do this:</p>
<ol class="arabic simple">
<li>Go to the directory <tt class="docutils literal">tools</tt><tt class="docutils literal">\</tt><tt class="docutils literal">build</tt><tt class="docutils literal">\</tt><tt class="docutils literal">v2</tt><tt class="docutils literal">\</tt>.</li>
<li>Run <tt class="docutils literal">bootstrap.bat</tt></li>
<li>Run <tt class="docutils literal">b2 install <span class="pre">--prefix=</span></tt><em>PREFIX</em> where <em>PREFIX</em> is
the directory where you want Boost.Build to be installed</li>
<li>Add <em>PREFIX</em><tt class="docutils literal">\</tt><tt class="docutils literal">bin</tt> to your PATH environment variable.</li>
</ol>
</div>
<div class="section" id="identify-your-toolset">
<span id="toolset-name"></span><span id="toolset"></span><h3><a class="toc-backref" href="#id38">5.2.2&nbsp;&nbsp;&nbsp;Identify Your Toolset</a></h3>
<p>First, find the toolset corresponding to your compiler in the
following table (an up-to-date list is always available <a class="reference external" href="http://www.boost.org/boost-build2/doc/html/bbv2/reference/tools.html">in the
Boost.Build documentation</a>).</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">If you previously chose a toolset for the purposes of
<a class="reference external" href="../../doc/html/bbv2/installation.html">building b2</a>, you should assume it won't work and instead
choose newly from the table below.</p>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="33%" />
<col width="48%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Toolset
Name</th>
<th class="head">Vendor</th>
<th class="head">Notes</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal">acc</tt></td>
<td>Hewlett Packard</td>
<td>Only very recent versions are
known to work well with Boost</td>
</tr>
<tr><td><tt class="docutils literal">borland</tt></td>
<td>Borland</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal">como</tt></td>
<td>Comeau Computing</td>
<td>Using this toolset may
require <a class="reference external" href="../../tools/build/index.html">configuring</a> another
toolset to act as its backend</td>
</tr>
<tr><td><tt class="docutils literal">darwin</tt></td>
<td>Apple Computer</td>
<td>Apple's version of the GCC
toolchain with support for
Darwin and MacOS X features
such as frameworks.</td>
</tr>
<tr><td><tt class="docutils literal">gcc</tt></td>
<td>The Gnu Project</td>
<td>Includes support for Cygwin
and MinGW compilers.</td>
</tr>
<tr><td><tt class="docutils literal">hp_cxx</tt></td>
<td>Hewlett Packard</td>
<td>Targeted at the Tru64
operating system.</td>
</tr>
<tr><td><tt class="docutils literal">intel</tt></td>
<td>Intel</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal">msvc</tt></td>
<td>Microsoft</td>
<td>&nbsp;</td>
</tr>
<tr><td><tt class="docutils literal">sun</tt></td>
<td>Sun</td>
<td>Only very recent versions are
known to work well with
Boost.</td>
</tr>
<tr><td><tt class="docutils literal">vacpp</tt></td>
<td>IBM</td>
<td>The VisualAge C++ compiler.</td>
</tr>
</tbody>
</table>
<p>If you have multiple versions of a particular compiler installed,
you can append the version number to the toolset name, preceded by
a hyphen, e.g. <tt class="docutils literal"><span class="pre">intel-9.0</span></tt> or
<tt class="docutils literal"><span class="pre">borland-5.4.3</span></tt>. <strong>On Windows, append a version
number even if you only have one version installed</strong> (unless you
are using the msvc or gcc toolsets, which have special version
detection code) or <a class="reference internal" href="#auto-linking">auto-linking</a> will fail.</p>
</div>
<div class="section" id="select-a-build-directory">
<span id="id12"></span><span id="build-directory"></span><h3><a class="toc-backref" href="#id39">5.2.3&nbsp;&nbsp;&nbsp;Select a Build Directory</a></h3>
<p><a class="reference external" href="../../tools/build/index.html">Boost.Build</a> will place all intermediate files it generates while
building into the <strong>build directory</strong>.  If your Boost root
directory is writable, this step isn't strictly necessary: by
default Boost.Build will create a <tt class="docutils literal">bin.v2/</tt> subdirectory for that
purpose in your current working directory.</p>
</div>
<div class="section" id="invoke-b2">
<h3><a class="toc-backref" href="#id40">5.2.4&nbsp;&nbsp;&nbsp;Invoke <tt class="docutils literal">b2</tt></a></h3>
<p>Change your current directory to the Boost root directory and
invoke <tt class="docutils literal">b2</tt> as follows:</p>
<pre class="literal-block">
b2 <strong>--build-dir=</strong><a class="reference internal" href="#id12"><em>build-directory</em></a> <strong>toolset=</strong><a class="reference internal" href="#toolset-name"><em>toolset-name</em></a> <strong>--build-type=complete</strong> stage
</pre>
<p>For a complete description of these and other invocation options,
please see the <a class="reference external" href="http://www.boost.org/boost-build2/doc/html/bbv2/advanced/invocation.html">Boost.Build documentation</a>.</p>
<p>For example, your session might look like this:<a class="footnote-reference" href="#continuation" id="id14"><sup>3</sup></a></p>
<pre class="literal-block">
C:\WINDOWS&gt; cd <tt class="docutils literal"><span class="pre">C:\Program</span> Files\boost\</tt><tt class="docutils literal">boost_1_55_0</tt>
<tt class="docutils literal"><span class="pre">C:\Program</span> Files\boost\</tt><tt class="docutils literal">boost_1_55_0</tt>&gt; b2 <strong>^</strong>
More? <strong>--build-dir=</strong>&quot;C:\Documents and Settings\dave\build-boost&quot; <strong>^</strong>
More? <strong>--build-type=complete</strong> <strong>msvc</strong> stage
</pre>
<p>Be sure to read <a class="reference internal" href="#continuation">this note</a> about the appearance of <tt class="docutils literal">^</tt>,
<tt class="docutils literal">More?</tt> and quotation marks (<tt class="docutils literal">&quot;</tt>) in that line.</p>
<p>The option “<strong>--build-type=complete</strong>” causes Boost.Build to build
all supported variants of the libraries.  For instructions on how to
build only specific variants, please ask on the <a class="reference external" href="http://www.boost.org/more/mailing_lists.htm#jamboost">Boost.Build mailing
list</a>.</p>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<p>Building the special <tt class="docutils literal">stage</tt> target places Boost
library binaries in the <tt class="docutils literal">stage</tt><tt class="docutils literal">\</tt><tt class="docutils literal">lib</tt><tt class="docutils literal">\</tt> subdirectory of
the Boost tree.  To use a different directory pass the
<tt class="docutils literal"><span class="pre">--stagedir=</span></tt><em>directory</em> option to <tt class="docutils literal">b2</tt>.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last"><tt class="docutils literal">b2</tt> is case-sensitive; it is important that all the
parts shown in <strong>bold</strong> type above be entirely lower-case.</p>
</div>
<p>For a description of other options you can pass when invoking
<tt class="docutils literal">b2</tt>, type:</p>
<pre class="literal-block">
b2 --help
</pre>
<p>In particular, to limit the amount of time spent building, you may
be interested in:</p>
<ul class="simple">
<li>reviewing the list of library names with <tt class="docutils literal"><span class="pre">--show-libraries</span></tt></li>
<li>limiting which libraries get built with the <tt class="docutils literal"><span class="pre">--with-</span></tt><em>library-name</em> or <tt class="docutils literal"><span class="pre">--without-</span></tt><em>library-name</em> options</li>
<li>choosing a specific build variant by adding <tt class="docutils literal">release</tt> or
<tt class="docutils literal">debug</tt> to the command line.</li>
</ul>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Boost.Build can produce a great deal of output, which can
make it easy to miss problems.  If you want to make sure
everything is went well, you might redirect the output into a
file by appending “<tt class="docutils literal">&gt;build.log <span class="pre">2&gt;&amp;1</span></tt>” to your command line.</p>
</div>
</div>
</div>
<div class="section" id="expected-build-output">
<h2><a class="toc-backref" href="#id41">5.3&nbsp;&nbsp;&nbsp;Expected Build Output</a></h2>
<p>During the process of building Boost libraries, you can expect to
see some messages printed on the console.  These may include</p>
<ul>
<li><p class="first">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.</p>
</li>
<li><p class="first">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.</p>
</li>
<li><p class="first">Build action messages describing what the tool is doing, which
look something like:</p>
<pre class="literal-block">
<em>toolset-name</em>.c++ <em>long</em>/<em>path</em>/<em>to</em>/<em>file</em>/<em>being</em>/<em>built</em>
</pre>
</li>
<li><p class="first">Compiler warnings.</p>
</li>
</ul>
</div>
<div class="section" id="in-case-of-build-errors">
<h2><a class="toc-backref" href="#id42">5.4&nbsp;&nbsp;&nbsp;In Case of Build Errors</a></h2>
<p>The only error messages you see when building Boost—if any—should
be related to the IOStreams library's support of zip and bzip2
formats as described <a class="reference external" href="../../libs/iostreams/doc/installation.html">here</a>.  Install the relevant development
packages for libz and libbz2 if you need those features.  Other
errors when building Boost libraries are cause for concern.</p>
<p>If it seems like the build system can't find your compiler and/or
linker, consider setting up a <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file as described
<a class="reference external" href="http://www.boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html">here</a>.  If that isn't your problem or the <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file
doesn't work for you, please address questions about configuring Boost
for your compiler to the <a class="reference external" href="http://www.boost.org/more/mailing_lists.htm#jamboost">Boost.Build mailing list</a>.</p>
<span class="target" id="auto-linking"></span><!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
</div>
</div>
<div class="section" id="link-your-program-to-a-boost-library">
<h1><a class="toc-backref" href="#id43">6&nbsp;&nbsp;&nbsp;Link Your Program to a Boost Library</a></h1>
<p>To demonstrate linking with a Boost binary library, we'll use the
following simple program that extracts the subject lines from
emails.  It uses the <a class="reference external" href="../../libs/regex/index.html">Boost.Regex</a> library, which has a
separately-compiled binary component.</p>
<pre class="literal-block">
#include &lt;boost/regex.hpp&gt;
#include &lt;iostream&gt;
#include &lt;string&gt;

int main()
{
    std::string line;
    boost::regex pat( &quot;^Subject: (Re: |Aw: )*(.*)&quot; );

    while (std::cin)
    {
        std::getline(std::cin, line);
        boost::smatch matches;
        if (boost::regex_match(line, matches, pat))
            std::cout &lt;&lt; matches[2] &lt;&lt; std::endl;
    }
}
</pre>
<p>There are two main challenges associated with linking:</p>
<ol class="arabic simple">
<li>Tool configuration, e.g. choosing command-line options or IDE
build settings.</li>
<li>Identifying the library binary, among all the build variants,
whose compile configuration is compatible with the rest of your
project.</li>
</ol>
<div class="admonition-auto-linking admonition">
<p class="first admonition-title">Auto-Linking</p>
<p>Most Windows compilers and linkers have so-called “auto-linking
support,” which eliminates the second challenge.  Special code in
Boost header files detects your compiler options and uses that
information to encode the name of the correct library into your
object files; the linker selects the library with that name from
the directories you've told it to search.</p>
<p class="last">The GCC toolchains (Cygwin and MinGW) are notable exceptions;
GCC users should refer to the <a class="reference external" href="unix-variants.html#link-your-program-to-a-boost-library">linking instructions for Unix
variant OSes</a> for the appropriate command-line options to use.</p>
</div>
<div class="section" id="link-from-within-the-visual-studio-ide">
<h2><a class="toc-backref" href="#id44">6.1&nbsp;&nbsp;&nbsp;Link From Within the Visual Studio IDE</a></h2>
<p>Starting with the <a class="reference internal" href="#vs-header-only">header-only example project</a> we created
earlier:</p>
<ol class="arabic simple">
<li>Right-click <strong>example</strong> in the <em>Solution Explorer</em> pane and
select <em>Properties</em> from the resulting pop-up menu</li>
<li>In <em>Configuration Properties</em> &gt; <em>Linker</em> &gt; <em>Additional Library
Directories</em>, enter the path to the Boost binaries,
e.g. <tt class="docutils literal"><span class="pre">C:\Program</span> Files\boost\</tt><tt class="docutils literal">boost_1_55_0</tt><tt class="docutils literal">\lib\</tt>.</li>
<li>From the <em>Build</em> menu, select <em>Build Solution</em>.</li>
</ol>
<p><a class="reference internal" href="#test-your-program"><em>skip to the next step</em></a></p>
</div>
<div class="section" id="or-link-from-the-command-prompt">
<h2><a class="toc-backref" href="#id45">6.2&nbsp;&nbsp;&nbsp;Or, Link From the Command Prompt</a></h2>
<p>For example, we can compile and link the above program from the
Visual C++ command-line by simply adding the <strong>bold</strong> text below to
the command line we used earlier, assuming your Boost binaries are
in <tt class="docutils literal"><span class="pre">C:\Program</span> Files\boost\</tt><tt class="docutils literal">boost_1_55_0</tt><tt class="docutils literal">\lib</tt>:</p>
<pre class="literal-block">
cl /EHsc /I <em>path\to\</em><tt class="docutils literal">boost_1_55_0</tt> example.cpp   <strong>^</strong>
     <strong>/link /LIBPATH:</strong><strong>C:\Program Files\boost\</strong><strong>boost_1_55_0</strong><strong>\lib</strong>
</pre>
</div>
<div class="section" id="library-naming">
<h2><a class="toc-backref" href="#id46">6.3&nbsp;&nbsp;&nbsp;Library Naming</a></h2>
<div class="note">
<p class="first admonition-title">Note</p>
<p>If, like Visual C++, your compiler supports auto-linking,
you can probably <a class="reference internal" href="#test-your-program"><em>skip to the next step</em></a>.</p>
<blockquote class="last">
</blockquote>
</div>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<p>In order to choose the right binary for your build configuration
you need to know how Boost binaries are named.  Each library
filename is composed of a common sequence of elements that describe
how it was built.  For example,
<tt class="docutils literal"><span class="pre">libboost_regex-vc71-mt-d-1_34.lib</span></tt> can be broken down into the
following elements:</p>
<dl class="docutils">
<dt><tt class="docutils literal">lib</tt></dt>
<dd><em>Prefix</em>: except on Microsoft Windows, every Boost library
name begins with this string.  On Windows, only ordinary static
libraries use the <tt class="docutils literal">lib</tt> prefix; import libraries and DLLs do
not.<a class="footnote-reference" href="#distinct" id="id22"><sup>5</sup></a></dd>
<dt><tt class="docutils literal">boost_regex</tt></dt>
<dd><em>Library name</em>: all boost library filenames begin with <tt class="docutils literal">boost_</tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">-vc71</span></tt></dt>
<dd><em>Toolset tag</em>: identifies the <a class="reference internal" href="#toolset">toolset</a> and version used to build
the binary.</dd>
<dt><tt class="docutils literal"><span class="pre">-mt</span></tt></dt>
<dd><em>Threading tag</em>: indicates that the library was
built with multithreading support enabled.  Libraries built
without multithreading support can be identified by the absence
of <tt class="docutils literal"><span class="pre">-mt</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">-d</span></tt></dt>
<dd><p class="first"><em>ABI tag</em>: encodes details that affect the library's
interoperability with other compiled code.  For each such
feature, a single letter is added to the tag:</p>
<blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="5%" />
<col width="75%" />
<col width="20%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Key</th>
<th class="head">Use this library when:</th>
<th class="head">Boost.Build option</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal">s</tt></td>
<td>linking statically to the C++ standard library and compiler runtime support
libraries.</td>
<td>runtime-link=static</td>
</tr>
<tr><td><tt class="docutils literal">g</tt></td>
<td>using debug versions of the standard and runtime support libraries.</td>
<td>runtime-debugging=on</td>
</tr>
<tr><td><tt class="docutils literal">y</tt></td>
<td>using a special <a class="reference external" href="../../libs/python/doc/building.html#python-debugging-builds">debug build of Python</a>.</td>
<td>python-debugging=on</td>
</tr>
<tr><td><tt class="docutils literal">d</tt></td>
<td>building a debug version of your code.<a class="footnote-reference" href="#debug-abi" id="id23"><sup>6</sup></a></td>
<td>variant=debug</td>
</tr>
<tr><td><tt class="docutils literal">p</tt></td>
<td>using the STLPort standard library rather than the default one supplied with
your compiler.</td>
<td>stdlib=stlport</td>
</tr>
</tbody>
</table>
</blockquote>
<p class="last">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: <tt class="docutils literal"><span class="pre">-sgdpn</span></tt>.  If none of the above apply, the
ABI tag is ommitted.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">-1_34</span></tt></dt>
<dd><em>Version tag</em>: the full Boost release number, with periods
replaced by underscores. For example, version 1.31.1 would be
tagged as &quot;-1_31_1&quot;.</dd>
<dt><tt class="docutils literal">.lib</tt></dt>
<dd><em>Extension</em>: determined according to the operating system's usual
convention.  On most unix-style platforms the extensions are
<tt class="docutils literal">.a</tt> and <tt class="docutils literal">.so</tt> for static libraries (archives) and shared
libraries, respectively.  On Windows, <tt class="docutils literal">.dll</tt> indicates a shared
library and <tt class="docutils literal">.lib</tt> indicates a
static or import library.  Where supported by toolsets on unix
variants, a full version extension is added (e.g. &quot;.so.1.34&quot;) and
a symbolic link to the library file, named without the trailing
version number, will also be created.</dd>
</dl>
<!-- .. _Boost.Build toolset names: toolset-name_ -->
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
</div>
<div class="section" id="test-your-program">
<h2><a class="toc-backref" href="#id47">6.4&nbsp;&nbsp;&nbsp;Test Your Program</a></h2>
<p>To test our subject extraction, we'll filter the following text
file.  Copy it out of your browser and save it as <tt class="docutils literal">jayne.txt</tt>:</p>
<pre class="literal-block">
To: George Shmidlap
From: Rita Marlowe
Subject: Will Success Spoil Rock Hunter?
---
See subject.
</pre>
<p>Now, in a <a class="reference internal" href="#command-prompt">command prompt</a> window, type:</p>
<pre class="literal-block">
<em>path</em>\<em>to</em>\<em>compiled</em>\example &lt; <em>path</em>\<em>to</em>\jayne.txt
</pre>
<p>The program should respond with the email subject, “Will Success
Spoil Rock Hunter?”</p>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
</div>
</div>
<div class="section" id="conclusion-and-further-resources">
<h1><a class="toc-backref" href="#id48">7&nbsp;&nbsp;&nbsp;Conclusion and Further Resources</a></h1>
<p>This concludes your introduction to Boost and to integrating it
with your programs.  As you start using Boost in earnest, there are
surely a few additional points you'll wish we had covered.  One day
we may have a “Book 2 in the Getting Started series” that addresses
them.  Until then, we suggest you pursue the following resources.
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 <a class="reference external" href="http://www.boost.org/more/mailing_lists.htm#users">Boost Users'
mailing list</a>.</p>
<ul class="simple">
<li><a class="reference external" href="../../tools/build/v2/index.html">Boost.Build reference manual</a></li>
<li><a class="reference external" href="http://www.boost.org/more/mailing_lists.htm#users">Boost Users' mailing list</a></li>
<li><a class="reference external" href="http://www.boost.org/more/mailing_lists.htm#jamboost">Boost.Build mailing list</a></li>
<li><a class="reference external" href="../../libs/index.html">Index of all Boost library documentation</a></li>
</ul>
<div class="admonition-onward admonition">
<p class="first admonition-title">Onward</p>
<blockquote class="epigraph last">
<p>Good luck, and have fun!</p>
<p class="attribution">&mdash;the Boost Developers</p>
</blockquote>
</div>
<hr class="docutils" />
<table class="docutils footnote" frame="void" id="zip" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[1]</a></td><td>We recommend
downloading <a class="reference external" href="http://www.boost.org/users/history/version_1_55_0.html"><tt class="docutils literal">boost_1_55_0</tt><tt class="docutils literal">.7z</tt></a> and using <a class="reference external" href="http://www.7-zip.org">7-Zip</a> to decompress
it.  We no longer recommend .zip files for Boost because they are twice
as large as the equivalent .7z files.  We don't recommend using Windows'
built-in decompression as it can be painfully slow for large archives.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="pch" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id5">[2]</a></td><td>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.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="continuation" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id14">[3]</a></td><td><p class="first">In this example, the caret character <tt class="docutils literal">^</tt> is a
way of continuing the command on multiple lines, and must be the
<strong>final character</strong> used on the line to be continued (i.e. do
not follow it with spaces).  The command prompt responds with
<tt class="docutils literal">More?</tt> to prompt for more input.  Feel free to omit the
carets and subsequent newlines; we used them so the example
would fit on a page of reasonable width.</p>
<p>The command prompt treats each bit of whitespace in the command
as an argument separator.  That means quotation marks (<tt class="docutils literal">&quot;</tt>)
are required to keep text together whenever a single
command-line argument contains spaces, as in</p>
<pre class="literal-block">
--build-dir=<span class="raw-html"><strong style="background-color:#B4FFB4">"</strong></span>C:\Documents<span class="raw-html"><strong style="color:#B4B4B4; background-color:#B4FFB4">_</strong></span>and<span class="raw-html"><strong style="color:#B4B4B4; background-color:#B4FFB4">_</strong></span>Settings\dave\build-boost<span class="raw-html"><strong style="background-color:#B4FFB4">"</strong></span>
</pre>
<p>Also, for example, you can't add spaces around the <tt class="docutils literal">=</tt> sign as in</p>
<pre class="last literal-block">
--build-dir<span class="raw-html"><strong style="color:#B4B4B4; background-color:#FFB4B4">_</strong></span>=<span class="raw-html"><strong style="color:#B4B4B4; background-color:#FFB4B4">_</strong></span>&quot;C:\Documents and Settings\dave\build-boost&quot;
</pre>
</td></tr>
</tbody>
</table>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<table class="docutils footnote" frame="void" id="warnings" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id7">[4]</a></td><td>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.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="distinct" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id22">[5]</a></td><td>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.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="debug-abi" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id23">[6]</a></td><td>These libraries were compiled without optimization
or inlining, with full debug symbols enabled, and without
<tt class="docutils literal">NDEBUG</tt> <tt class="docutils literal">#define</tt>d.  Although it's true that sometimes
these choices don't affect binary compatibility with other
compiled code, you can't count on that with Boost libraries.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="native" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[7]</td><td>This feature of STLPort is deprecated because it's
impossible to make it work transparently to the user; we don't
recommend it.</td></tr>
</tbody>
</table>
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<!-- This file contains all the definitions that need to be updated -->
<!-- for each new release of Boost. -->
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
</div>
</div>
</body>
</html>

.. Copyright David Abrahams 2006. Distributed under the Boost
.. Software License, Version 1.0. (See accompanying
.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

=======================================
 |(logo)|__ Getting Started on Windows
=======================================

.. |(logo)| image:: ../../boost.png
   :alt: Boost
   :class: boost-logo

.. role:: raw-html(raw)
   :format: html

__ ../../index.htm

.. section-numbering::

.. Admonition:: A note to Cygwin_ and MinGW_ users

  If you plan to use your tools from the Windows command prompt,
  you're in the right place.  If you plan to build from the Cygwin_
  bash shell, you're actually running on a POSIX platform and
  should follow the instructions for `getting started on Unix
  variants`_.  Other command shells, such as MinGW_\ 's MSYS, are
  not supported—they may or may not work.

  .. _`Getting Started on Unix Variants`: unix-variants.html
  .. _Cygwin: http://www.cygwin.com
  .. _MinGW: http://mingw.org

.. Contents:: Index

Get Boost
=========

The most reliable way to get a copy of Boost is to
download |boost.7z|_ or |boost_zip|_ and unpack it to install a complete Boost
distribution. [#zip]_

.. |boost.7z| replace:: |boost_ver|\ ``.7z``

.. _`boost.7z`: `sf-download`_

.. |boost_zip| replace:: |boost_ver|\ ``.zip``

.. _`boost_zip`: `sf-download`_

.. include:: detail/distro.rst

.. include:: detail/header-only.rst

.. include:: detail/build-simple-head.rst

.. _`command prompt`:
.. _`command-line tool`:

.. Note:: To build the examples in this guide, you can use an
   Integrated Development Environment (IDE) like Visual Studio, or
   you can issue commands from the `command prompt`_.  Since every
   IDE and compiler has different options and Microsoft's are by
   far the dominant compilers on Windows, we only give specific
   directions here for Visual Studio 2005 and .NET 2003 IDEs and
   their respective command prompt compilers (using the command
   prompt is a bit simpler).  If you are using another compiler or
   IDE, it should be relatively easy to adapt these instructions to
   your environment.

.. sidebar:: Command Prompt Basics
   :class: small

   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 a generic *Command Prompt*, click the *Start* menu
   button, click *Run*, type “cmd”, and then click *OK*.

   .. _current directory:

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

   .. parsed-literal::

      cd *path*\ \\\ *to*\ \\\ *some*\ \\\ *directory*

   followed by Return.  For example,

   .. parsed-literal::

      cd |default-root|

   Long commands can be continued across several lines by typing a
   caret (``^``) at the end of all but the last line.  Some examples
   on this page use that technique to save horizontal space.

.. _vs-header-only:

Build From 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, for example

    |default-root|

* In *Configuration Properties* > *C/C++* > *Precompiled Headers*, change
  *Use Precompiled Header (/Yu)* to *Not Using Precompiled
  Headers*. [#pch]_
* 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.

|next|__

__ `Errors and Warnings`_

Or, Build From the 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, set the `current
directory`_ to a suitable location for creating some temporary
files and type the following command followed by the Return key:

.. parsed-literal::

  cl /EHsc /I |root| *path*\ \\\ *to*\ \\example.cpp

To test the result, type:

.. parsed-literal::

  echo 1 2 3 | example

.. include:: detail/errors-and-warnings.rst

.. include:: detail/binary-head.rst

Simplified Build From Source
----------------------------

If you wish to build from source with Visual C++, you can use a 
simple build procedure described in this section. Open the command prompt
and change your current directory to the Boost root directory. Then, type
the following commands::

  bootstrap
  .\b2

The first command prepares the Boost.Build system for use. The second
command invokes Boost.Build to build the separately-compiled Boost
libraries. Please consult the `Boost.Build documentation`__ for a list
of allowed options.

__ http://www.boost.org/boost-build2/doc/html/bbv2/overview/invocation.html

Or, Build Binaries From Source
------------------------------

If you're using an earlier version of Visual C++, or a compiler
from another vendor, you'll need to use Boost.Build_ to create your
own binaries.

.. Admonition:: Boost.CMake

  There is also an experimental CMake build for boost, supported and distributed
  separately.  See the `Boost.CMake`_ wiki page for more information.

  .. _`Boost.CMake`:
       https://svn.boost.org/trac/boost/wiki/CMake

.. include:: detail/build-from-source-head.rst

For example, your session might look like this: [#continuation]_

.. parsed-literal::

   C:\\WINDOWS> cd |default-root|
   |default-root|> b2 **^**
   More? **--build-dir=**\ "C:\\Documents and Settings\\dave\\build-boost" **^**
   More? **--build-type=complete** **msvc** stage

Be sure to read `this note`__ about the appearance of ``^``,
``More?`` and quotation marks (``"``) in that line.

The option “\ **--build-type=complete**\ ” causes Boost.Build to build
all supported variants of the libraries.  For instructions on how to
build only specific variants, please ask on the `Boost.Build mailing
list`_.

__ continuation_

.. include:: detail/build-from-source-tail.rst

.. _auto-linking:

.. include:: detail/link-head.rst

.. Admonition:: Auto-Linking

   Most Windows compilers and linkers have so-called “auto-linking
   support,” which eliminates the second challenge.  Special code in
   Boost header files detects your compiler options and uses that
   information to encode the name of the correct library into your
   object files; the linker selects the library with that name from
   the directories you've told it to search.

   The GCC toolchains (Cygwin and MinGW) are notable exceptions;
   GCC users should refer to the `linking instructions for Unix
   variant OSes`__ for the appropriate command-line options to use.

__ unix-variants.html#link-your-program-to-a-boost-library


Link From Within the Visual Studio IDE
--------------------------------------

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

__ vs-header-only_

1. Right-click **example** in the *Solution Explorer* pane and
   select *Properties* from the resulting pop-up menu
2. In *Configuration Properties* > *Linker* > *Additional Library
   Directories*, enter the path to the Boost binaries,
   e.g. |default-root|\ ``\lib\``.
3. From the *Build* menu, select *Build Solution*.

|next|__

__ `Test Your Program`_

Or, Link From the 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 |default-root|\ ``\lib``:

.. parsed-literal::

   cl /EHsc /I |root| example.cpp   **^**
        **/link /LIBPATH:**\ |default-root-bold|\ **\\lib**

Library Naming
--------------

.. Note:: If, like Visual C++, your compiler supports auto-linking,
   you can probably |next|__.

     __ `Test Your Program`_

.. include:: detail/library-naming.rst

.. include:: detail/test-head.rst

Now, in a `command prompt`_ window, type:

.. parsed-literal::

   *path*\ \\\ *to*\ \\\ *compiled*\ \\example < *path*\ \\\ *to*\ \\\ jayne.txt

The program should respond with the email subject, “Will Success
Spoil Rock Hunter?”

.. include:: detail/conclusion.rst

------------------------------

.. [#zip] We recommend
   downloading |boost.7z|_ and using 7-Zip_ to decompress
   it.  We no longer recommend .zip files for Boost because they are twice
   as large as the equivalent .7z files.  We don't recommend using Windows'
   built-in decompression as it can be painfully slow for large archives.
   
.. _7-Zip: http://www.7-zip.org  

.. [#pch] 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.

.. [#continuation] In this example, the caret character ``^`` is a
   way of continuing the command on multiple lines, and must be the
   **final character** used on the line to be continued (i.e. do
   not follow it with spaces).  The command prompt responds with
   ``More?`` to prompt for more input.  Feel free to omit the
   carets and subsequent newlines; we used them so the example
   would fit on a page of reasonable width.  

   The command prompt treats each bit of whitespace in the command
   as an argument separator.  That means quotation marks (``"``)
   are required to keep text together whenever a single
   command-line argument contains spaces, as in

   .. parsed-literal::

     --build-dir=\ :raw-html:`<strong style="background-color:#B4FFB4">"</strong>`\ C:\\Documents\ :raw-html:`<strong style="color:#B4B4B4; background-color:#B4FFB4">_</strong>`\ and\ :raw-html:`<strong style="color:#B4B4B4; background-color:#B4FFB4">_</strong>`\ Settings\\dave\\build-boost\ \ :raw-html:`<strong style="background-color:#B4FFB4">"</strong>`

   Also, for example, you can't add spaces around the ``=`` sign as in

   .. parsed-literal::

     --build-dir\ :raw-html:`<strong style="color:#B4B4B4; background-color:#FFB4B4">_</strong>`\ =\ :raw-html:`<strong style="color:#B4B4B4; background-color:#FFB4B4">_</strong>`\ "C:\\Documents and Settings\\dave\\build-boost"

.. |boost.zip| replace:: |boost_ver|\ ``.zip``

.. _`boost.zip`: `sf-download`_

.. |build-type-complete| replace:: **--build-type=complete**

.. include:: detail/common-footnotes.rst
.. include:: detail/release-variables.rst
.. include:: detail/common-windows.rst
.. include:: detail/links.rst

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
   <head>
      <title>Boost More Information</title>
      <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
      <meta name="ProgId" content="FrontPage.Editor.Document">
      <meta name="GENERATOR" content="Microsoft FrontPage 5.0">
      <link rel="stylesheet" href="../doc/src/boostbook.css" type="text/css" />
   </head>
   <body bgcolor="#ffffff" text="#000000">

  <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
    <tr>
      <td width="277">
        <a href="../index.html">
        <img src="../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" border="0"></a></td>
      <td width="337" align="middle">
        <font size="7">More Info</font>
      </td>
    </tr>
  </table>

  <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" height="26" width="681">
    <tr>
      <td height="16" width="671"><a href="../more/getting_started/index.html">Getting Started</a>&nbsp;&nbsp;<font color="#FFFFFF">&nbsp;
      </font>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="../libs/libraries.htm">
      Libraries</a>&nbsp;&nbsp;<font color="#FFFFFF">&nbsp;
      </font>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="../tools/index.html">Tools&nbsp;</a>&nbsp;<font color="#FFFFFF">&nbsp;
      </font>&nbsp;&nbsp;&nbsp;&nbsp; <a href="http://www.boost.org">Web Site</a>&nbsp;&nbsp;<font color="#FFFFFF">&nbsp;
      </font>&nbsp;&nbsp;&nbsp;&nbsp; <a href="http://www.boost.org/users/news/">News</a>&nbsp;&nbsp;<font color="#FFFFFF">&nbsp;
      </font>&nbsp;&nbsp;&nbsp; <a href="http://www.boost.org/community/">Community</a>&nbsp;&nbsp;<font color="#FFFFFF">&nbsp;
      </font>&nbsp;&nbsp;&nbsp;&nbsp;
      <a href="http://www.boost.org/users/faq.html">FAQ</a>&nbsp;</td>
    </tr>
  </table>

      <h2>Boost Policies</h2>
      <blockquote>
         <p><b><a href="http://www.boost.org/community/policy.html">Mailing List Discussion Policy.</a></b>&nbsp; 
            What's acceptable and what isn't.</p>
         <p><b><a href="http://www.boost.org/development/requirements.html">Library Requirements and Guidelines</a></b>.&nbsp; 
            Basic standards for those preparing a submission.</p>
         <P><STRONG>
         <a href="http://www.boost.org/development/separate_compilation.html">Guidelines for Libraries with Separate 
                  Source</a></STRONG>.&nbsp; Basic tutorial for libraries that require the 
            building of a separate link library.</P>
         <p><strong><a href="writingdoc/index.html">Writing Documentation for Boost</a>.&nbsp; </strong>&nbsp;Basic guidelines for writing documentation and templates for quickly generating 
            documentation that follows the guidelines.</p>
         <p><b><a href="http://www.boost.org/development/test.html">Test Policies and Protocols</a></b>.&nbsp; 
         What tests must be in place for a Boost library.</p>
         <p><b><a href="http://www.boost.org/development/submissions.html">Library Submission Process</a></b>.&nbsp; 
            How to submit a library to Boost.</p>
         <p><b><a href="http://www.boost.org/community/reviews.html">Library Formal Review Process</a></b>. 
            Including how to submit a review comment.</p>
         <p><b><a href="http://www.boost.org/development/header.html">Header Policy</a></b>.&nbsp; Headers are where a 
            library contacts its users, so programming practices are particularly 
            important.</p>
         <p><b><a href="http://www.boost.org/development/reuse.html">Library Reuse</a></b>.&nbsp; Should Boost 
            libraries use other boost libraries?&nbsp; What about the C++ Standard 
            Library?&nbsp; It's another trade-off.</p>
         <p><b><a href="http://www.boost.org/community/moderators.html">Moderators</a></b>.&nbsp; Who they are and what 
            they do.</p>
      </blockquote>
      <h2>Boost Whatever</h2>
      <blockquote>
         <p><b><a href="http://www.boost.org/users/license.html">License Information</a> </b>&nbsp;Information 
            about the Boost Software License.</p>
         <p><b><a href="http://www.boost.org/users/bibliography.html">Bibliography</a> </b>&nbsp;Print and online 
            publications relating to Boost and Boost libraries.</p>
         <p><b><a href="http://www.boost.org/users/uses.html">Who's Using Boost?</a> </b>&nbsp;
         Products and organizations that are using Boost.</p>
         <p><b><a href="http://www.boost.org/community/review_schedule.html">Formal Review Schedule</a></b>&nbsp; 
            Future, current, and recently past Formal Reviews.</p>
         <p><b><a href="http://www.boost.org/users/proposal.pdf">Proposal for a C++ Library Repository Web Site</a></b>&nbsp; 
            The original 1998 proposal that launched Boost.</p>
         <p><b><a href="http://www.boost.org/support/bugs.html">How to report bugs</a></b>&nbsp; Ways to report Boost 
            bugs.</p>
         <p><b><a href="http://www.boost.org/community/requests.html">How to request features</a></b> Ways 
            to request new library features.</p>
      </blockquote>
      <h2>Articles and Papers</h2>
      <blockquote>
         <p><strong>
         <a href="http://www.boost.org/development/int_const_guidelines.html">Coding Guidelines for Integral Constant 
                  Expressions</a></strong> describes how to work through the maze of 
            compiler related bugs surrounding this tricky topic.</p>
      </blockquote>
      <hr>
      <p>
         Revised 
         <!--webbot bot="Timestamp" s-type="EDITED"
s-format="%d %B, %Y" startspan -->13 March, 2008<!--webbot bot="Timestamp" endspan i-checksum="28995" --></p>
      <p>
         � Copyright Beman Dawes 2003.</p>
      <p>
         Distributed under the Boost Software License, Version 1.0. (See
         accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
         at <a href=
         "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
   </body>
</html>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
  <meta http-equiv="Content-Language" content="en-us">
  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  <link rel="stylesheet" type="text/css" href="../../boost.css">

  <title>Writing Documentation for Boost - HTML Design</title>
</head>

<body link="#0000FF" vlink="#800080">
  <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
  "header">
    <tr>
      <td valign="top" width="300">
        <h3><a href="index.html"><img height="86" width="277" alt="C++ Boost"
        src="../../boost.png" border="0"></a></h3>
      </td>

      <td valign="top">
        <h1 align="center">Writing Documentation for Boost</h1>

        <h2 align="center">HTML Design</h2>
      </td>
    </tr>
  </table>
  <hr>

  <dl class="page-index">
    <dt><a href="#introduction">Introduction</a></dt>

    <dt><a href="#common-pages">Common Pages Included in HTML
    Documentation</a></dt>

    <dd>
      <dl class="page-index">
        <dt><a href="#index-page">Index</a></dt>

        <dt><a href="#overview-page">Overview</a></dt>

        <dt><a href="#definitions-page">Definitions</a></dt>

        <dt><a href="#rationale-page">Rationale</a></dt>

        <dt><a href="#configuration-page">Configuration Information</a></dt>

        <dt><a href="#faq-page">Frequently Asked Questions</a></dt>

        <dt><a href="#bibliography-page">Bibliography</a></dt>

        <dt><a href="#acknowledgements-page">Acknowledgment</a></dt>

        <dt><a href="#header-page">Header Reference</a></dt>
      </dl>
    </dd>

    <dt><a href="#layout">Layout</a></dt>

    <dd>
      <dl class="page-index">
        <dt><a href="#page-banner">Page Banner</a></dt>

        <dt><a href="#page-index">Page Index</a></dt>

        <dt><a href="#content">Documentation Content</a></dt>

        <dd>
          <dl class="page-index">
            <dt><a href="#doc-footnotes">Footnotes</a></dt>
          </dl>
        </dd>

        <dt><a href="#revision-info">Revision Information</a></dt>

        <dt><a href="#copyright">Copyright Information</a></dt>
      </dl>
    </dd>

    <dt><a href="#format">Format</a></dt>

    <dd>
      <dl class="page-index">
        <dt><a href="#style-sheets">Cascading Style Sheets</a></dt>

        <dd>
          <dl class="page-index">
            <dt><a href="#boost-style-sheet">Boost Style Sheet</a></dt>
          </dl>
        </dd>
      </dl>
    </dd>

    <dt><a href="#templates">Templates</a></dt>

    <dd>
      <dl class="page-index">
        <dt><a href="#index-template">Index Page Template</a></dt>

        <dt><a href="#overview-template">Overview Page Template</a></dt>

        <dt><a href="#definitions-template">Definitions Page
        Template</a></dt>

        <dt><a href="#rationale-template">Rationale Page Template</a></dt>

        <dt><a href="#configuration-template">Configuration Page
        Template</a></dt>

        <dt><a href="#faq-template">FAQ (Frequently Asked Questions) Page
        Template</a></dt>

        <dt><a href="#bibliography-template">Bibliography Page
        Template</a></dt>

        <dt><a href="#acknowledgements-template">Acknowledgments Page
        Template</a></dt>

        <dt><a href="#header-template">Header Page Template</a></dt>
      </dl>
    </dd>
  </dl>

  <h2><a name="introduction" id="introduction"></a>Introduction</h2>

  <p>Boost places no requirements on the design of HTML documentation for
  library submitters. If you are submitting a library for which documentation
  already exists in either HTML or in a form easily converted to HTML then
  there is no need for you to read this document. However, if you have not
  yet written the documentation, or if you expect to have to translate
  documentation written in a format not easily convertible to HTML then this
  document can give you a lot of information on how to go about writing
  documentation in HTML.</p>

  <p>In several places this document assumes you're writing the documentation
  to conform to the structure described in the <a href=
  "structure.html">Documentation Structure</a> document. There is no
  requirement that your documentation content follow these guidelines, but
  they provide an effective way to communicate technical specifications for a
  library in a terse yet precise manner that's familiar to many Boost
  users.</p>

  <p>This document also contains links to <a href="#templates">HTML template
  files</a> that can be used to rapidly develop documentation for a library
  submission. These templates follow the guidelines presented here and in the
  <a href="structure.html">Documentation Structure</a> document.</p>

  <h2><a name="common-pages" id="common-pages"></a>Common Pages Included in
  HTML Documentation</h2>

  <p>Most HTML documentation projects will contain some common pages. General
  guidelines for these common pages are provided below.</p>

  <h3><a name="index-page" id="index-page"></a>Index</h3>

  <p>The index page is the first page presented to a user when he browses the
  documentation. Generally this page should not contain any actual content,
  but instead contains a list of links to specific content. At a minimum this
  list should contain a link to every HTML page contained in the
  documentation. Optionally, sub-lists may be provided for individual pages
  linking to specific subjects within the page. These sub-lists should form a
  "tree" hierarchy based on the level of heading tag used for the specific
  subject. Inclusion of such sub-lists for every page can make the index
  rather lengthy, and since each page should include its own <a href=
  "#page-index">Page Index</a>, it may make the navigation of the
  documentation easier if such sub-lists are avoided. However, there is one
  exception to this guideline: reference documentation should contain a link
  to every header file in the library and a sub-list with a link to every
  macro, value, type, class, function and object (see <a href=
  "structure.html">Documentation Structure</a>) found in the header. Users
  aren't always sure what header file any of these may be contained in, so
  this structure in the index allows for easy navigation of the reference
  documentation.</p>

  <p>The index list should generally be constructed using an HTML "definition
  list" (&lt;dl&gt; and &lt;dt&gt; tags). A definition list has no bullets or
  ordered specifications and produces a cleaner layout then an unordered list
  (&lt;ul&gt; and &lt;li&gt; tags) or an ordered list (&lt;ol&gt; and
  &lt;li&gt; tags). If you choose to use the common <a href=
  "#boost-style-sheet">Boost Style Sheet</a> you should add a
  <code>class="index"</code> attribute/value pair to the &lt;dl&gt; tag.</p>

  <p>An Index page <a href="#index-template">template</a> is provided for
  use.</p>

  <h3><a name="overview-page" id="overview-page"></a>Overview</h3>

  <p>The Overview page is used to introduce the reader to the library. It
  should give a high-level overview of the purpose of the library and
  introduce the reader to any concepts they may be unfamiliar with. This may
  also be an appropriate place for some "light" rationale, though more
  thorough presentation of any rationale would be better placed in the
  <a href="#rationale-page">Rational Page</a>.</p>

  <p>Like most content pages, the Overview page should include a <a href=
  "#page-index">Page Index</a>.</p>

  <p>An Overview page <a href="#overview-template">template</a> is provided
  for use.</p>

  <h3><a name="definitions-page" id="definitions-page"></a>Definitions</h3>

  <p>The Definitions page is used to provide a list of definitions for terms
  that a user may be unfamiliar with.</p>

  <p>The definition list should generally be constructed using an HTML
  "definition list" (&lt;dl&gt; and &lt;DT&gt; tags). A definition list has
  no bullets or ordered specifications and produces a cleaner layout then an
  unordered list (&lt;UL&gt; and &lt;li&gt; tags) or an ordered list
  (&lt;ol&gt; and &lt;li&gt; tags). If you choose to use the common <a href=
  "#boost-style-sheet">Boost Style Sheet</a> you should add a
  <code>class="definition"</code> attribute/value pair to the &lt;dl&gt;
  tag.</p>

  <p>Because this page's content should only contain a list of definitions,
  it should not have a <a href="#page-index">Page Index</a>.</p>

  <p>A Definitions page <a href="#definitions-template">template</a> is
  provided for use.</p>

  <h3><a name="rationale-page" id="rationale-page"></a>Rationale</h3>

  <p>The Rationale page is used to provide lengthy descriptions of the
  rationale behind the library's design. This information helps users to
  understand why a library was designed the way it was and may reduce the
  frequency of a number of frequently asked questions. For a better
  description of why rationale is important see the <a href=
  "http://www.boost.org/more/lib_guide.htm#Rationale">Rationale rationale</a>
  in the general submission guidelines.</p>

  <p>Like most content pages, the Rationale page should include a <a href=
  "#page-index">Page Index</a>.</p>

  <p>A Rationale page <a href="#rationale-template">template</a> is provided
  for use.</p>

  <h3><a name="configuration-page" id="configuration-page"></a>Configuration
  Information</h3>

  <p>The Configuration Information page is used to document configuration
  macros used by the library. Such macros belong in one of three groups:
  macros used by library implenters defined in
  <code>&lt;boost/config.hpp&gt;</code>, macros used by library users to
  detect platform configuration information and macros defined by library
  users to configure library behavior.</p>

  <p>Like most content pages, the Overview page should include a <a href=
  "#page-index">Page Index</a>.</p>

  <p>A Configuration page <a href="#configuration-template">template</a> is
  provided for use.</p>

  <h3><a name="faq-page" id="faq-page"></a>Frequently Asked Questions</h3>

  <p>As a library matures the users will have questions about the usage of
  the library. Often users will ask the same questions over and over again.
  Rather than having to deal with answering the question every time it's
  asked, a Frequently Asked Questions (commonly known as FAQs) page can be
  used to document the questions and answers. This is such a valuable piece
  of documentation not only for the users but for the maintainers as well,
  that a FAQ page should be provided from the outset. If there are no
  questions that will obviously become a FAQ, the initial page may just
  indicate that there are no FAQs yet. This empty place holder helps to
  indicate to the users that you plan to address any FAQs as they occur.</p>

  <p>The <a href="#page-index">Page Index</a> for the FAQ page should contain
  a list of all the questions contained in the document. The actual question
  entries should be formatted with the question in a heading tag and the
  answers in standard paragraph format. This provides a clean presentation
  that's easy to read.</p>

  <p>A Frequently Asked Questions page <a href="#faq-template">template</a>
  is provided for use.</p>

  <h3><a name="bibliography-page" id=
  "bibliography-page"></a>Bibliography</h3>

  <p>The Bibliography page is used to document any bibliographical
  information associated with references made within the documentation to
  external resources. Parenthetical references are used within the
  documentation which link to entries in the Bibliography page.
  Bibliographical entries provide detailed information about the external
  resource and may contain hyper links to the resource if it's available
  online. There are several formal styles used for writing bibliographies.
  You may use what ever style you want, but one of the better styles to
  consider using can be referenced <a href=
  "http://www.columbia.edu/cu/cup/cgos/idx_basic.html">here</a>.</p>

  <p>Since the Bibliography page should contain only bibliographical
  information there is no need for a <a href="#page-index">Page
  Index</a>.</p>

  <p>A Bibliography page <a href="#bibliography-template">template</a> is
  provided for use.</p>

  <h3><a name="acknowledgements-page" id=
  "acknowledgements-page"></a>Acknowledgment</h3>

  <p>The Acknowledgment page is used to give credit where credit is due. When
  individuals provide input on the design or implementation, or when you make
  use of someone else's work, you should acknowledge them. This is a courtesy
  that you'd expect others to extend to you, so you should strive to
  acknowledge the efforts of everyone else in your own documentation.</p>

  <p>Since the Acknowledgment page should contain only a list of
  acknowledgment there is no need for a <a href="#page-index">Page
  Index</a>.</p>

  <p>An Acknowledgments page <a href=
  "#acknowledgements-template">template</a> is provided for use.</p>

  <h3><a name="header-page" id="header-page"></a>Header Reference</h3>

  <p>The Header Reference pages are the most important pages in your
  documentation. They document all library headers, including all the macros,
  values, types, classes, functions and objects defined in them. In general
  it may prove useful to follow the guidelines in <a href=
  "structure.html">Documentation Structure</a> when writing the content for
  these pages.</p>

  <p>Like most content pages, the Header Reference pages should include a
  <a href="#page-index">Page Index</a>.</p>

  <p>A Header Reference page <a href="#header-template">template</a> is
  provided for use.</p>

  <h2><a name="layout" id="layout"></a>Layout</h2>

  <p>There are certain page layout concepts that will be used frequently in
  many of your pages. This section outlines some general guidelines that you
  can follow when designing each of these layout concepts for your
  documentation.</p>

  <h3><a name="page-banner" id="page-banner"></a>Page Banner</h3>

  <p>The Page Banner is located at the very top of a page and provides quick
  information about the page contents. This includes the Boost logo, which
  indicates to the reader that this page is part of the Boost web site, a
  title for the documentation (generally the library name) and the page
  title. The Boost logo should hyper link to the Boost home page on the index
  page and to the index page on all other pages. This allows the user to
  easily navigate through the Boost web site and through the documentation.
  The &lt;title&gt; tag for the HTML page should consist of the documentation
  title and the page title separated by a hyphen.</p>

  <p>The Page Banner should be separated from the rest of the page by the use
  of an &lt;hr&gt; tag. This helps to clearly separate the actual content
  from the title information and produces cleaner text.</p>

  <h3><a name="page-index" id="page-index"></a>Page Index</h3>

  <p>The page index is used to quickly navigate to the various sections of
  the documentation on the page, and when present should be located just
  below the Page Banner.</p>

  <p>The index list should generally be constructed using an HTML "definition
  list" (&lt;dl&gt; and &lt;DT&gt; tags). A definition list has no bullets or
  ordered specifications and produces a cleaner layout then an unordered list
  (&lt;UL&gt; and &lt;li&gt; tags) or an ordered list (&lt;ol&gt; and
  &lt;li&gt; tags). If you choose to use the Boost Style Sheet you should add
  a <code>class="page-index"</code> attribute/value pair to the &lt;dl&gt;
  tag.</p>

  <p>Most pages should include a Page Index.</p>

  <h3><a name="content" id="content"></a>Documentation Content</h3>

  <p>The page's actual documentation content will be formatted according to
  the specific needs of individual pages, and should be placed right after
  the Page Index if present, or after the Page Banner if not. In general the
  documentation content will take the form of paragraph text contained
  underneath section headings.</p>

  <h3><a name="doc-footnotes" id="doc-footnotes"></a>Footnotes</h3>

  <p>Footnotes may be used within a page's documentation. Within the
  documentation content a footnote reference should take the form of a
  footnote number in parentheses (the parentheses make it easier for the
  reader to click on the hyper link) hyper linking to the actual footnote at
  the bottom of the page's documentation content. You may either use the
  &lt;sup&gt; tag to format such footnote numbers, or, preferably, you can
  use a CSS style class in order to distinguish the number as a footnote
  instead of as part of the actual text. If you choose to use the common
  <a href="#boost-style-sheet">Boost Style Sheet</a>, a <code>footnote</code>
  class is defined for this purpose.</p>

  <h3><a name="revision-info" id="revision-info"></a>Revision
  Information</h3>

  <p>At the bottom of every page should be some revision information
  indicating when the page was last revised. This information should be
  separated from the rest of the page above by an &lt;hr&gt; tag. The
  following HTML code snippet can be used to track this revision information
  (this code uses some server components that exist on the Boost web site to
  automatically track revision dates with out the need for hand editing the
  date text):</p>
  <pre>
&lt;hr&gt;
&lt;p&gt;Revised
  &lt;!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --&gt;
  01 January, 2001
  &lt;!--webbot bot="Timestamp" endspan i-checksum="39359" --&gt;
&lt;/p&gt;
</pre>

  <h3><a name="copyright" id="copyright"></a>Copyright Information</h3>

  <p>The very bottom of the page should contain any copyright information
  that applies to the document.</p>

  <h2><a name="format" id="format"></a>Format</h2>

  <p>This section provides general guidelines for formatting documentation
  using HTML. The description of the various "common pages" gave specific
  details for formatting specific sections of the documentation, which should
  override these guidelines.</p>

  <h3><a name="code-format" id="code-format"></a>Code</h3>

  <p>Code within the documentation should be placed within either
  &lt;code&gt;&lt;/code&gt; or &lt;pre&gt;&lt;/pre&gt; tags. For code that's
  placed inline with other text you use &lt;code&gt;&lt;/code&gt; tags, while
  &lt;pre&gt;&lt;/pre&gt; tags are used for code "blocks". If a cascading
  style sheet is used to specify formatting for these tags, a fixed width
  sans serif font should be used. This insures that the code is easily
  distinguishable from the rest of the text. It may also be beneficial to set
  the style for &lt;pre&gt;&lt;/pre&gt; tags to indent the text, to help
  separate code blocks from other structural HTML blocks. The <a href=
  "#boost-style-sheet">Boost Style Sheet</a> specifies formatting for these
  tags.</p>

  <p><b>Note:</b> "Code" includes variable names, function names, etc.</p>

  <h3><a name="lists" id="lists"></a>Lists</h3>

  <p>Lists should be constructed as unordered (&lt;UL&gt; and &lt;li&gt;
  tags), ordered (&lt;ol&gt; and &lt;li&gt; tags) or definition (&lt;dl&gt;
  and &lt;DT&gt; tags) lists in HTML. You use an unordered list when you need
  a collection of items that don't have any kind of logical ordering, such as
  a list of data types that are defined by the library and can be used for a
  template argument. You use an ordered list when the collection of items
  must be grouped in a logical ordering, such as when enumerating the steps
  that an action logically performs. You use a definition list when the list
  consists of not only items that have no logical ordering, but also contains
  definitions/descriptions/etc. of the items. A good example of this is the
  function specifications as described in <a href=
  "structure.html">Documentation Structure</a>.</p>

  <h3><a name="graphics" id="graphics"></a>Graphics</h3>

  <p>Graphics should be used very sparingly, if at all. Graphic images
  greatly effect the download time for many people, which can discourage
  users from reading the documentation. If you need graphic images to help
  illustrate something in your documentation consider supplying only a link
  to the image within the documentation, instead of embedding it directly in
  the text. If an image is going to be included in the text of the document
  you should specify the image's size in the &lt;img&gt; tag, in order to
  allow the user's browser to optimize the formatting of the text before the
  image is loaded.</p>

  <h3><a name="non-breaking-spaces" id="non-breaking-spaces"></a>Non-breaking
  Spaces</h3>

  <p>Non-breaking spaces (&amp;nbsp;) should be avoided in HTML text.
  Generally there are more appropriate ways to format the document, such as
  using list constructs or specifying indentation as a style attribute or in
  cascading style sheets.</p>

  <h3><a name="style-sheets" id="style-sheets"></a>Cascading Style
  Sheets</h3>

  <p>Cascading style sheets allow you to apply some advanced formatting
  styles to an HTML document. More importantly, they allow you to change the
  formatting in a single file and effect all pages using the style sheet.
  Instead of struggling to produce a specific format in HTML it's often
  easier and more flexible to specify the formatting in a style sheet.</p>

  <h4><a name="boost-style-sheet" id="boost-style-sheet"></a>Boost Style
  Sheet</h4>

  <p>The concept of using cascading style sheets to format HTML is such a
  good idea that it can be beneficial to apply this across the entire Boost
  site. Of course we can't require this (if Boost were to require such trivia
  for submissions it's likely that many programmers would be discouraged from
  contributing). However, a "standard" Boost style sheet
  (http://www.boost.org/boost.css) is supplied anyway, so that a contributer
  can quickly and easily produce clear and consistent documentation that
  reflects a Boost "brand" if they so choose. If, at a later date, it's
  decided to update the Boost "brand", it may be done in this single file and
  all documents using the style sheet will automatically be updated.</p>

  <p>The Boost supplied style sheet not only specifies styles for many
  standard tags, it also specifies several style "classes". A class is
  specified for a given tag instead of being applied to all instances of a
  given tag type. Below is a list of the classes specified in the Boost style
  sheet and a description of when to use them:</p>

  <dl>
    <dt><b>index</b> Used for &lt;dl&gt; tags when writing index lists.</dt>

    <dt><b>page-index</b> Used for &lt;dl&gt; tags when writing page index
    lists.</dt>

    <dt><b>Footnote</b> Used when writing Footnote numbers.</dt>

    <dt><b>function-semantics</b> Used for &lt;dl&gt; tags when writing
    function semantic lists.</dt>
  </dl>

  <h2><a name="templates" id="templates"></a>Templates</h2>

  <p>Instead of hand coding every HTML page, HTML "templates" can be used
  instead. The list below provides links to templates that may be used when
  writing documentation for a contribution to Boost. Links provided in these
  templates assume the files will reside in the "traditional" directory
  hierarchy of <i>boost/libs/library/doc</i>. They may need correcting if the
  file will reside in some other location.</p>

  <p><b>Note:</b> Since these "templates" are just HTML pages simply clicking
  on the links below will load the template in your browser. You will need to
  use a browser specific method to download the files instead of loading them
  into the browser (for instance, on most Windows browsers you can right
  click on the link and select the appropriate command from the context
  sensitive menu).</p>

  <ul>
    <li><a name="index-template" id="index-template"></a><a href=
    "template/index.html">Index Page Template</a></li>

    <li><a name="overview-template" id="overview-template"></a><a href=
    "template/overview.html">Overview Page Template</a></li>

    <li><a name="definitions-template" id="definitions-template"></a><a href=
    "template/definitions.html">Definitions Page Template</a></li>

    <li><a name="rationale-template" id="rationale-template"></a><a href=
    "template/rationale.html">Rationale Page Template</a></li>

    <li><a name="configuration-template" id=
    "configuration-template"></a><a href=
    "template/configuration.html">Configuration Page Template</a></li>

    <li><a name="faq-template" id="faq-template"></a><a href=
    "template/faq.html">FAQ (Frequently Asked Questions) Page
    Template</a></li>

    <li><a name="bibliography-template" id=
    "bibliography-template"></a><a href=
    "template/bibliography.html">Bibliography Page Template</a></li>

    <li><a name="acknowledgements-template" id=
    "acknowledgements-template"></a><a href=
    "template/acknowledgments.html">Acknowledgments Page Template</a></li>

    <li><a name="header-template" id="header-template"></a><a href=
    "template/header.html">Header Page Template</a></li>
  </ul>
  <hr>

  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
  "../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
  height="31" width="88"></a></p>

  <p>Revised 
  <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
  December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>

  <p><i>Copyright &copy; 2001 <a href=
  "mailto:williamkempf@hotmail.com">William E. Kempf</a></i></p>

  <p><i>Distributed under the Boost Software License, Version 1.0. (See
  accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
  copy at <a href=
  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
  <meta http-equiv="Content-Language" content="en-us">
  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  <link rel="stylesheet" type="text/css" href="../../boost.css">

  <title>Writing Documentation for Boost</title>
</head>

<body link="#0000FF" vlink="#800080">
  <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
  "header">
    <tr>
      <td valign="top" width="300">
        <h3><a href="../../index.htm"><img height="86" width="277" alt=
        "C++ Boost" src="../../boost.png" border="0"></a></h3>
      </td>

      <td valign="top">
        <h1 align="center">Writing Documentation for Boost</h1>

        <h2 align="center">Index</h2>
      </td>
    </tr>
  </table>
  <hr>

  <h2>Contents</h2>

  <dl class="index">
    <dt><a href="introduction.html">Introduction</a></dt>

    <dt><a href="structure.html">Documentation Structure</a></dt>

    <dt><a href="design.html">HTML Design</a></dt>
  </dl>
  <hr>

  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
  "../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
  height="31" width="88"></a></p>

  <p>Revised 
  <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
  December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>

  <p><i>Copyright &copy; 2001 <a href=
  "mailto:williamkempf@hotmail.com">William E. Kempf</a></i></p>

  <p><i>Distributed under the Boost Software License, Version 1.0. (See
  accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
  copy at <a href=
  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
  <meta http-equiv="Content-Language" content="en-us">
  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  <link rel="stylesheet" type="text/css" href="../../boost.css">

  <title>Writing Documentation for Boost - Introduction</title>
</head>

<body link="#0000FF" vlink="#800080">
  <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
  "header">
    <tr>
      <td valign="top" width="300">
        <h3><a href="index.html"><img height="86" width="277" alt="C++ Boost"
        src="../../boost.png" border="0"></a></h3>
      </td>

      <td valign="top">
        <h1 align="center">Writing Documentation for Boost</h1>

        <h2 align="center">Introduction</h2>
      </td>
    </tr>
  </table>
  <hr>

  <p>Boost does not have any requirements on how you write your
  documentation. If you are submitting a library that already has written
  documentation in HTML format, there is no reason to change it to follow any
  of the guidelines presented here. However, if you have documentation that's
  not in HTML format and can't be easily converted to HTML, or if you're
  starting on a library from scratch or have a library with no documentation
  then these guidelines can make writing the documentation much easier.</p>

  <p>The section on <a href="structure.html">Documentation Structure</a>
  describes how to go about structuring the documentation's content. This
  section may be helpful even for libraries that already have documentation.
  If there's a desire to present the library for possible inclusion by the
  C++ Standards Committee then there may be a need to restructure the
  documentation's content in order to insure the content meets explicit
  requirements for library components (Section 17.3).</p>

  <p>The section on <a href="design.html">HTML Design</a> gives general rules
  to follow when writing HTML documentation in order to give a professional
  and consistent look. This section also contains some template files that
  can be used to rapidly create documentation pages.</p>
  <hr>

  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
  "../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
  height="31" width="88"></a></p>

  <p>Revised 
  <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
  December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>

  <p><i>Copyright &copy; 2001 <a href=
  "mailto:williamkempf@hotmail.com">William E. Kempf</a></i></p>

  <p><i>Distributed under the Boost Software License, Version 1.0. (See
  accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
  copy at <a href=
  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
  <meta http-equiv="Content-Language" content="en-us">
  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  <link rel="stylesheet" type="text/css" href="../../boost.css">

  <title>Writing Documentation for Boost - Documentation Structure</title>
</head>

<body link="#0000FF" vlink="#800080">
  <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
  "header">
    <tr>
      <td valign="top" width="300">
        <h3><a href="index.html"><img height="86" width="277" alt="C++ Boost"
        src="../../boost.png" border="0"></a></h3>
      </td>

      <td valign="top">
        <h1 align="center">Writing Documentation for Boost</h1>

        <h2 align="center">Documentation Structure</h2>
      </td>
    </tr>
  </table>
  <hr>

  <dl class="page-index">
    <dt><a href="#introduction">Introduction</a></dt>

    <dt><a href="#standards-conforming">Standards Conforming
    Documentation</a></dt>

    <dd>
      <dl class="page-index">
        <dt><a href="#elements">Document elements</a></dt>

        <dd>
          <dl class="page-index">
            <dt><a href="#summary">Summary</a></dt>

            <dt><a href="#requirements">Requirements</a></dt>

            <dt><a href="#detailed-specs">Detailed specifications</a></dt>

            <dt><a href="#ref-cpp">References to the Standard C++
            library</a></dt>

            <dt><a href="#ref-c">References to the Standard C
            library</a></dt>
          </dl>
        </dd>

        <dt><a href="#other">Other conventions</a></dt>

        <dd>
          <dl class="page-index">
            <dt><a href="#type-descs">Type descriptions</a></dt>
          </dl>
        </dd>
      </dl>
    </dd>

    <dt><a href="#more">More Information</a></dt>

    <dd>
      <dl class="page-index">
        <dt><a href="#function-semantic-explanations">Function semantic
        element explanations</a></dt>

        <dd>
          <dl class="page-index">
            <dt><a href="#requires">Requires</a></dt>

            <dt><a href="#effects">Effects</a></dt>

            <dt><a href="#postconditions">Postconditions</a></dt>

            <dt><a href="#returns">Returns</a></dt>

            <dt><a href="#throws">Throws</a></dt>

            <dt><a href="#complexity">Complexity</a></dt>

            <dt><a href="#rationale">Rationale</a></dt>
          </dl>
        </dd>
      </dl>
    </dd>

    <dt><a href="#web">Web Reference Documentation</a></dt>

    <dt><a href="#footnotes">Footnotes</a></dt>
  </dl>

  <h2><a name="introduction" id="introduction">Introduction</a></h2>

  <p>Boost does not require any specific documentation structure.
  However, there are some important considerations that
  influence content and structure. For example, many Boost
  libraries wind up being proposed for inclusion in the C++
  Standard, so writing them initially with text suitable for
  inclusion in the Standard may be helpful. Also, Boost library
  documentation is often accessed via the World Wide Web,
  including via search engines, so context is often important
  for every page. Finally, Boost libraries should provide
  additional documentation, such as introductory, tutorial,
  example, and rationale content. With those things in mind, we
  suggest the following guidelines for Boost library
  documentation.</p>

  <h2><a name="standards-conforming" id="standards-conforming">Standards
  Conforming</a> Documentation</h2>

  <p>The documentation structure required for the C++ Standard is
  an effective way to describe the technical specifications for
  a library.  Although terse, that format is familiar to many
  Boost users and is far more precise than most ad hoc formats.
  The following description is based upon &sect;17.3 of the
  Standard.  (Note that while final Standard proposals must
  include full standardese wording, which the committee will
  not do for you, that level of detail is not expected of Boost
  library documentation.)</p>

  <h3><a name="elements" id="elements">Document elements</a></h3>

  <p>Each document contains the following elements, as applicable<a class=
  "footnote" href="#footnote1" id="footnote1-location">(1)</a>:</p>

  <ul>
    <li><a href="#summary">Summary</a></li>

    <li><a href="#requirements">Requirements</a></li>

    <li><a href="#detailed-specs">Detailed specifications</a></li>

    <li><a href="#ref-cpp">References to the Standard C++ library</a></li>

    <li><a href="#ref-c">References to the Standard C library</a></li>
  </ul>

  <h4><a name="summary" id="summary">Summary</a></h4>

  <p>The Summary provides a synopsis of the category, and introduces the
  first-level subclauses. Each subclause also provides a summary, listing the
  headers specified in the subclause and the library entities provided in
  each header.</p>

  <p>Paragraphs labeled "Note(s):" or "Example(s):" are informative, other
  paragraphs are normative.</p>

  <p>The summary and the detailed specifications are presented in the
  order:</p>

  <ul>
    <li>Macros</li>

    <li>Values</li>

    <li>Types</li>

    <li>Classes</li>

    <li>Functions</li>

    <li>Objects</li>
  </ul>

  <h4><a name="requirements" id="requirements">Requirements</a></h4>

  <p>The library can be extended by a C++ program. Each clause, as
  applicable, describes the requirements that such extensions must meet. Such
  extensions are generally one of the following:</p>

  <ul>
    <li>Template arguments</li>

    <li>Derived classes</li>

    <li>Containers, iterators, and/or algorithms that meet an interface
    convention</li>
  </ul>

  <p>Interface convention requirements are stated as generally as possible.
  Instead of stating "<code>class X</code> has to define a member function
  <code>operator++()</code>," the interface requires "for any object
  <code>x</code> of <code>class X</code>, <code>++x</code> is defined." That
  is, whether the operator is a member is unspecified.</p>

  <p>Requirements are stated in terms of well-defined expressions, which
  define valid terms of the types that satisfy the requirements. For every
  set of requirements there is a table that specifies an initial set of the
  valid expressions and their semantics. Any generic algorithm that uses the
  requirements is described in terms of the valid expressions for its formal
  type parameters.</p>

  <p>Template argument requirements are sometimes referenced by name.</p>

  <p>In some cases the semantic requirements are presented as C++ code. Such
  code is intended as a specification of equivalance of a construct to
  another construct, not necessarily as the way the construct must be
  implemented.<a class="footnote" href="#footnote2" id="footnote2-location">(2)</a></p>

  <h4><a name="detailed-specs" id="detailed-specs">Detailed
  specification</a></h4>

  <p>The detailed specifications each contain the following elements:</p>

  <ul>
    <li>Name and brief description</li>

    <li>Synopsis (class definition or function prototype, as
    appropriate)</li>

    <li>Restrictions on template arguments, if any</li>

    <li>Description of class invariants</li>

    <li>Description of function semantics</li>
  </ul>

  <p>Descriptions of class member functions follow the order (as
  appropriate)<a class="footnote" href="#footnote3" id="footnote3-location">(3)</a>:</p>

  <ul>
    <li>Constructor(s) and destructor</li>

    <li>Copying and assignment functions</li>

    <li>Comparison functions</li>

    <li>Modifier functions</li>

    <li>Observer functions</li>

    <li>Operators and other non-member functions</li>
  </ul>

  <p>Descriptions of function semantics contain the following <a name=
  "function-elements" id="function-elements">elements</a> (as
  appropriate)<a class="footnote" href="#footnote4" id="footnote4-location">(4):</a></p>

  <dl class="function-semantics">
    <dt><b><a href="#requires">Requires:</a></b> the preconditions for
    calling the function</dt>

    <dt><b><a href="#effects">Effects:</a></b> the actions performed by the
    function</dt>

    <dt><b><a href="#postconditions">Postconditions:</a></b> the observable
    results established by the function</dt>

    <dt><b><a href="#returns">Returns:</a></b> a description of the value(s)
    returned by the function</dt>

    <dt><b><a href="#throws">Throws:</a></b> any exceptions thrown by the
    function, and the conditions that would cause the exception</dt>

    <dt><b><a href="#complexity">Complexity:</a></b> the time and/or space
    complexity of the function</dt>

    <dt><b><a href="#rationale">Rationale:</a></b> the rationale for the
    function's design or existence</dt>
  </dl>

  <p>Complexity requirements specified in the library clauses are upper
  bounds, and implementations that provide better complexity guarantees
  satisfy the requirements.</p>

  <h4><a name="ref-cpp" id="ref-cpp">References to the C++ Standard
  library</a></h4>

  <h4><a name="ref-c" id="ref-c">References to the C Standard
  library</a></h4>

  <h3><a name="other" id="other">Other conventions</a></h3>

  <p>These conventions are for describing implementation-defined types, and
  member functions.</p>

  <h4><a name="type-descs" id="type-descs">Type descriptions</a></h4>

  <p>The Requirements subclauses may describe names that are used to specify
  constraints on template arguments.</p>

  <h2><a name="more" id="more">More Information</a></h2>

  <h3><a name="function-semantic-explanations" id=
  "function-semantic-explanations">Function semantic element
  explanations</a></h3>

  <p>The function semantic element description <a href=
  "#function-elements">above</a> is taken directly from the C++ standard, and
  is quite terse. Here is a more detailed explanation of each of the
  elements.</p>

  <p>Note the use of the <code>&lt;code&gt; ... &lt;/code&gt;</code> font tag
  to distinguish actual C++ usage from English prose.</p>

  <h4><a name="requires" id="requires">Requires</a></h4>

  <p>Preconditions for calling the function, typically expressed as
  predicates. The most common preconditions are requirements on the value of
  arguments, often in the form of C++ expressions. For example,</p>
  <pre>
 
<code>void limit( int * p, int min, int max );</code>
</pre>

  <dl class="function-semantics">
    <dt><b>Requires:</b> <code>p != 0 &amp;&amp; min &lt;= max</code></dt>
  </dl>

  <p>Requirements already enforced by the C++ language rules (such as the
  type of arguments) are not repeated in Requires paragraphs.</p>

  <h4><a name="effects" id="effects">Effects</a></h4>

  <p>The actions performed by the function, described either in prose or in
  C++. A description in prose is often less limiting on implementors, but is
  often less precise than C++ code.</p>

  <p>If an effect is specified in one of the other elements, particularly
  <i>postconditions</i>, <i>returns</i>, or <i>throws</i>, it is not also
  described in the <i>effects</i> paragraph. Having only a single description
  ensures that there is one and only one specification, and thus eliminates
  the risk of divergence.</p>

  <h4><a name="postconditions" id="postconditions">Postconditions</a></h4>

  <p>The observable results of the function, such as the value of variables.
  Postconditions are often expressed as predicates that are true after the
  function completes, in the form of C++ expressions. For example:</p>
  <pre>
 
void make_zero_if_negative( int &amp; x );
</pre>

  <dl class="function-semantics">
    <dt><b>Postcondition:</b> <code>x &gt;= 0</code></dt>
  </dl>

  <h4><a name="returns" id="returns">Returns</a></h4>

  <p>The value returned by the function, usually in the form of a C++
  expression. For example:</p>
  <pre>
int sum( int x, int y );
</pre>

  <dl class="function-semantics">
    <dt><b>Returns:</b> <code>x + y</code></dt>
  </dl>

  <p>Only specify the return value; the type is already dictated by C++
  language rules.</p>

  <h4><a name="throws" id="throws">Throws</a></h4>

  <p>Specify both the type of exception thrown, and the condition that causes
  the exception to be thrown. For example, the <code>std::basic_string</code>
  class specifies:</p>
  <pre>
 
void resize(size_type n, charT c);
</pre>

  <dl class="function-semantics">
    <dt><b>Throws:</b> <code>length_error</code> if <code>n &gt;
    max_size()</code>.</dt>
  </dl>

  <h4><a name="complexity" id="complexity">Complexity</a></h4>

  <p>Specifying the time and/or space complexity of a function is often not
  desirable because it over-constrains implementors and is hard to specify
  correctly. Complexity is thus often best left as a quality of
  implementation issue.</p>

  <p>A library component, however, can become effectively non-portable if
  there is wide variation in performance between conforming implementations.
  Containers are a prime example. In these cases it becomes worthwhile to
  specify complexity.</p>

  <p>Complexity is often specified in generalized <a href=
  "http://hissa.nist.gov/dads/HTML/bigOnotation.html">"Big-O"
  notation</a>.</p>

  <h4><a name="rationale" id="rationale">Rationale</a></h4>

  <p>Specifying the rationale for a function's design or existence can often
  give users a lot of insight into why a library is designed the way it is.
  More importantly, it can help prevent "fixing" something that wasn't really
  broken as the library matures.</p>
  
  <h2 id="web">Web Reference Documentation</h2>

  <p>Boost library documentation is often accessed via the World
  Web. Using search engines, a page deep in the reference
  content could be viewed without any further context.
  Therefore, it is helpful to add extra context, such as the
  following, to each page:</p>

  <ul>
  <li>Describe the enclosing namespace or use fully scoped
    identifiers.
  <li>Document required headers for each type or function.
  <li>Link to relevant tutorial information.
  <li>Link to related example code.
  <li>Include the library name.
  <li>Include navigation elements to the beginning of the
    documentation.
  </ul>

  <p>It is also useful to consider the effectiveness of a
  description in search engines. Terse or cryptic descriptions
  are less likely to help the curious find a relevant function
  or type.</p>

  <h2><a name="footnotes" id="footnotes">Footnotes</a></h2>

  <dl>
    <dt><a class="footnote" id="footnote1" href="#footnote1-location">(1)</a> To save
    space, items that do not apply to a clause are omitted. For example, if a
    clause does not specify any requirements, there will be no "Requirements"
    subclause.</dt>

    <dt><a class="footnote" id="footnote2" href="#footnote2-location">(2)</a> Although
    in some cases the code is unambiguously the optimum implementation.</dt>

    <dt><a class="footnote" id="footnote3" href="#footnote3-location">(3)</a> To save
    space, items that do not apply to a class are omitted. For example, if a
    class does not specify any comparison functions, there will be no
    "Comparison functions" subclause.</dt>

    <dt><a class="footnote" id="footnote4" href="#footnote4-location">(4)</a> To save
    space, items that do not apply to a function are omitted. For example, if
    a function does not specify any precondition, there will be no "Requires"
    paragraph.</dt>
  </dl>
  <hr>

  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
  "../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
  height="31" width="88"></a></p>

  <p>Revised 
  <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
  December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>

  <p><i>Copyright &copy; 2001 <a href=
  "mailto:williamkempf@hotmail.com">William E. Kempf</a></i></p>

  <p><i>Distributed under the Boost Software License, Version 1.0. (See
  accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
  copy at <a href=
  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
  <meta http-equiv="Content-Language" content="en-us">
  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  <link rel="stylesheet" type="text/css" href="../../../boost.css">

  <title>{{Library}} - Acknowledgments</title>
</head>

<body link="#0000FF" vlink="#800080">
  <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
  "header">
    <tr>
      <td valign="top" width="300">
        <h3><a href="../../../index.htm"><img height="86" width="277" alt=
        "C++ Boost" src="../../../boost.png" border="0"></a></h3>
      </td>

      <td valign="top">
        <h1 align="center">{{Library}}</h1>

        <h2 align="center">Acknowledgments</h2>
      </td>
    </tr>
  </table>
  <hr>
  {{text}}
  <hr>

  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
  "../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
  height="31" width="88"></a></p>

  <p>Revised 
  <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
  December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>

  <p><i>Copyright &copy; 2006 <a href=
  "mailto:{{address}}">{{author}}</a></i></p>

  <p><i>Distributed under the Boost Software License, Version 1.0. (See
  accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
  copy at <a href=
  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
  <meta http-equiv="Content-Language" content="en-us">
  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  <link rel="stylesheet" type="text/css" href="../../../boost.css">

  <title>{{Library}} - Bibliography</title>
</head>

<body link="#0000FF" vlink="#800080">
  <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
  "header">
    <tr>
      <td valign="top" width="300">
        <h3><a href="../../../index.htm"><img height="86" width="277" alt=
        "C++ Boost" src="../../../boost.png" border="0"></a></h3>
      </td>

      <td valign="top">
        <h1 align="center">{{Library}}</h1>

        <h2 align="center">Bibliography</h2>
      </td>
    </tr>
  </table>
  <hr>
  {{bibliographical information}}
  <hr>

  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
  "../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
  height="31" width="88"></a></p>

  <p>Revised 
  <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
  December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>

  <p><i>Copyright &copy; 2006 <a href=
  "mailto:{{address}}">{{author}}</a></i></p>

  <p><i>Distributed under the Boost Software License, Version 1.0. (See
  accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
  copy at <a href=
  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
  <meta http-equiv="Content-Language" content="en-us">
  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  <link rel="stylesheet" type="text/css" href="../../../boost.css">

  <title>{{Library}} - Configuration</title>
</head>

<body link="#0000FF" vlink="#800080">
  <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
  "header">
    <tr>
      <td valign="top" width="300">
        <h3><a href="../../../index.htm"><img height="86" width="277" alt=
        "C++ Boost" src="../../../boost.png" border="0"></a></h3>
      </td>

      <td valign="top">
        <h1 align="center">{{Library}}</h1>

        <h2 align="center">Configuration</h2>
      </td>
    </tr>
  </table>
  <hr>

  <dl class="page-index">
    <dt><a href="#introduction">Introduction</a></dt>

    <dt><a href="#app-defined">Application Defined Macros</a></dt>

    <dt><a href="#lib-defined-public">Public Library Defined Macros</a></dt>

    <dt><a href="#lib-defined-impl">Library Defined Implementation
    Macros</a></dt>
  </dl>

  <h2><a name="introduction" id="introduction"></a>Introduction</h2>

  <p>{{library}} uses several configuration macros in <a href=
  "http://www.boost.org/libs/config/config.htm">&lt;boost/config.hpp&gt;</a>,
  as well as configuration macros meant to be supplied by the application.
  These macros are documented here.</p>

  <h2><a name="app-defined" id="app-defined"></a>Application Defined
  Macros</h2>

  <p>These are the macros that may be defined by an application using
  {{library}}.</p>

  <table summary="application defined macros" cellspacing="10" width="100%">
    <tr>
      <td><b>Macro</b></td>

      <td><b>Meaning</b></td>
    </tr>

    <tr>
      <td>{{macro}}</td>

      <td>{{meaning}}</td>
    </tr>

    <tr>
      <td>{{macro}}</td>

      <td>{{meaning}}</td>
    </tr>
  </table>

  <h2><a name="lib-defined-public" id="lib-defined-public"></a>Public Library
  Defined Macros</h2>

  <p>These macros are defined by {{library}} but are expected to be used by
  application code.</p>

  <table summary="public library defined macros" cellspacing="10" width=
  "100%">
    <tr>
      <td><b>Macro</b></td>

      <td><b>Meaning</b></td>
    </tr>

    <tr>
      <td>{{macro}}</td>

      <td>{{meaning}}</td>
    </tr>

    <tr>
      <td>{{macro}}</td>

      <td>{{meaning}}</td>
    </tr>
  </table>

  <h2><a name="lib-defined-impl" id="lib-defined-impl"></a>Library Defined
  Implementation Macros</h2>

  <p>These macros are defined by {{library}} and are implementation details
  of interest only to implementers.</p>

  <table summary="library defined implementation macros" cellspacing="10"
  width="100%">
    <tr>
      <td><b>Macro</b></td>

      <td><b>Meaning</b></td>
    </tr>

    <tr>
      <td>{{macro}}</td>

      <td>{{meaning}}</td>
    </tr>

    <tr>
      <td>{{macro}}</td>

      <td>{{meaning}}</td>
    </tr>
  </table>
  <hr>

  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
  "../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
  height="31" width="88"></a></p>

  <p>Revised 
  <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
  December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>

  <p><i>Copyright &copy; 2006 <a href=
  "mailto:{{address}}">{{author}}</a></i></p>

  <p><i>Distributed under the Boost Software License, Version 1.0. (See
  accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
  copy at <a href=
  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
  <meta http-equiv="Content-Language" content="en-us">
  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  <link rel="stylesheet" type="text/css" href="../../../boost.css">

  <title>{{Library}} - Definitions</title>
</head>

<body link="#0000FF" vlink="#800080">
  <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
  "header">
    <tr>
      <td valign="top" width="300">
        <h3><a href="../../../index.htm"><img height="86" width="277" alt=
        "C++ Boost" src="../../../boost.png" border="0"></a></h3>
      </td>

      <td valign="top">
        <h1 align="center">{{Library}}</h1>

        <h2 align="center">Definitions</h2>
      </td>
    </tr>
  </table>
  <hr>

  <h2>Contents</h2>

  <dl class="page-index">
    <dt><a href="#introduction">Introduction</a></dt>

    <dt><a href="#definitions">Definitions</a></dt>

    <dd>
      <dl class="page-index">
        <dt><a href="#definition-term1">Term 1</a></dt>

        <dt><a href="#definition-term2">Term 2</a></dt>
      </dl>
    </dd>
  </dl>
  <hr>

  <h2><a name="introduction" id="introduction"></a>Introduction</h2>

  <p>{{Introductory text}}</p>

  <h2><a name="definitions" id="definitions"></a>Definitions</h2>

  <dl class="definitions">
    <dt><a name="definition-term1" id="definition-term1"></a><b>{{term}}:</b>
    {{definition}}</dt>

    <dt><a name="definition-term2" id="definition-term2"></a><b>{{term}}:</b>
    {{definition}}</dt>
  </dl>
  <hr>

  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
  "../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
  height="31" width="88"></a></p>

  <p>Revised 
  <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
  December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>

  <p><i>Copyright &copy; 2006 <a href=
  "mailto:{{address}}">{{author}}</a></i></p>

  <p><i>Distributed under the Boost Software License, Version 1.0. (See
  accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
  copy at <a href=
  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
  <meta http-equiv="Content-Language" content="en-us">
  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  <link rel="stylesheet" type="text/css" href="../../../boost.css">

  <title>{{Library}} - FAQ</title>
</head>

<body link="#0000FF" vlink="#800080">
  <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
  "header">
    <tr>
      <td valign="top" width="300">
        <h3><a href="../../../index.htm"><img height="86" width="277" alt=
        "C++ Boost" src="../../../boost.png" border="0"></a></h3>
      </td>

      <td valign="top">
        <h1 align="center">{{Library}}</h1>

        <h2 align="center">Frequently Asked Questions (FAQs)</h2>
      </td>
    </tr>
  </table>
  <hr>

  <dl class="page-index">
    <dt><a href="#question1">{{question}}</a></dt>

    <dt><a href="#question2">{{question}}</a></dt>
  </dl>

  <h2><a name="question1" id="question1"></a>{{question}}</h2>

  <p>{{answer}}</p>

  <h2><a name="question2" id="question2"></a>{{question}}</h2>

  <p>{{answer}}</p>
  <hr>

  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
  "../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
  height="31" width="88"></a></p>

  <p>Revised 
  <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
  December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>

  <p><i>Copyright &copy; 2006 <a href=
  "mailto:{{address}}">{{author}}</a></i></p>

  <p><i>Distributed under the Boost Software License, Version 1.0. (See
  accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
  copy at <a href=
  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
  <meta http-equiv="Content-Language" content="en-us">
  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  <link rel="stylesheet" type="text/css" href="../../../boost.css">

  <title>{{library}} - Header &lt;{{header}}&gt;</title>
</head>

<body link="#0000FF" vlink="#800080">
  <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
  "header">
    <tr>
      <td valign="top" width="300">
        <h3><a href="../../../index.htm"><img height="86" width="277" alt=
        "C++ Boost" src="../../../boost.png" border="0"></a></h3>
      </td>

      <td valign="top">
        <h1 align="center">{{library}}</h1>

        <h2 align="center">Header &lt;{{header}}&gt;</h2>
      </td>
    </tr>
  </table>
  <hr>

  <h2>Contents</h2>

  <dl class="page-index">
    <dt><a href="#introduction">Introduction</a></dt>

    <dt><a href="#macros">Macros</a></dt>

    <dd>
      <dl class="page-index">
        <dt><a href="#macro-spec">{{macro name}}</a></dt>
      </dl>
    </dd>

    <dt><a href="#values">Values</a></dt>

    <dd>
      <dl class="page-index">
        <dt><a href="#value-spec">{{value name}}</a></dt>
      </dl>
    </dd>

    <dt><a href="#types">Types</a></dt>

    <dd>
      <dl class="page-index">
        <dt><a href="#type-spec">{{type name}}</a></dt>
      </dl>
    </dd>

    <dt><a href="#classes">Classes</a></dt>

    <dd>
      <dl class="page-index">
        <dt><a href="#class-spec">Class <code>{{class name}}</code></a></dt>

        <dd>
          <dl class="page-index">
            <dt><a href="#class-spec-synopsis">Class <code>{{class
            name}}</code> synopsis</a></dt>

            <dt><a href="#class-spec-ctors">Class <code>{{class name}}</code>
            constructors and destructor</a></dt>

            <dt><a href="#class-spec-comparisons">Class <code>{{class
            name}}</code> comparison functions</a></dt>

            <dt><a href="#class-spec-modifiers">Class <code>{{class
            name}}</code> modifier functions</a></dt>

            <dt><a href="#class-spec-observers">Class <code>{{class
            name}}</code> observer functions</a></dt>

            <dt><a href="#class-spec-statics">Class <code>{{class
            name}}</code> static functions</a></dt>
          </dl>
        </dd>
      </dl>
    </dd>

    <dt><a href="#functions">Functions</a></dt>

    <dd>
      <dl class="page-index">
        <dt><a href="#function-spec">{{function name}}</a></dt>
      </dl>
    </dd>

    <dt><a href="#objects">Objects</a></dt>

    <dd>
      <dl class="page-index">
        <dt><a href="#object-spec">{{object name}}</a></dt>
      </dl>
    </dd>

    <dt><a href="#examples">Example(s)</a></dt>
  </dl>
  <hr>

  <h2><a name="introduction" id="introduction"></a>Introduction</h2>

  <p>{{Introductory text}}</p>

  <h2><a name="macros" id="macros"></a>Macros</h2>

  <p><a name="macro-spec" id="macro-spec"></a>{{Macro specifications}}</p>

  <h2><a name="values" id="values"></a>Values</h2>

  <p><a name="value-spec" id="value-spec"></a>{{Value specifications}}</p>

  <h2><a name="types" id="types"></a>Types</h2>

  <p><a name="type-spec" id="type-spec"></a>{{Type specifications}}</p>

  <h2><a name="classes" id="classes"></a>Classes</h2>

  <h3><a name="class-spec" id="class-spec"></a>Class <code>{{class
  name}}</code></h3>

  <p>{{class overview text}}</p>

  <h4><a name="class-spec-synopsis" id="class-spec-synopsis"></a>Class
  <code>{{class name}}</code> synopsis</h4>
  <pre>
namespace boost
{
    class {{class name}}
        {
        };
};
</pre>

  <h4><a name="class-spec-ctors" id="class-spec-ctors"></a>Class
  <code>{{class name}}</code> constructors and destructor</h4>
  <pre>
{{constructor}}
</pre>

  <dl class="function-semantics">
    <dt><b>Requires:</b> {{text}}</dt>

    <dt><b>Effects:</b> {{text}}</dt>

    <dt><b>Postconditions:</b> {{text}}</dt>

    <dt><b>Returns:</b> {{text}}</dt>

    <dt><b>Throws:</b> {{text}}</dt>

    <dt><b>Complexity:</b> {{text}}</dt>

    <dt><b>Note:</b> {{text}}</dt>

    <dt><b>Danger:</b> {{text}}</dt>

    <dt><b>Rationale:</b> {{text}}</dt>
  </dl>
  <pre>
{{destructor}}
</pre>

  <dl class="function-semantics">
    <dt><b>Requires:</b> {{text}}</dt>

    <dt><b>Effects:</b> {{text}}</dt>

    <dt><b>Postconditions:</b> {{text}}</dt>

    <dt><b>Returns:</b> {{text}}</dt>

    <dt><b>Throws:</b> {{text}}</dt>

    <dt><b>Complexity:</b> {{text}}</dt>

    <dt><b>Note:</b> {{text}}</dt>

    <dt><b>Danger:</b> {{text}}</dt>

    <dt><b>Rationale:</b> {{text}}</dt>
  </dl>

  <h4><a name="class-spec-comparisons" id="class-spec-comparisons"></a>Class
  <code>{{class name}}</code> comparison functions</h4>
  <pre>
{{function}}
</pre>

  <dl class="function-semantics">
    <dt><b>Requires:</b> {{text}}</dt>

    <dt><b>Effects:</b> {{text}}</dt>

    <dt><b>Postconditions:</b> {{text}}</dt>

    <dt><b>Returns:</b> {{text}}</dt>

    <dt><b>Throws:</b> {{text}}</dt>

    <dt><b>Complexity:</b> {{text}}</dt>

    <dt><b>Note:</b> {{text}}</dt>

    <dt><b>Danger:</b> {{text}}</dt>

    <dt><b>Rationale:</b> {{text}}</dt>
  </dl>

  <h4><a name="class-spec-modifiers" id="class-spec-modifiers"></a>Class
  <code>{{class name}}</code> modifier functions</h4>
  <pre>
{{function}}
</pre>

  <dl class="function-semantics">
    <dt><b>Requires:</b> {{text}}</dt>

    <dt><b>Effects:</b> {{text}}</dt>

    <dt><b>Postconditions:</b> {{text}}</dt>

    <dt><b>Returns:</b> {{text}}</dt>

    <dt><b>Throws:</b> {{text}}</dt>

    <dt><b>Complexity:</b> {{text}}</dt>

    <dt><b>Note:</b> {{text}}</dt>

    <dt><b>Danger:</b> {{text}}</dt>

    <dt><b>Rationale:</b> {{text}}</dt>
  </dl>

  <h4><a name="class-spec-observers" id="class-spec-observers"></a>Class
  <code>{{class name}}</code> observer functions</h4>
  <pre>
{{function}}
</pre>

  <dl class="function-semantics">
    <dt><b>Requires:</b> {{text}}</dt>

    <dt><b>Effects:</b> {{text}}</dt>

    <dt><b>Postconditions:</b> {{text}}</dt>

    <dt><b>Returns:</b> {{text}}</dt>

    <dt><b>Throws:</b> {{text}}</dt>

    <dt><b>Complexity:</b> {{text}}</dt>

    <dt><b>Note:</b> {{text}}</dt>

    <dt><b>Danger:</b> {{text}}</dt>

    <dt><b>Rationale:</b> {{text}}</dt>
  </dl>

  <h4><a name="class-spec-statics" id="class-spec-statics"></a>Class
  <code>{{class name}}</code> static functions</h4>
  <pre>
{{function}}
</pre>

  <dl class="function-semantics">
    <dt><b>Requires:</b> {{text}}</dt>

    <dt><b>Effects:</b> {{text}}</dt>

    <dt><b>Postconditions:</b> {{text}}</dt>

    <dt><b>Returns:</b> {{text}}</dt>

    <dt><b>Throws:</b> {{text}}</dt>

    <dt><b>Complexity:</b> {{text}}</dt>

    <dt><b>Note:</b> {{text}}</dt>

    <dt><b>Danger:</b> {{text}}</dt>

    <dt><b>Rationale:</b> {{text}}</dt>
  </dl>

  <h2><a name="functions" id="functions"></a>Functions</h2>
  <pre>
<a name="function-spec" id="function-spec"></a>{{function}}
</pre>

  <dl class="function-semantics">
    <dt><b>Requires:</b> {{text}}</dt>

    <dt><b>Effects:</b> {{text}}</dt>

    <dt><b>Postconditions:</b> {{text}}</dt>

    <dt><b>Returns:</b> {{text}}</dt>

    <dt><b>Throws:</b> {{text}}</dt>

    <dt><b>Complexity:</b> {{text}}</dt>

    <dt><b>Note:</b> {{text}}</dt>

    <dt><b>Danger:</b> {{text}}</dt>

    <dt><b>Rationale:</b> {{text}}</dt>
  </dl>

  <h2><a name="objects" id="objects"></a>Objects</h2>

  <p><a name="object-spec" id="object-spec"></a>{{Object specifications}}</p>

  <h2><a name="examples" id="examples"></a>Example(s)</h2>

  <p>{{Example(s)}}</p>
  <hr>

  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
  "../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
  height="31" width="88"></a></p>

  <p>Revised 
  <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
  December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>

  <p><i>Copyright &copy; 2006 <a href=
  "mailto:{{address}}">{{author}}</a></i></p>

  <p><i>Distributed under the Boost Software License, Version 1.0. (See
  accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
  copy at <a href=
  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
  <meta http-equiv="Content-Language" content="en-us">
  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  <link rel="stylesheet" type="text/css" href="../../../boost.css">

  <title>{{Library}}</title>
</head>

<body link="#0000FF" vlink="#800080">
  <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
  "header">
    <tr>
      <td valign="top" width="300">
        <h3><a href="../../../index.htm"><img height="86" width="277" alt=
        "C++ Boost" src="../../../boost.png" border="0"></a></h3>
      </td>

      <td valign="top">
        <h1 align="center">{{Library}}</h1>

        <h2 align="center">Index</h2>
      </td>
    </tr>
  </table>
  <hr>

  <h2>Contents</h2>

  <dl class="index">
    <dt><a href="overview.html">Overview</a></dt>

    <dt>Reference</dt>

    <dd>
      <dl class="index">
        <dt><a href="header.html">{{header}}</a></dt>

        <dd>
          <dl class="index">
            <dt><a href="header.html#macros">Macros</a></dt>

            <dd>
              <dl class="index">
                <dt><a href="header.html#macro-spec">{{macro name}}</a></dt>
              </dl>
            </dd>

            <dt><a href="header.html#values">Values</a></dt>

            <dd>
              <dl class="index">
                <dt><a href="header.html#value-spec">{{value name}}</a></dt>
              </dl>
            </dd>

            <dt><a href="header.html#types">Types</a></dt>

            <dd>
              <dl class="index">
                <dt><a href="header.html#value-spec">{{type name}}</a></dt>
              </dl>
            </dd>

            <dt><a href="header.html#classes">Classes</a></dt>

            <dd>
              <dl class="index">
                <dt><a href="header.html#value-spec">{{class name}}</a></dt>
              </dl>
            </dd>

            <dt><a href="header.html#functions">Functions</a></dt>

            <dd>
              <dl class="index">
                <dt><a href="header.html#value-spec">{{function
                name}}</a></dt>
              </dl>
            </dd>

            <dt><a href="header.html#objects">Objects</a></dt>

            <dd>
              <dl class="index">
                <dt><a href="header.html#value-spec">{{object name}}</a></dt>
              </dl>
            </dd>
          </dl>
        </dd>
      </dl>
    </dd>

    <dt><a href="configuration.html">Configuration Information</a></dt>

    <dt><a href="rationale.html">Rationale</a></dt>

    <dt><a href="definitions.html">Definitions</a></dt>

    <dt><a href="faq.html">Frequently Asked Questions (FAQs)</a></dt>

    <dt><a href="bibliography.html">Bibliography</a></dt>

    <dt><a href="acknowledgments.html">Acknowledgments</a></dt>
  </dl>
  <hr>

  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
  "../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
  height="31" width="88"></a></p>

  <p>Revised 
  <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
  December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>

  <p><i>Copyright &copy; 2006 <a href=
  "mailto:{{address}}">{{author}}</a></i></p>

  <p><i>Distributed under the Boost Software License, Version 1.0. (See
  accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
  copy at <a href=
  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
  <meta http-equiv="Content-Language" content="en-us">
  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  <link rel="stylesheet" type="text/css" href="../../../boost.css">

  <title>{{Library}} - Overview</title>
</head>

<body link="#0000FF" vlink="#800080">
  <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
  "header">
    <tr>
      <td valign="top" width="300">
        <h3><a href="../../../index.htm"><img height="86" width="277" alt=
        "C++ Boost" src="../../../boost.png" border="0"></a></h3>
      </td>

      <td valign="top">
        <h1 align="center">{{Library}}</h1>

        <h2 align="center">Overview</h2>
      </td>
    </tr>
  </table>
  <hr>

  <dl class="index">
    <dt><a href="#introduction">Introduction</a></dt>

    <dt><a href="#topic1">First topic</a></dt>

    <dt><a href="#topic2">Second topic</a></dt>

    <dt><a href="#footnotes">Footnotes</a></dt>
  </dl>

  <h2><a name="introduction" id="introduction"></a>Introduction</h2>

  <p>{{text}}</p>

  <h2><a name="topic1" id="topic1"></a>First Topic</h2>

  <p>{{text}}</p>

  <h2><a name="topic2" id="topic2"></a>Second Topic</h2>

  <p>{{text}}</p>

  <h2><a name="footnotes" id="footnotes"></a>Footnotes</h2>

  <dl>
    <dt><a name="footnote1" class="footnote" id="footnote1">(1)</a>
    {{text}}</dt>

    <dt><a name="footnote2" class="footnote" id="footnote2">(2)</a>
    {{text}}</dt>
  </dl>
  <hr>

  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
  "../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
  height="31" width="88"></a></p>

  <p>Revised 
  <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
  December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>

  <p><i>Copyright &copy; 2006 <a href=
  "mailto:{{address}}">{{author}}</a></i></p>

  <p><i>Distributed under the Boost Software License, Version 1.0. (See
  accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
  copy at <a href=
  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
  <meta http-equiv="Content-Language" content="en-us">
  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  <link rel="stylesheet" type="text/css" href="../../../boost.css">

  <title>{{Library}} - Rationale</title>
</head>

<body link="#0000FF" vlink="#800080">
  <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
  "header">
    <tr>
      <td valign="top" width="300">
        <h3><a href="../../../index.htm"><img height="86" width="277" alt=
        "C++ Boost" src="../../../boost.png" border="0"></a></h3>
      </td>

      <td valign="top">
        <h1 align="center">{{Library}}</h1>

        <h2 align="center">Rationale</h2>
      </td>
    </tr>
  </table>
  <hr>

  <dl class="index">
    <dt><a href="#introduction">Introduction</a></dt>

    <dt><a href="#topic1">First topic</a></dt>

    <dt><a href="#topic2">Second topic</a></dt>

    <dt><a href="#footnotes">Footnotes</a></dt>
  </dl>

  <h2><a name="introduction" id="introduction"></a>Introduction</h2>

  <p>{{text}}</p>

  <h2><a name="topic1" id="topic1"></a>First Topic</h2>

  <p>{{text}}</p>

  <h2><a name="topic2" id="topic2"></a>Second Topic</h2>

  <p>{{text}}</p>

  <h2><a name="footnotes" id="footnotes"></a>Footnotes</h2>

  <dl>
    <dt><a name="footnote1" class="footnote" id="footnote1">(1)</a>
    {{text}}</dt>

    <dt><a name="footnote2" class="footnote" id="footnote2">(2)</a>
    {{text}}</dt>
  </dl>
  <hr>

  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
  "../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
  height="31" width="88"></a></p>

  <p>Revised 
  <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04
  December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>

  <p><i>Copyright &copy; 2006 <a href=
  "mailto:{{address}}">{{author}}</a></i></p>

  <p><i>Distributed under the Boost Software License, Version 1.0. (See
  accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
  copy at <a href=
  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>