This repository hosts the tools/cmake
Boost submodule, containing
the CMake support infrastructure for Boost.
Note that the officially supported way to build Boost remains
with b2
.
The first thing you need to know is that the
official Boost releases
can't be built with CMake. Even though the Boost Github repository
contains a CMakeLists.txt
file, it's removed from the release.
That's because the file and directory layout of Boost releases,
for historical reasons, has all the Boost header files copied
into a single boost/
directory. These headers are then removed
from the individual library include/
directories. The CMake
support infrastructure expects the headers to remain in their
respective libs/<libname>/include
directories, and therefore
does not work on a release archive.
To build Boost with CMake, you will need either a Git clone
of Boost
(git clone --recurse-submodules https://github.com/boostorg/boost
)
or the alternative archives
available on Github.
Once you have cloned, or downloaded and extracted, Boost, use the usual procedure of
mkdir __build
cd __build
cmake ..
cmake --build .
to build it with CMake. To install it, add
cmake --build . --target install
Under Windows (when using the Visual Studio generator), you can
control whether Debug or Release variants are built by adding
--config Debug
or --config Release
to the cmake --build
lines:
cmake --build . --config Debug
cmake --build . --target install --config Debug
The default is Debug. You can build and
install both Debug and Release at the same time, by running the
respective cmake --build
line twice, once per --config
:
cmake --build . --target install --config Debug
cmake --build . --target install --config Release
The following variables are supported and can be set either from
the command line as cmake -DVARIABLE=VALUE ..
, or via ccmake
or cmake-gui
:
-
BOOST_INCLUDE_LIBRARIES
A semicolon-separated list of libraries to include into the build (and installation.) Defaults to empty, which means "all libraries". Example:
filesystem;regex
. -
BOOST_EXCLUDE_LIBRARIES
A semicolon-separated list of libraries to exclude from the build (and installation.) This is useful if a library causes an error in the CMake configure phase.
-
BOOST_ENABLE_MPI
Set to ON if Boost libraries depending on MPI should be built.
-
BOOST_ENABLE_PYTHON
Set to ON if Boost libraries depending on Python should be built.
-
For single-configuration generators such as Makefile and Ninja (the typical case under POSIX operating systems), controls the build variant (Debug or Release.) The default when building Boost is set to Release.
For multi-configuration generators such as the Visual Studio generators,
CMAKE_BUILD_TYPE
is ignored; the desired configuration is set at build (or install) time, with the--config
option tocmake --build
andcmake --install
.For more information, see the CMake documentation on build configurations.
-
A standard CMake variable that determines where the headers and libraries should be installed. The default when building Boost is set to
C:/Boost
under Windows,/usr/local
otherwise. -
Directory in which to install the header files. Can be relative to
CMAKE_INSTALL_PREFIX
. Defaultinclude
. -
Directory in which to install the binary artifacts (executables and Windows DLLs.) Can be relative to
CMAKE_INSTALL_PREFIX
. Defaultbin
. -
Directory in which to install the compiled libraries. Can be relative to
CMAKE_INSTALL_PREFIX
. Defaultlib
. -
BOOST_INSTALL_CMAKEDIR
Directory in which to install the CMake configuration files. Default
lib/cmake
. -
BOOST_INSTALL_LAYOUT
Boost installation layout. Can be one of
system
,tagged
, orversioned
. The default isversioned
under Windows, andsystem
otherwise.versioned
produces library names of the formlibboost_timer-vc143-mt-gd-x64-1_82.lib
, containing the toolset (compiler) name and version, encoded build settings, and the Boost version. (The extension is.lib
under Windows,.a
or.so
under Linux, and.a
or.dylib
under macOS.)tagged
produces library names of the formlibboost_timer-mt-gd-x64.lib
; only the build settings are encoded in the name, the toolset and the Boost version are not.system
produces library names of the formlibboost_timer.lib
(orlibboost_timer.a
,libboost_timer.so
,libboost_timer.dylib
.) -
BOOST_INSTALL_INCLUDE_SUBDIR
When
BOOST_INSTALL_LAYOUT
isversioned
, headers are installed in a subdirectory ofCMAKE_INSTALL_INCLUDEDIR
(to enable several Boost releases being installed at the same time.) The default for release e.g. 1.81 is/boost-1_81
.) -
BOOST_RUNTIME_LINK
Whether to use the static or the shared C++ runtime libraries under Microsoft Visual C++ and compatible compilers. (The available values are
shared
andstatic
and the default isshared
.) -
A standard CMake variable; when ON, tests are configured and built. Defaults to OFF.
-
A standard CMake variable that determines whether to build shared or static libraries. Defaults to OFF.
-
BOOST_STAGEDIR
The directory in which to place the build outputs. Defaults to the
stage
subdirectory of the current CMake binary directory.The standard CMake variables
CMAKE_RUNTIME_OUTPUT_DIRECTORY
,CMAKE_LIBRARY_OUTPUT_DIRECTORY
, andCMAKE_ARCHIVE_OUTPUT_DIRECTORY
are set by default to${BOOST_STAGEDIR}/bin
,${BOOST_STAGEDIR}/lib
, and${BOOST_STAGEDIR}/lib
, respectively. -
C++ symbol visibility (one of
default
,hidden
,protected
,internal
). The default is set tohidden
to matchb2
. -
C symbol visibility (one of
default
,hidden
,protected
,internal
). The default is set tohidden
to matchb2
. -
CMAKE_VISIBILITY_INLINES_HIDDEN
Whether inline functions should have hidden visibility. The default is set to
ON
to matchb2
.
Some Boost libraries provide their own configuration variables, some of which are given below.
-
BOOST_CONTEXT_BINARY_FORMAT
Allowed values are
elf
,mach-o
,pe
,xcoff
. The default is autodetected from the platform. -
BOOST_CONTEXT_ABI
Allowed values are
aapcs
,eabi
,ms
,n32
,n64
,o32
,o64
,sysv
,x32
. The default is autodetected from the platform. -
BOOST_CONTEXT_ARCHITECTURE
Allowed values are
arm
,arm64
,loongarch64
,mips32
,mips64
,ppc32
,ppc64
,riscv64
,s390x
,i386
,x86_64
,combined
. The default is autodetected from the platform. -
BOOST_CONTEXT_ASSEMBLER
Allowed values are
masm
,gas
,armasm
. The default is autodetected from the platform. -
BOOST_CONTEXT_ASM_SUFFIX
Allowed values are
.asm
and.S
. The default is autodetected from the platform. -
BOOST_CONTEXT_IMPLEMENTATION
Allowed values are
fcontext
,ucontext
,winfib
. Defaults tofcontext
.
-
BOOST_FIBER_NUMA_TARGET_OS
Target OS for the Fiber NUMA support. Can be
aix
,freebsd
,hpux
,linux
,solaris
,windows
,none
. Defaults towindows
under Windows,linux
under Linux, otherwisenone
.
-
BOOST_IOSTREAMS_ENABLE_ZLIB
When ON, enables ZLib support. Defaults to ON when
zlib
is found, OFF otherwise. -
BOOST_IOSTREAMS_ENABLE_BZIP2
When ON, enables BZip2 support. Defaults to ON when
libbzip2
is found, OFF otherwise. -
BOOST_IOSTREAMS_ENABLE_LZMA
When ON, enables LZMA support. Defaults to ON when
liblzma
is found, OFF otherwise. -
BOOST_IOSTREAMS_ENABLE_ZSTD
When ON, enables Zstd support. Defaults to ON when
libzstd
is found, OFF otherwise.
-
BOOST_LOCALE_ENABLE_ICU
When ON, enables the ICU backend. Defaults to ON when ICU is found, OFF otherwise.
-
BOOST_LOCALE_ENABLE_ICONV
When ON, enables the Iconv backend. Defaults to ON when
iconv
is found, OFF otherwise. -
BOOST_LOCALE_ENABLE_POSIX
When ON, enables the POSIX backend. Defaults to ON on POSIX systems, OFF otherwise.
-
BOOST_LOCALE_ENABLE_STD
When ON, enables the
std::locale
backend. Defaults to ON. -
BOOST_LOCALE_ENABLE_WINAPI
When ON, enables the Windows API backend. Defaults to ON under Windows, OFF otherwise.
-
BOOST_STACKTRACE_ENABLE_NOOP
When ON, builds the
boost_stacktrace_noop
library variant. Defaults to ON. -
BOOST_STACKTRACE_ENABLE_BACKTRACE
When ON, builds the
boost_stacktrace_backtrace
library variant. Defaults to ON whenlibbacktrace
is found, OFF otherwise. -
BOOST_STACKTRACE_ENABLE_ADDR2LINE
When ON, builds the
boost_stacktrace_addr2line
library variant. Defaults to ON, except on Windows. -
BOOST_STACKTRACE_ENABLE_BASIC
When ON, builds the
boost_stacktrace_basic
library variant. Defaults to ON. -
BOOST_STACKTRACE_ENABLE_WINDBG
When ON, builds the
boost_stacktrace_windbg
library variant. Defaults to ON under Windows when WinDbg support is autodetected, otherwise OFF. -
BOOST_STACKTRACE_ENABLE_WINDBG_CACHED
When ON, builds the
boost_stacktrace_windbg_cached
library variant. Defaults to ON under Windows when WinDbg support is autodetected and whenthread_local
is supported, otherwise OFF.
-
BOOST_THREAD_THREADAPI
Threading API,
pthread
orwin32
. Defaults towin32
under Windows,pthread
otherwise.
To run the Boost tests with CMake/CTest, first configure as before, but with
BUILD_TESTING=ON
:
mkdir __build
cd __build
cmake -DBUILD_TESTING=ON ..
then build the tests:
cmake --build . --target tests
and then run them:
ctest --output-on-failure --no-tests=error
Under Windows, you need to select a configuration (Debug or Release):
cmake --build . --target tests --config Debug
ctest --output-on-failure --no-tests=error -C Debug
To only build the tests for a specific library, and not the entire Boost,
use BOOST_INCLUDE_LIBRARIES
:
cmake -DBUILD_TESTING=ON -DBOOST_INCLUDE_LIBRARIES=timer ..
To build and run in parallel using more than one core, use the -j
option:
cmake --build . --target tests -j 16
ctest --output-on-failure --no-tests=error -j 16
A convenience target check
is provided that first builds the tests and
then invokes ctest
:
cmake --build . --target check
but it doesn't support running the tests in parallel.
Normally, a Boost installation is used from CMake by means of
find_package(Boost)
. However, up to and including release 1.81.0, installing
Boost with CMake did not deploy the necessary CMake configuration file for
the Boost
package, so find_package(Boost)
did not work. (It also did
not provide the Boost::boost
and Boost::headers
targets, on which many
existing CMakeLists.txt
files rely.)
Instead, the individual Boost libraries needed to be referenced as in
find_package(boost_filesystem 1.81 REQUIRED)
This has been rectified in Boost 1.82, which installs an umbrella CMake
configuration file for the Boost package (BoostConfig.cmake
) and
provides the Boost::boost
and Boost::headers
compatibility targets.
Assuming that your project already has a copy of Boost in a subdirectory, either deployed as a Git submodule or extracted manually by the user as a prerequisite, using it is relatively straightforward:
add_subdirectory(deps/boost)
However, as-is, this will configure all Boost libraries and build them by default regardless of whether they are used. It's better to use
add_subdirectory(deps/boost EXCLUDE_FROM_ALL)
so that only the libraries that are referenced by the project are built,
and it's even better to set BOOST_INCLUDE_LIBRARIES
before the
add_subdirectory
call to a list of the Boost libraries that need to be
configured:
set(BOOST_INCLUDE_LIBRARIES filesystem regex)
add_subdirectory(deps/boost EXCLUDE_FROM_ALL)
Boost is a large dependency, and sometimes a project only needs a single
library. It's possible to use add_subdirectory
with individual Boost
libraries (https://github.com/boostorg/<libname>
) instead of the entire
superproject or release archive. However, since Boost libraries depend on
each other quite extensively, all library dependencies also need to be
added (again via add_subdirectory
.)
As an example, this is how one would use Boost.Timer in this manner:
set(libs
timer
# Primary dependencies
chrono
config
core
io
predef
system
throw_exception
# Secondary dependencies
assert
integer
move
mpl
ratio
static_assert
type_traits
typeof
utility
winapi
variant2
preprocessor
rational
mp11
)
foreach(lib IN LISTS libs)
add_subdirectory(deps/boost/${lib} EXCLUDE_FROM_ALL)
endforeach()
assuming that the individual libraries have been placed in subdirectories
of deps/boost
.
(The list of required dependencies above has been produced by running
boostdep --brief timer
. See
the documentation of Boostdep.)
FetchContent
downloads the required dependencies as part of CMake's
project configuration phase. While this is convenient because it doesn't
require the user to acquire the dependencies beforehand, in the case of
Boost it involves an 87 MB download, so you should carefully weigh the
pros and cons of this approach.
That said, here's how one would use Boost with FetchContent
:
include(FetchContent)
FetchContent_Declare(
Boost
URL https://github.com/boostorg/boost/releases/download/boost-1.81.0/boost-1.81.0.tar.xz
URL_MD5 6cf0cdd797bca685910d527ae3c08cb3
DOWNLOAD_EXTRACT_TIMESTAMP ON
)
FetchContent_MakeAvailable(Boost)
This has the same drawback as the simple add_subdirectory
call -- all
Boost libraries are configured and built, even if not used by the project.
To configure only some Boost libraries, set BOOST_INCLUDE_LIBRARIES
before the FetchContent_MakeAvailable
call:
set(BOOST_INCLUDE_LIBRARIES timer filesystem regex)
FetchContent_MakeAvailable(Boost)
To perform the add_subdirectory
call with the EXCLUDE_FROM_ALL
option,
replace FetchContent_MakeAvailable(Boost)
with this:
FetchContent_GetProperties(Boost)
if(NOT Boost_POPULATED)
message(STATUS "Fetching Boost")
FetchContent_Populate(Boost)
message(STATUS "Configuring Boost")
add_subdirectory(${Boost_SOURCE_DIR} ${Boost_BINARY_DIR} EXCLUDE_FROM_ALL)
endif()