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, whileSHARED_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
andDEPENDS
.
- 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". LikeLINK_LIBS
, this option states that all variants of the library being built will link against the stated libraries. UnlikeLINK_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 libraryDEPENDS
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 thePYTHON_DEBUG
feature.
Example
The Boost.Thread library binary is built using the following invocation of the boost_add_library
macro. The options passed to the macro indicate that CMake should define BOOST_THREAD_BUILD_DLL
to 1 when building shared libraries and BOOST_THREAD_BUILD_LIB
to 1 when building static libraries. The NO_SINGLE_THREADED
option inhibits creation of any single-threaded variants of the library (which obviously would not make sense for a threading library!). The flags needed to compile the multi-threaded variants are automatically added.
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 )
This example is from libs/thread/src/CMakeLists.txt.
Where Defined
This macro is defined in the Boost Core module in tools/build/CMake/BoostCore.cmake