Build Features in CMake

Different compilation and linking flags affect how source code and libraries are compiled. Boost's build system abstracts some of these properties into specific features of the build, which indicate (at a high level) what options are being used, e.g., multi-threaded, release-mode, shared libraries, etc. Each feature brings with it certain compilation options (which vary from one compiler to the next) that need to be used when building that variant. For example, on Unix systems, one often must link against the pthread library for multi-threaded programs and libraries, which requires the addition of the -lpthread flag to the link line. The features feature of the build system encapsulates this knowledge.

A library built with a given set of features is called a library variant. For example, we could have a multi-threaded release variant of a shared library, which would be built with all of the options needed to support multi-threading, optimization, elimination of debugging symbols, and for building a shared library. Each variant of a library is given a unique name based on the features in that variant, so that one can readily identify the library, for example, libboost_signals-gcc40-mt-d.so is the multi-threaded, debug version of the shared library for Boost.Signals on a typical Linux system. The Boost Getting Started guide describes the library naming conventions used for the variants.

This page describes each of the featues supported by Boost.Build, and the default variants that are built for each platform.

Features

The CMake-based build system for Boost supports the following features.

STATIC

The STATIC feature identifies static builds of libraries, i.e., a .lib (library) file on Microsoft Windows or a .a (archive) file on Unix systems.

SHARED

The SHARED feature identifies shared builds of libraries, i.e., a .dll (dynamically linked library) file on Microsoft Windows or a .so(shared object) or .dylib (dynamic library) file on Unix systems. In some cases, SHARED variants actually refer to "modules", which are a special kind of shared library on some systems (e.g., Mac OS X).

DEBUG

The DEBUG feature identifies builds of libraries that retain complete debugging information and prohibit optimization, making these builds far easier to use for debugging programs.

RELEASE

The RELEASE feature identifies builds of libraries that use full optimization and eliminate extraneous information such as debug symbols, resulting in builds of libraries that are typically much smaller than (and execute faster than) their debug library counterparts.

SINGLE_THREADED

The SINGLE_THREADED feature identifies builds of libraries that assume that the program using them is single-threaded. These libraries typically avoid costly atomic operations or locks, and make use of no multi-threaded features.

MULTI_THREADED

The MULTI_THREADED feature identifies builds of libraries that assume that the program using them is multi-threaded. These libraries may introduce additional code (relative to their single-threaded variants) that improves the behavior of the library in a multi-threade context, often at the cost of single-thread performance.

STATIC_RUNTIME

The STATIC_RUNTIME feature identifies builds that link against the C and C++ run-time libraries statically, which directly includes the code from those run-time libraries into the Boost library or executable.

DYNAMIC_RUNTIME

The DYNAMIC_RUNTIME feature identifies builds that link against the dynamic C and C++ run-time libraries.

Compilation and Linker Options

For each feature, the Boost build system defines three macros providing compilation flags, linking flags, and extra libraries to link against when using that feature. These flags are automatically added to the build commands for variants using that feature. The particular flags and libraries are described by the following global variables:

feature_COMPILE_FLAGS

A string containing extra flags that will be added to the compile line, including macro definitions and compiler-specific flags needed to enable this particular feature.

feature_LINK_FLAGS

A string containing extra flags that will be added to the beginning of the link line. Note that these flags should not contain extra libraries that one needs to link against. Those should go into feature_LINK_LIBS.

feature_LINK_LIBS

A CMake list containing the names of additional libraries that will be linked into libraries and executables that require this feature. The elements in this list should name the library (e.g., pthread) rather than providing the link command itself (e.g., -lpthread), so that linking will be more portable.

Each of these variables can be expanded for any feature, e.g., MULTI_THREADED_LINK_LIBS contains libraries that multi-threaded variants should link against.

All of the flags provided for each feature are typically detected by the Boost CMake configuration module in ​tools/build/CMake/BoostConfig.cmake.

Default Variants

By default, Boost's build system will build every permutation of libraries in the space (STATIC or SHARED) x (DEBUG or RELEASE) x (SINGLE_THREADED or MULTI_THREADED), resulting in 8 different copies of each library. On Windows, where the distinction between static and dynamic run-time libraries is very important, the default build also creates permutations with (STATIC_RUNTIME or DYNAMIC_RUNTIME). Certain non-sensical combinations of libraries will automatically be eliminated, e.g., it does not generally make sense to create a shared library that links against the static C and C++ run-time libraries. However, this still means that the default build creates between 8 and 12 different variants of each Boost library.

Users who only need a few variants of each library can change which variants of Boost libraries are build by default using various configuration options. For each feature, CMake's configuration will contain an option BUILD_feature. When the feature is ON, the build system will produce variants with that feature. When the feature is OFF, the build system will suppress variants with that feature. For example, toggling BUILD_DEBUG to OFF will inhibit the creation of the debug variants, drastically improving overall build times.