CMake Macro Reference: boost_add_library

This macro creates a new Boost library target that generates a compiled library (.a, .lib, .dll, .so, etc) from source files. This routine will actually build several different variants of the same library, with different compilation options, as determined by the set of "default" library variants.

boost_add_library(libname
                  source1 source2 ...
                  [COMPILE_FLAGS compileflags]
                  [feature_COMPILE_FLAGS compileflags]
                  [LINK_FLAGS linkflags]
                  [feature_LINK_FLAGS linkflags]
                  [LINK_LIBS linklibs]
                  [feature_LINK_LIBS linklibs]
                  [DEPENDS libdepend1 libdepend2 ...]
                  [STATIC_TAG]
                  [MODULE]
                  [NOT_feature]
                  [EXTRA_VARIANTS variant1 variant2 ...])

where libname is the name of Boost library binary (e.g., "boost_regex") and source1, source2, etc. are the source files used to build the library, e.g., cregex.cpp.

This macro has a variety of options that affect its behavior. In several cases, we use the placeholder "feature" in the option name to indicate that there are actually several different kinds of options, each referring to a different build feature, e.g., shared libraries, multi-threaded, debug build, etc. For a complete listing of these features, please refer to the page on CMake Build Features.

The options that affect this macro's behavior are:

COMPILE_FLAGS

Provides additional compilation flags that will be used when building all variants of the library. For example, one might want to add "-DBOOST_SIGNALS_NO_LIB=1" through this option (which turns off auto-linking for the Signals library while building it).

feature_COMPILE_FLAGS

Provides additional compilation flags that will be used only when building variants of the library that include the given feature. For example, MULTI_THREADED_COMPILE_FLAGS are additional flags that will be used when building a multi-threaded variant, while SHARED_COMPILE_FLAGS will be used when building a shared library (as opposed to a static library).

LINK_FLAGS

Provides additional flags that will be passed to the linker when linking each variant of the library. This option should not be used to link in additional libraries; see LINK_LIBS and DEPENDS.

feature_LINK_FLAGS

Provides additional flags that will be passed to the linker when building variants of the library that contain a specific feature, e.g., MULTI_THREADED_LINK_FLAGS. This option should not be used to link in additional libraries; see feature_LINK_LIBS.

LINK_LIBS

Provides additional libraries against which each of the library variants will be linked. For example, one might provide "expat" as options to LINK_LIBS, to state that each of the library variants will link against the expat library binary. Use LINK_LIBS for libraries external to Boost; for Boost libraries, use DEPENDS.

feature_LINK_LIBS

Provides additional libraries for specific variants of the library to link against. For example, MULTI_THREADED_LINK_LIBS provides extra libraries to link into multi-threaded variants of the library.

DEPENDS

States that this Boost libraries depends on and links against another Boost library. The arguments to DEPENDS should be the unversioned name of the Boost library, such as "boost_filesystem". Like LINK_LIBS, this option states that all variants of the library being built will link against the stated libraries. Unlike LINK_LIBS, however, DEPENDS takes particular library variants into account, always linking the variant of one Boost library against the same variant of the other Boost library. For example, if the boost_mpi_python library DEPENDS on boost_python, multi-threaded variants of boost_mpi_python will link against multi-threaded variants of boost_python.

STATIC_TAG

States that the name of static library variants on Unix need to be named differently from shared library variants. This particular option should only be used in rare cases where the static and shared library variants are incompatible, such that linking against the shared library rather than the static library will cause features. When this option is provided, static libraries on Unix variants will have "-s" appended to their names. Note: we hope that this is a temporary solution. At present, it is only used by the Test library.

MODULE

This option states that, when building a shared library, the shared library should be built as a module rather than a normal shared library. Modules have special meaning an behavior on some platforms, such as Mac OS X.

NOT_feature

States that library variants containing a particular feature should not be built. For example, passing NOT_SINGLE_THREADED suppresses generation of single-threaded variants of this library.

EXTRA_VARIANTS

Specifies that extra variants of this library should be built, based on the features listed. Each "variant" is a colon-separated list of features. For example, passing EXTRA_VARIANTS "PYTHON_NODEBUG:PYTHON_DEBUG" will result in the creation of an extra set of library variants, some with the PYTHON_NODEBUG feature and some with the PYTHON_DEBUG feature.

Example

boost_add_library(
  boost_thread
  barrier.cpp condition.cpp exceptions.cpp mutex.cpp once.cpp 
  recursive_mutex.cpp thread.cpp tss_hooks.cpp tss_dll.cpp tss_pe.cpp 
  tss.cpp xtime.cpp
  SHARED_COMPILE_FLAGS "-DBOOST_THREAD_BUILD_DLL=1"
  STATIC_COMPILE_FLAGS "-DBOOST_THREAD_BUILD_LIB=1"
  NO_SINGLE_THREADED
)