If you have a proposed patch to the code, post it along with your bug
- report, preferably in the context diffs format (diff -c);
+ report, preferably in the unified diffs format (cvs diff -du);
if you can, send a patch relative to the current CVS state. A canonical
example of creating a patch file follows (let's assume that you've found
a bug in the file intentional_bug.hpp:
diff --git a/getting_started.html b/getting_started.html
index 6d74694..2f59118 100644
--- a/getting_started.html
+++ b/getting_started.html
@@ -1,1054 +1,1554 @@
+
-
- Getting Started
-
-
-
-
-
-
-
These instructions are intended to help you get started using the Boost
- Libraries. This walks you through getting, building, and installing the
- libraries. To summarize these are the steps to get Boost built and installed:
The Boost Libraries are distributed through the SourceForge file distribution
- system. Click here to
- download releases from SourceForge. And
- unpack the release to a convenient location.
-
-
-
The Boost release includes all of the libraries and other material from the web
- site. It is available in ZIP, TAR.GZ,
- and TAR.BZ2 formats. Past releases are also available.
- It is also possible to download current snapshots of work-in-progress from
- Boost's CVS repository.
-
- The .zip format is widely supported by both free decoders and commercial
- compress/archive utilities. If you don't already have a .zip file decoder,
- download one from the Info-ZIP web site,
- which supplies versions for many operating systems.
-
Text file line endings in the .zip file are as supplied by each library
- developer. This works fine for Windows, but not for Unix/Linux. The
- .tar.gz and .tar.bz2 files supply Unix/Linux friendly line endings.
The .tar.gz format is widely supported on Unix/Linux platforms. Some Windows
- compress/archive utilities can read the format as well. Because the gzip
- format compresses the archive as a single file rather than compressing each
- file individually, the .tar.gz file is smaller that the .zip file.
-
The .tar.bz2 format is becoming widely available on Unix/Linux platforms and is
- built into many tar utilities. This format differs for the .tar.gz format in
- the compression used, which is considerably better and therefore creates
- smaller files.
-
Text file line endings in the .tar.gz and .tar.bz2 files have been converted to
- newlines for ease of use on Unix/Linux platforms.
All Boost files, including the entire distribution tree including web site HTML
- is maintained in a CVS repository. Command line, GUI, or browser access is
- available.
-
Boost CVS access via command line or graphical clients
- For those who have CVS clients installed, the libraries are also available from
- the public Boost CVS
- repository. Free command line clients (often already installed on
- Linux/Unix systems) are available for many systems, and free GUI clients are
- available for Windows, Mac, and other systems.
-
See the much improved CVS
- documentation (Section F) from SourceForge, which includes links to the
- home pages for various GUI and command line clients.
-
The general procedure for command-line clients is something like this:
-
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/boost login
- [Hit <return> when it asks for a password]
- cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/boost checkout
- boost
- cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/boost logout
- Read the manual for your CVS client for further information.
+
+ Getting Started
+
+
+
+
+
+
-
This access is read-only; if you are a library author and
- wish to have CVS write access, please contact one of the moderators.
- For confirmation of write access, check the sourceforge
- boost project member list, available via a link on this page.
-
- For access to the CVS archive from any modern web browser, you can also use the
- web browser interface. Try one of the color diffs to see how
- a file has changed over time. Note: this interface is only suitable for
- viewing individual files and their revision histories.
-
Some of the Boost documentation is generated from
- BoostBook XML source stored in the CVS repository, and will not appear
- directly in the CVS tree as readable HTML. View a nightly build of the
- generated HTML on the
- Nightly Generated Documentation page. Where generated HTML is missing
- from the CVS tree, an attempt has been made to include redirection to this
- nightly build, but if you are away from an internet connection you may want to
- download the generated documentation archive from the aforementioned page so
- you can browse those documents offline.
-
Preparation
-
The recommended way to build and install the Boost Libraries is to use
- Boost.Build, the Boost Build system. The rest of these instructions
- explain that use, but it is up to you to use this method, or not. Note that
- some of the libraries also include non Boost.Build makefiles and/or project
- files. But all include the needed files for building with Boost.Build.
-
-
-
2
-
The build system uses Boost.Jam,
- an extension of the Perforce Jam
- portable make replacement. The recommended way to get Boost.Jam if you
- are using a Boost distribution is to
- download a prebuilt executable from SourceForge. If a
- prebuilt executable is not provided for your platform or you are using Boost's
- sources in an unreleased state, it may be necessary to
- build bjam from sources included in the Boost source tree. To
- install Boost.Jam, copy the bjam executable to a location accessible
- in your PATH.
Before using Boost.Build you will need to configure the compiler tools you are
- using. The build system's toolsets are designed to work in either of two ways:
-
-
- The user sets up all of the environment for each toolset he wants to use in the
- normal way. For example, for Microsoft VC++, ...VC98/Bin or .../VC7/Bin is in
- the PATH environment variable, VCVARS32.BAT or VSVARS32.BAT has been invoked,
- etc. For Metrowerks CodeWarrior, cwenv.bat or equivalent has been called and
- ...Other Metrowerks Tools/Command Line Tools is in the path. Many Unix
- operating systems come preconfigured this way and require no user intervention.
-
-
- The user doesn't want his environment cluttered with settings or has
- nonstandard installations for some of his tools. Instead, he or she sets
- variables which point to the toolset installation directories, either in the
- command shell environment or on the bjam command-line. These
- variables are used by the build system to locate the tools and invoke the
- necessary setup. To set the variables on the bjam command-line you use
- the "-s" option. For example:
-
- bjam "-sGCC_ROOT_DIRECTORY=/usr/local/gcc-3.3.2"
-
- Some variables, like the toolset TOOLS variable, can accept multiple
- values separated by spaces. Others, like the path above, can contain spaces.
- For such circumstances you should use quotes appropriate for your command
- interpreter.
-
GNU GCC and associated tools in MinGW configuration
- (produces commercially redistributable objects), using the
- STLport standard library implementation
Microsoft Visual C++ version
- 6 command-line tools, using the STLport standard
- library implementation. NOTE; For version 7.x (the .NET series) use the
- vc7-stlport or vc-7_1-stlport toolsets below.
The default build and install attempts to build all available libraries and
- install to default locations the libraries and Boost header files. On Unix
- systems the default install location is "/usr/local", and on Windows
- systems the default is "C:\Boost". Within those directories libraries
- are installed to the "lib" subdirectory, and headers to an "include/boost-1_31"
- subdirectory, the version will reflect the distribution you are installing.
-
-
-
5
-
Invoke the build system, specifying the toolset(s) you
- wish to use, to build and install. For example for GNU/GCC.
-
bjam "-sTOOLS=gcc" install
-
-
Or if you are interested only in the built libraries you can have them built
- and collected to a common directory without installation.
-
-
bjam "-sTOOLS=gcc" stage
-
-
-
-
-
The build and install system can be controlled through a set of options similar
- in style to GNU configure options. The options allow you to, among other
- things, change the install location, disable building of libraries, etc. You
- can see a summary of the available options by invoking "bjam --help".
- The full invocation takes the form:
-
-
bjam [options...] [install|stage]
-
-
-
-
- Action
-
-
-
-
none
-
Only builds the Boost libraries. This lets you do
- the first part of what the install action normally does without
- copying the built libraries to the install location.
-
-
-
install
-
Builds and installs Boost libraries and headers.
-
-
-
stage
-
Builds the Boost libraries and copies them into a
- common directory.
-
-
-
- Option
-
-
-
-
--help
-
Shows a short summary of the options and syntax of
- the command.
-
-
-
-sTOOLS=<toolsets>
-
The list of tools to compile with. Usually only one
- is needed.
-
-
-
--prefix=PREFIX
-
Install architecture independent files here.
- Default; C:\Boost on Win32.
- Default; /usr/local on Unix. Linux, etc.
Install source headers here. The Boost headers are
- installed in a version specific "boost-<version>" subdirectory
- in this directory.
- Default; PREFIX/include
-
-
-
--builddir=DIR
-
Build in this location instead of building within
- the distribution tree. This moves where the sources for the libraries are
- compiled to before they are installed. Recommended!
-
-
-
--stagedir=DIR
-
When staging only, with the "stage" action,
- copy to the given location.
- Default; ./stage
-
-
-
--without-<library>
-
Do not build, stage, or install the specified
- library.
-
-
-
--with-<library>
-
Build, stage, or install the specified library. This
- changes the default from trying to build all possible libraries, to only
- building the specified libraries.
-
-
-
--with-python-root[=PYTHON_ROOT]
-
Build Boost.Python libraries with the Python devel
- packages located at PYTHON_ROOT. The Boost.Python libraries are built
- only if the build can find the Python development package at this location.
- Default; C:\tools\python on Win32.
- Default; /usr/local on Unix, Linux, etc.
- Default; /usr on Cygwin.
-
-
-
--with-pydebug
-
Build Boost.Python libraries using the Python debug
- runtime. This builds an additional set of libraries for use with the debug
- version of Python. The regular versions of the Boost.Python libraries are also
- built.
Build Boost.Regex libraries with Unicode support
- provided by the
- ICU libraries. ICU must have been built with the same
- compiler that you are using to build Boost, and must have been built
- (or installed to) directory path.
- For example if you configured ICU with --prefix=/usr/local/icu/3.3, then use
- -sICU_PATH=/usr/local/icu/3.3. See
- the Boost.Regex
- installation documentation for more information.
-
-
-
-sNO_COMPRESSION=1
-
Build Boost.Iostreams without support for the compression
- filters which rely on the non-Boost libraries zlib and libbz2. If you use Windows,
- this option is enabled by default. If you use UNIX, the compression filters will likely
- work with no configuration, so this option should not be necessary. For full details see
- Boost.Iostreams Installation.
-
-
-
-
There are additional options as supported by
- Boost.Build and Boost.Jam.
- Of the additional options perhaps the most imporant is "-sBUILD=<features/variants>"
- which lets you override what is built by default. The "<features/variants>"
- value is a list, separated by spaces, of build requests. Features take the form
- of a tag and a value or values. And variants are single symbolic names for a
- collection of features. For example the default is to request "debug release
- <runtime-link>static/dynamic <threading>single/multi", in
- which "debug" and "release" are variants, and the rest
- features with two values each.
-
If you have some feedback about the build and install process please drop us a
- line at the Boost.Build mailing list.
- We are particularly interested if it works for your platform and if it there is
- anything that you feel could be done better.
-
Results
-
The results of building come in to forms: static libraries, and dynamic
- libraries. Depending on the platform the libraries produced have different
- names to accommodate the platform requirements. For a single Boost library the
- build with the default will produce eight different libraries. For example
- building the Boost.Datetime library on Unix type system it would produce:
-
-
- libboost_date_time-gcc-d-1_31.so
-
- libboost_date_time-gcc-mt-d-1_31.so
-
- libboost_date_time-gcc-1_31.so
-
- libboost_date_time-gcc-mt-1_31.so
-
- libboost_date_time-gcc-d-1_31.a
-
- libboost_date_time-gcc-mt-d-1_31.a
-
- libboost_date_time-gcc-1_31.a
-
- libboost_date_time-gcc-mt-1_31.a
-
-
-
-
-
-
-
-
- · Library Prefix
-
-
-
-
-
-
lib
-
-
-
-
- · Library Name
-
-
-
-
-
boost_date_time
-
-
-
-
- · Toolset
-
-
-
-
-
-
-
gcc
-
-
-
-
- · Threading
-
-
-
-
-
-
-
mt
-
-
-
-
- · Runtime
-
-
-
-
-
-
-
d
-
-
-
-
- · Boost Version
-
-
-
-
-
-
-
1_31
-
-
-
-
- · Library Type
-
-
-
-
-
.a
-
-
-
-
Library Prefix
-
The "lib" prefix on the libraries is a requirement on many platforms, like
- Unix, and on others like GCC running on Windows. The prefix is therefore added
- to all libraries on Unix type systems, and to static libraries on Windows. That
- is on Unix shared libraries and static libraries (object archives) are named
- respectively:
On Windows shared libraries do not have the prefix to differentiate the import
- libraries from static libraries. Consequently on Windows the libraries are
- named:
-
-
-
-
*.dll
-
Dynamic library version.
-
-
-
*.lib
-
-
Import library for the dll.
-
-
-
lib*.lib
-
-
Static library version.
-
-
-
-
Library Name
-
For Boost libraries the name has the "boost_" prefix to separate them
- from other libraries in your system.
-
Toolset
-
The toolset name is an abbreviation based on the compiler you are building
- with. The abbreviation is composed of a short, 2 to 4 characters, tag for the
- compiler and a version number of the compiler's major and minor revision (if
- available). For example if your toolset is "gcc-3_2_3" the toolset tag
- would be "gcc32". The toolset abbreviations used are as follows:
This tag indicates if the library is compiled with threading support. If
- threading is enabled "-mt" is added, otherwise nothing is added.
-
Runtime
-
This specifies the type of runtime the library was compiled against, and the
- type of code that is compiled. More commonly this encodes the ABI variation
- used in the code. For each feature of the runtime system and code compilation
- option a single letter is added to this tag.
-
-
-
Key
-
Feature
-
-
-
s
-
Static link to runtime.
-
-
-
g
-
Debug runtime.
-
-
-
y
-
Debug Python system.
-
-
-
d
-
Debug enabled code.
-
-
-
p
-
STLport runtime, instead of the vendor toolset runtime.
-
-
-
n
-
STLport runtime using the "native" IO streams instead of the STLport IO
- streams.
-
-
-
For example if you compile debug code for STLport using native IO streams, and
- statically link to the debug runtime the tag would be: "-sgdpn".
-
Boost Version
-
This is the short label for the version of the Boost Libraries. The major and
- minor version numbers are taken together separated by an underscore. For
- example version 1.31.0 would be tagged as "-1_31". The patch version
- number is not included because it is assumed that patch versions are upward
- compatible.
-
Library Type
-
The extension holds the type of library. This follows the platform
- requirements. On Windows this is ".dll" for shared libraries, and ".lib"
- for static libraries including import libraries. On Unix this is ".a" for
- static libraries (archives), and ".so" for shared libraries. For toolsets that
- support it in Unix they will also have a full version extension (for example ".so.1.31.0")
- with a symbolic link for the un-versioned library.
-
Automatic Linking on Windows
-
For most Boost libraries that have separate source, the correct build variant
- is linked against automatically when you include one of that library's header
- files. For this feature to work, your compiler must support the #pragma
- comment(lib, name) feature (Microsoft Visual C++, Intel C++,
- Metrowerks C++ , and Borland C++ all support this).
-
If you are linking to a dynamic runtime, then you can choose to link to either
- a static or a dynamic Boost library, the default is to do a static link.
- You can alter this for a specific library whatever by defining
- BOOST_WHATEVER_DYN_LINK to force Boost library whatever to be linked
- dynamically. Alternatively you can force all Boost libraries to dynamic
- link by defining BOOST_ALL_DYN_LINK.
-
This feature can be disabled for Boost library whatever by defining
- BOOST_WHATEVER_NO_LIB, or for all of Boost by defining BOOST_ALL_NO_LIB.
-
If you want to observe which libraries are being linked against then defining
- BOOST_LIB_DIAGNOSTIC will cause the auto-linking code to emit a #pragma
- message each time a library is selected for linking.
-
There are some Boost libraries (Boost.Test
- is one one special case), where automatic linking is not supported for
- technical reasons: please consult the documentation for each of the libraries
- you are using for more information, and the Boost.Config
- documentation for more information on configuration macros. The following
- table shows the current supported configurations, (Boost libraries not listed
- here consist of headers only):
Since all Python extensions are DLL's it makes sense to dynamic link to the
- Boost Python library by default (static linking is only really an option
- if you are embedding python).
-
-
-
Regex
-
Yes
-
Yes
-
static
-
Yes
-
-
-
-
Serialization
-
Yes
-
Yes
-
static
-
Yes
-
-
-
-
Signals
-
Yes
-
Yes
-
static
-
Yes
-
-
-
-
Test
-
Yes
-
No
-
static
-
No
-
Which library you link to depends upon which program entry point you define,
- rather than which Boost.Test features you use.
-
-
-
Thread
-
Partial
-
Yes
-
static (Visual C++), otherwise dynamic
-
Yes
-
For technical reasons static linking is supported on only one Windows compiler
- (Visual C++).
-
-
-
Wave
-
Yes
-
Yes
-
static
-
Yes
-
-
-
-
-
Additional Steps
-
Depending on your platform and configuration you may need to perform some
- additional configuration to get Boost to build and install.
- Configure the boost source code.
- This step should not be required on the vast majority of platforms, but if
- you're trying to build Boost on an untested or unsupported platform it may be
- necessary.
-
-
- If Boost.Build has problems detecting your Python installation it will print a
- short messages about how to configure for finding the Python installation. For
- more information, see these detailed
- instructions.
These instructions are intended to help you get started using the Boost
+ Libraries. This walks you through getting, building, and installing the
+ libraries. To summarize these are the steps to get Boost built and
+ installed:
The Boost Libraries are distributed through the SourceForge file
+ distribution system. Click here to
+ download releases from SourceForge. And
+ unpack the release to a convenient location.
+
+
+
+
The Boost release includes all of the libraries and other material from
+ the web site. It is available in ZIP, TAR.GZ, and TAR.BZ2 formats. Past
+ releases are also available.
It is also possible to download current
+ snapshots of work-in-progress from Boost's CVS
+ repository.
+
+
The .zip format is widely
+ supported by both free decoders and commercial compress/archive utilities.
+ If you don't already have a .zip file decoder, download one from the
+ Info-ZIP web site, which supplies
+ versions for many operating systems.
+
+
Text file line endings in the .zip file are as supplied by each library
+ developer. This works fine for Windows, but not for Unix/Linux.
+ The .tar.gz and .tar.bz2 files supply Unix/Linux friendly line endings.
The .tar.gz format is widely supported on Unix/Linux platforms. Some
+ Windows compress/archive utilities can read the format as well.
+ Because the gzip format compresses the archive as a single file rather than
+ compressing each file individually, the .tar.gz file is smaller that the
+ .zip file.
+
+
The .tar.bz2 format is becoming widely available on Unix/Linux platforms
+ and is built into many tar utilities. This format differs for the .tar.gz
+ format in the compression used, which is considerably better and therefore
+ creates smaller files.
+
+
Text file line endings in the .tar.gz and .tar.bz2 files have been
+ converted to newlines for ease of use on Unix/Linux platforms.
All Boost files, including the entire distribution tree including web
+ site HTML is maintained in a CVS repository. Command line, GUI, or browser
+ access is available.
+
+
Boost CVS access via command line or graphical clients
For those
+ who have CVS clients installed, the libraries are also available from the
+ public Boost CVS
+ repository. Free command line clients (often already installed on
+ Linux/Unix systems) are available for many systems, and free GUI clients
+ are available for Windows, Mac, and other systems.
+
+
See the much improved CVS documentation (Section
+ F) from SourceForge, which includes links to the home pages for various GUI
+ and command line clients.
+
+
The general procedure for command-line clients is something like
+ this:
+
+
+ cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/boost
+ login
+ [Hit <return> when it asks for a password]
+ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/boost
+ checkout boost
+ cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/boost
+ logout
+
Read the manual for your CVS client for further information.
+
+
This access is read-only; if you are a library author and wish to have
+ CVS write access, please contact one of the moderators.
For access to the CVS archive from any modern web
+ browser, you can also use the web
+ browser interface. Try one of the color diffs to see how a
+ file has changed over time. Note: this interface is only suitable
+ for viewing individual files and their revision histories.
+
+
Some of the Boost documentation is generated from BoostBook XML source stored in the CVS
+ repository, and will not appear directly in the CVS tree as readable HTML.
+ View a nightly build of the generated HTML on the
+ Nightly Generated Documentation page. Where generated HTML is missing
+ from the CVS tree, an attempt has been made to include redirection to this
+ nightly build, but if you are away from an internet connection you may want
+ to download the generated documentation archive from the aforementioned
+ page so you can browse those documents offline.
+
+
Preparation
+
+
The recommended way to build and install the Boost Libraries is to use
+ Boost.Build, the Boost
+ Build system. The rest of these instructions explain that use, but it is up
+ to you to use this method, or not. Note that some of the libraries also
+ include non Boost.Build makefiles and/or project files. But all include the
+ needed files for building with Boost.Build.
+
+
+
+
+ 2
+
+
The build system uses Boost.Jam, an extension of the
+ Perforce Jam
+ portable make replacement. The recommended way to get Boost.Jam
+ if you are using a Boost distribution is to
+ download a prebuilt executable from SourceForge. If a
+ prebuilt executable is not provided for your platform or you are using
+ Boost's sources in an unreleased state, it may be necessary to build bjam
+ from sources included in the Boost source tree. To install
+ Boost.Jam, copy the bjam executable to a location accessible
+ in your PATH.
Before using Boost.Build you will need to configure the compiler tools
+ you are using. The build system's toolsets are designed to work in either
+ of two ways:
+
+
+
The user sets up all of the environment for each toolset he wants to
+ use in the normal way. For example, for Microsoft VC++, ...VC98/Bin or
+ .../VC7/Bin is in the PATH environment variable, VCVARS32.BAT or
+ VSVARS32.BAT has been invoked, etc. For Metrowerks CodeWarrior, cwenv.bat
+ or equivalent has been called and ...Other Metrowerks Tools/Command Line
+ Tools is in the path. Many Unix operating systems come preconfigured this
+ way and require no user intervention.
+
+
+
The user doesn't want his environment cluttered with settings or has
+ nonstandard installations for some of his tools. Instead, he or she sets
+ variables which point to the toolset installation directories, either in
+ the command shell environment or on the bjam command-line.
+ These variables are used by the build system to locate the tools and
+ invoke the necessary setup. To set the variables on the bjam
+ command-line you use the "-s" option. For example:
+
+ bjam "-sGCC_ROOT_DIRECTORY=/usr/local/gcc-3.3.2"
+
+ Some variables, like the toolset TOOLS variable, can accept
+ multiple values separated by spaces. Others, like the path above, can
+ contain spaces. For such circumstances you should use quotes appropriate
+ for your command interpreter.
GNU GCC and associated tools in MinGW configuration (produces commercially
+ redistributable objects), using the STLport standard library
+ implementation
Microsoft Visual
+ C++ version 6 command-line tools, using the STLport standard library implementation.
+ NOTE; For version 7.x (the .NET series) use the vc7-stlport or
+ vc-7_1-stlport toolsets below.
Microsoft Visual
+ C++ command-line tools from Visual Studio .NET 2005.
+
+
+
+
Build and Install
+
+
The common build and install process is driven by the top-level build
+ file (Jamfile).
+
+
+
+
+ 4
+
+
+
First you need to change to the directory where you have the Boost
+ distribution you downloaded. For example:
+
+
+
chdir boost-1.31.0
+
+
+
+
+
+
The default build and install attempts to build all available libraries
+ and install to default locations the libraries and Boost header files. On
+ Unix systems the default install location is "/usr/local", and on
+ Windows systems the default is "C:\Boost". Within those
+ directories libraries are installed to the "lib" subdirectory, and
+ headers to an "include/boost-1_31" subdirectory, the version will
+ reflect the distribution you are installing.
+
+
+
+
+ 5
+
+
+ Invoke the build system, specifying the toolset(s) you wish to use, to build and install. For
+ example for GNU/GCC.
+
+
+
bjam "-sTOOLS=gcc" install
+
+
+
Or if you are interested only in the built libraries you can have
+ them built and collected to a common directory without
+ installation.
+
+
+
bjam "-sTOOLS=gcc" stage
+
+
+
+
+
+
The build and install system can be controlled through a set of options
+ similar in style to GNU configure options. The options allow you to, among
+ other things, change the install location, disable building of libraries,
+ etc. You can see a summary of the available options by invoking "bjam
+ --help". The full invocation takes the form:
+
+
+
bjam [options...] [install|stage]
+
+
+
+
+
Action
+
+
+
+
+
+
none
+
+
Only builds the Boost libraries. This
+ lets you do the first part of what the install action normally
+ does without copying the built libraries to the install location.
+
+
+
+
install
+
+
Builds and installs Boost libraries and
+ headers.
+
+
+
+
stage
+
+
Builds the Boost libraries and copies
+ them into a common directory.
+
+
+
+
Option
+
+
+
+
+
+
--help
+
+
Shows a short summary of the options and
+ syntax of the command.
+
+
+
+
+ -sTOOLS=<toolsets>
+
+
The list of tools to compile with.
+ Usually only one is needed.
+
+
+
+
--prefix=PREFIX
+
+
Install architecture independent files
+ here.
+ Default; C:\Boost on Win32.
+ Default; /usr/local on Unix. Linux, etc.
Install source headers here. The Boost
+ headers are installed in a version specific
+ "boost-<version>" subdirectory in this directory.
+ Default; PREFIX/include
+
+
+
+
--builddir=DIR
+
+
Build in this location instead of
+ building within the distribution tree. This moves where the sources for
+ the libraries are compiled to before they are installed.
+ Recommended!
+
+
+
+
--stagedir=DIR
+
+
When staging only, with the
+ "stage" action, copy to the given location.
+ Default; ./stage
+
+
+
+
+ --without-<library>
+
+
Do not build, stage, or install the
+ specified library.
+
+
+
+
+ --with-<library>
+
+
Build, stage, or install the specified
+ library. This changes the default from trying to build all possible
+ libraries, to only building the specified libraries.
+
+
+
+
+ --with-python-root[=PYTHON_ROOT]
+
+
Build Boost.Python libraries with the
+ Python devel packages located at PYTHON_ROOT. The Boost.Python
+ libraries are built only if the build can find the Python development
+ package at this location.
+ Default; C:\Python24 on Win32.
+ Default; /usr on Unix, Linux, Cygwin, etc.
+
+
+
+
+ --with-python-version[=2.4]
+
+
Build Boost.Python libraries with the
+ Python version indicated.
+ Default; 2.4.
+
+
+
+
--with-pydebug
+
+
Build Boost.Python libraries using the
+ Python debug runtime. This builds an additional set of libraries for
+ use with the debug version of Python. The regular versions of the
+ Boost.Python libraries are also built.
Build Boost.Regex libraries with Unicode
+ support provided by the ICU
+ libraries. ICU must have been built with the same compiler that you
+ are using to build Boost, and must have been built (or installed to)
+ directory path. For example if you configured ICU with
+ --prefix=/usr/local/icu/3.3, then use
+ -sICU_PATH=/usr/local/icu/3.3. See the Boost.Regex installation
+ documentation for more information.
+
+
+
+
-sNO_COMPRESSION=1
+
+
Build Boost.Iostreams without support for
+ the compression filters which rely on the non-Boost libraries zlib and
+ libbz2. If you use Windows, this option is enabled by default. If you
+ use UNIX, the compression filters will likely work with no
+ configuration, so this option should not be necessary. For full details
+ see Boost.Iostreams
+ Installation.
+
+
+
+
There are additional options as supported by Boost.Build and Boost.Jam. Of the additional
+ options perhaps the most imporant is "-sBUILD=<features/variants>"
+ which lets you override what is built by default. The
+ "<features/variants>" value is a list, separated by spaces,
+ of build requests. Features take the form of a tag and a value or values.
+ And variants are single symbolic names for a collection of features. For
+ example the default is to request "debug release
+ <runtime-link>static/dynamic <threading>single/multi", in
+ which "debug" and "release" are variants, and the rest
+ features with two values each.
+
+
If you have some feedback about the build and install process please
+ drop us a line at the Boost.Build
+ mailing list. We are particularly interested if it works for your
+ platform and if it there is anything that you feel could be done
+ better.
+
+
Results
+
+
The results of building come in to forms: static libraries, and dynamic
+ libraries. Depending on the platform the libraries produced have different
+ names to accommodate the platform requirements. For a single Boost library
+ the build with the default will produce eight different libraries. For
+ example building the Boost.Datetime library on Unix type system it would
+ produce:
+
+
+
libboost_date_time-gcc-d-1_31.so
+
+
libboost_date_time-gcc-mt-d-1_31.so
+
+
libboost_date_time-gcc-1_31.so
+
+
libboost_date_time-gcc-mt-1_31.so
+
+
libboost_date_time-gcc-d-1_31.a
+
+
libboost_date_time-gcc-mt-d-1_31.a
+
+
libboost_date_time-gcc-1_31.a
+
+
libboost_date_time-gcc-mt-1_31.a
+
+
+
+
+
+
+
+
· Library Prefix
+
+
+
+
+
+
+
+
+
lib
+
+
+
+
+
· Library Name
+
+
+
+
+
+
+
boost_date_time
+
+
+
+
+
· Toolset
+
+
+
+
+
+
+
-
+
+
gcc
+
+
+
+
+
· Threading
+
+
+
+
+
+
+
-
+
+
mt
+
+
+
+
+
· Runtime
+
+
+
+
+
+
+
-
+
+
d
+
+
+
+
+
· Boost Version
+
+
+
+
+
+
+
-
+
+
1_31
+
+
+
+
+
· Library Type
+
+
+
+
+
+
+
.a
+
+
+
+
+
+
Library Prefix
+
+
The "lib" prefix on the libraries is a requirement on many platforms,
+ like Unix, and on others like GCC running on Windows. The prefix is
+ therefore added to all libraries on Unix type systems, and to static
+ libraries on Windows. That is on Unix shared libraries and static libraries
+ (object archives) are named respectively:
+
+
+
lib*.so
+
+
lib*.a
+
+
+
On Windows shared libraries do not have the prefix to differentiate the
+ import libraries from static libraries. Consequently on Windows the
+ libraries are named:
+
+
+
+
*.dll
+
+
Dynamic library version.
+
+
+
+
*.lib
+
+
Import library for the dll.
+
+
+
+
lib*.lib
+
+
Static library version.
+
+
+
+
+
Library Name
+
+
For Boost libraries the name has the "boost_" prefix to
+ separate them from other libraries in your system.
+
+
Toolset
+
+
The toolset name is an abbreviation based on the compiler you are
+ building with. The abbreviation is composed of a short, 2 to 4 characters,
+ tag for the compiler and a version number of the compiler's major and minor
+ revision (if available). For example if your toolset is
+ "gcc-3_2_3" the toolset tag would be "gcc32". The toolset
+ abbreviations used are as follows:
This tag indicates if the library is compiled with threading support. If
+ threading is enabled "-mt" is added, otherwise nothing is
+ added.
+
+
Runtime
+
+
This specifies the type of runtime the library was compiled against, and
+ the type of code that is compiled. More commonly this encodes the ABI
+ variation used in the code. For each feature of the runtime system and code
+ compilation option a single letter is added to this tag.
+
+
+
+
Key
+
+
Feature
+
+
+
+
s
+
+
Static link to runtime.
+
+
+
+
g
+
+
Debug runtime.
+
+
+
+
y
+
+
Debug Python system.
+
+
+
+
d
+
+
Debug enabled code.
+
+
+
+
p
+
+
STLport runtime, instead of the vendor toolset runtime.
+
+
+
+
n
+
+
STLport runtime using the "native" IO streams instead of the
+ STLport IO streams.
+
+
+
+
For example if you compile debug code for STLport using native IO
+ streams, and statically link to the debug runtime the tag would be:
+ "-sgdpn".
+
+
Boost Version
+
+
This is the short label for the version of the Boost Libraries. The
+ major and minor version numbers are taken together separated by an
+ underscore. For example version 1.31.0 would be tagged as "-1_31".
+ For patch versions the patch number is also included, for example a version
+ of 1.31.1 would be tagged as "-1_31_1".
+
+
Library Type
+
+
The extension holds the type of library. This follows the platform
+ requirements. On Windows this is ".dll" for shared libraries, and
+ ".lib" for static libraries including import libraries. On Unix
+ this is ".a" for static libraries (archives), and ".so" for shared
+ libraries. For toolsets that support it in Unix they will also have a full
+ version extension (for example ".so.1.31.0") with a symbolic link
+ for the un-versioned library.
+
+
Automatic Linking on Windows
+
+
For most Boost libraries that have separate source, the correct build
+ variant is linked against automatically when you include one of that
+ library's header files. For this feature to work, your compiler must
+ support the #pragma comment(lib, name) feature (Microsoft
+ Visual C++, Intel C++, Metrowerks C++ , and Borland C++ all support
+ this).
+
+
If you are linking to a dynamic runtime, then you can choose to link to
+ either a static or a dynamic Boost library, the default is to do a static
+ link. You can alter this for a specific library whatever by
+ defining BOOST_WHATEVER_DYN_LINK to force Boost library whatever
+ to be linked dynamically. Alternatively you can force all Boost
+ libraries to dynamic link by defining BOOST_ALL_DYN_LINK.
+
+
This feature can be disabled for Boost library whatever by
+ defining BOOST_WHATEVER_NO_LIB, or for all of Boost by defining
+ BOOST_ALL_NO_LIB.
+
+
If you want to observe which libraries are being linked against then
+ defining BOOST_LIB_DIAGNOSTIC will cause the auto-linking code to emit a
+ #pragma message each time a library is selected for
+ linking.
+
+
There are some Boost libraries (Boost.Test is one one special case),
+ where automatic linking is not supported for technical reasons: please
+ consult the documentation for each of the libraries you are using for more
+ information, and the Boost.Config
+ documentation for more information on configuration macros. The
+ following table shows the current supported configurations, (Boost
+ libraries not listed here consist of headers only):
Since all Python extensions are DLL's it makes sense to dynamic
+ link to the Boost Python library by default (static linking is
+ only really an option if you are embedding python).
+
+
+
+
Regex
+
+
Yes
+
+
Yes
+
+
static
+
+
Yes
+
+
+
+
+
+
Serialization
+
+
Yes
+
+
Yes
+
+
static
+
+
Yes
+
+
+
+
+
+
Signals
+
+
Yes
+
+
Yes
+
+
static
+
+
Yes
+
+
+
+
+
+
Test
+
+
Yes
+
+
No
+
+
static
+
+
No
+
+
Which library you link to depends upon which program entry point
+ you define, rather than which Boost.Test features you use.
+
+
+
+
Thread
+
+
Partial
+
+
Yes
+
+
static (Visual C++), otherwise dynamic
+
+
Yes
+
+
For technical reasons static linking is supported on only one
+ Windows compiler (Visual C++).
+
+
+
+
Wave
+
+
Yes
+
+
Yes
+
+
static
+
+
Yes
+
+
+
+
+
+
+
Additional
+ Steps
+
+
Depending on your platform and configuration you may need to perform
+ some additional configuration to get Boost to build and install.
+
+
+
Configure the boost
+ source code. This step should not be required on the vast majority of
+ platforms, but if you're trying to build Boost on an untested or
+ unsupported platform it may be necessary.
+
+
+
If Boost.Build has problems detecting your Python installation it
+ will print a short messages about how to configure for finding the Python
+ installation. For more information, see these detailed instructions.
+
-
-
-
diff --git a/mailing_lists.htm b/mailing_lists.htm
index 3b96917..e997be7 100644
--- a/mailing_lists.htm
+++ b/mailing_lists.htm
@@ -199,10 +199,8 @@ div.admonition p.admonition-title {
is available at news://news.gmane.org/gmane.comp.lib.boost.devel.
-
For this list's members only, preliminary libraries under discussion are
- available from the YahooGroups Files section (formerly
- called the "vault").
+
Preliminary libraries under discussion are available from the Vault.
