![]() |
|
You need to do two things in order to let your compiler and linker find Boost:
Depending on your platform and configuration you may need to 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.
Add the Boost root directory
to the compiler's #include <...> path. For most compilers that
means adding -Iboost-root-directory
to the command
line.
If you are using an IDE, refer to its documentation how to do this. For
example, in Visual Studio .NET 2003 you can add the path in the
Tools/Options/Projects/VC++ Directories
dialog.
If you plan to use the header-only libraries and didn't build anything, you are already done. Just look at the docs of the libraries you want to use. If you need help, ask in the Boost user's mailing list.
Add the lib
directory within the boost root directory to
the linker's library path. For most linkers that means adding
-Lboost-root-directory/lib
to the command line.
If you are using an IDE, refer to its documentation how to do this. For
example, in Visual Studio .NET 2003 you can add the path in the
Tools/Options/Projects/VC++ Directories
dialog.
The results of building come in two 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. (If you
tell them where the libraries are located, most Windows linkers will
automatically select the correct library as explained
below.)
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
|
||||||||||||
lib |
|
|||||||||||
boost_date_time |
|
|||||||||||
- |
gcc |
|
||||||||||
- |
mt |
|
||||||||||
- |
d |
|
||||||||||
- |
1_31 |
|
||||||||||
.a |
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. |
Boost library file names all contain the "boost_
" prefix
to distinguish them from other libraries in your system.
The toolset name is an abbreviation based on the compiler you are building
with. The abbreviation is composed of a two- to four-character compiler
tag and a version number of the compiler's major and minor revision (if
available). For example if your toolset is "gcc-3_2_3
" the toolset tag
would be "gcc32
". The toolset abbreviations used are as follows:
TOOLS Name | Abbreviation |
borland |
bcb |
como |
como |
como-win32 |
como |
cw |
cw |
darwin |
osx |
dmc |
dmc |
dmc-stlport |
dmc |
edg |
edg |
gcc |
gcc |
gcc-stlport |
gcc |
gcc-nocygwin |
gcc |
intel-linux |
il |
intel-win32 |
iw |
kcc |
kcc |
kylix |
bck |
mingw |
mgw |
mingw-stlport |
mgw |
mipspro |
mp |
msvc |
vc |
msvc-stlport |
vc |
sunpro |
sw |
tru64cxx |
tru |
tru64cxx65 |
tru |
vacpp |
xlc |
vc7 |
vc |
vc7-stlport |
vc |
vc-7_1 |
vc |
vc-7_1-stlport |
vc |
Others | The first part of the toolset name. |
This tag indicates whether the library is compiled with threading support.
If threading is enabled "-mt
" is added, otherwise nothing is
added.
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
".
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.
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.
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):
Library | Static Link | Dynamic Link | Default linkage | Automatic library selection | Comments |
Date-Time | Yes | Yes | static | Yes | |
Filesystem | Yes |
Yes |
static | Yes | |
Graph | Yes | No | static | No | The separate Graph library source is needed only when reading an AT&T graphviz file. |
Program Options | Yes | Yes | static | Yes | |
Python | Yes | Yes | dynamic | No | 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 | |
Serialisation | Yes | No | static | No | Automatic linking support will be introduced in a future release. |
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 | dynamic | Yes | For technical reasons static linking is supported on only one Windows compiler (Visual C++). |
Now you need to look at the docs!
If you need help, ask in the Boost user's
mailing list.
Revised 8 November, 2004
Copyright © Rene Rivera 2003.
Copyright © Jens Maurer 2001.
Copyright © John Maddock 2004.
Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at www.boost.org/LICENSE_1_0.txt)