Previous: Resources Home: Next: Header Organization and Compiled Binaries

Library Names and Organization

If your compiler supports auto-linking, such as Visual C++, then there is no need to understand the details of library binary naming.

However, if auto-linking is not supported by your compiler, then, in order to choose the right binary for your build configuration you need to know how Boost binaries are named.

Library Name Elements

Each library filename is composed of a common sequence of elements that describe how it was built. For example, libboost_regex-vc71-mt-d-x86-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. (1)

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: B2 option

s

linking statically to the C++ standard library and compiler runtime support libraries.

runtime-link=static

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. (2)

variant=debug

p

using the STLPort standard library rather than the default one supplied with your compiler.

stdlib=stlport

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, the tag would be: -sgdp . If none of the above apply, the ABI tag is omitted.

-x86

Architecture and address model tag: in the first letter, encodes the architecture as follows:

Key Architecture B2 option

x

x86-32, x86-64

architecture=x86

a

ARM

architecture=arm

i

IA-64

architecture=ia64

s

Sparc

architecture=sparc

m

MIPS/SGI

architecture=mips*

p

RS/6000 & PowerPC

architecture=power

The two digits following the letter encode the address model as follows:

Key Address model B2 option

32

32 bit

address-model=32

64

64 bit

address-model=64
-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.

Installed Library Names

When libraries are installed using the B2 app, the actual name can vary from the full name described above.

The --layout=<layout> option determines how the library name is handled, and the appropriate header locations so that multiple versions of Boost, or multiple compilers, can be used on the same system.

Layout Description Default on

versioned

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

Windows

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.

none

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.

Unix

The Boost Distribution

After installing Boost, this is the resulting directory structure, in the boost_1_82_0 root:

Root Level Lower Level Description

bin.v2

libs

Mainly contains the compiled binaries for those libraries that require compilation.

boost

library folders

All Boost header files

doc

A subset of all Boost library docs

libs

library folders

Tests, .cpps, docs, etc., by library

more

getting_started writingdoc

Policy, getting started, and Contributor Guide documentation

stage

lib

CMake files for each library

status

Boost-wide test suite

tools

tool folders

Utilities: B2, quickbook, bcp, etc.

b2.exe

Boost install app, and supporting files

index.htm

A copy of www.boost.org starts here

Footnotes

(1)

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.

(2)

These libraries were compiled without optimization or inlining, with full debug symbols enabled, and without #define NDEBUG. 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.

See Also