boost.png (6897 bytes)

Home
Libraries
People
FAQ
More

Telling your compiler and linker about Boost

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

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.

Point your linker to the libraries

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:

  1. libboost_date_time-gcc-d-1_31.so
  2. libboost_date_time-gcc-mt-d-1_31.so
  3. libboost_date_time-gcc-1_31.so
  4. libboost_date_time-gcc-mt-1_31.so
  5. libboost_date_time-gcc-d-1_31.a
  6. libboost_date_time-gcc-mt-d-1_31.a
  7. libboost_date_time-gcc-1_31.a
  8. 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

Boost library file names all contain the "boost_" prefix to distinguish 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 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.

Threading

This tag indicates whether 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):

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)