The easiest way to add CMake support to a header-only Boost library is
to generate a CMakeLists.txt file with
Boostdep
using the command boostdep --cmake <libname>, where <libname> is the
name of the repository (or the directory name).
For example, a CMakeLists.txt file for Boost.Core can be generated with
boostdep --cmake core, and the result will be, as of this writing,
# Generated by `boostdep --cmake core`
# Copyright 2020 Peter Dimov
# Distributed under the Boost Software License, Version 1.0.
# https://www.boost.org/LICENSE_1_0.txt
cmake_minimum_required(VERSION 3.5...3.16)
project(boost_core VERSION "${BOOST_SUPERPROJECT_VERSION}" LANGUAGES CXX)
add_library(boost_core INTERFACE)
add_library(Boost::core ALIAS boost_core)
target_include_directories(boost_core INTERFACE include)
target_link_libraries(boost_core
INTERFACE
Boost::assert
Boost::config
Boost::static_assert
)
if(BUILD_TESTING AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/test/CMakeLists.txt")
add_subdirectory(test)
endif()
Most header-only libraries require no modification to this boostdep output.
You are not required to use this exact file, but if you can, there are benefits for doing so:
- You can regenerate the file at any time, to pick up style changes as the Boost CMake infrastructure evolves and Boostdep is updated to match;
- Boostdep computes the library dependencies automatically (as this is its primary purpose as a tool), and if you make changes to the library that cause its dependencies to change, a simple regeneration can keep the list up to date;
- You can add a CI job that compares the output of Boostdep to your current CMakeLists.txt file, which will inform you if the file needs to be regenerated.
Even if you decide to make changes to your CMakeLists.txt file, the
generated output provides a useful starting point. Its contents are explained
below.
cmake_minimum_required(VERSION 3.5...3.16)
This directive sets the minimum required version of CMake and must be the first thing in it. If CMake is older than 3.5, the result will be a fatal error at configure time, and inability to proceed with building.
In addition, this number changes the behavior of newer CMake versions to attempt to be compatible with the stated version. If this only said
cmake_minimum_required(VERSION 3.5)
a newer version of CMake would have emulated version 3.5. The additional
...3.16 suffix, however, requests newer versions to emulate 3.16 instead.
This is typically the latest version of CMake with which the CMakeLists.txt
file has been tested. If you make changes to the file for other reasons, you
may want to update the directive to, say,
cmake_minimum_required(VERSION 3.5...3.20)
You should avoid increasing the minimal CMake requirement above the Boost
minimum, which is at present tentatively and conservatively set to 3.5, but
will likely be increased in the near future. If you use a higher minimum,
configuring Boost will fail with earlier CMake versions, even if the user
is not interested in your library. He will then be forced to manually exclude
your library from the build with -DBOOST_EXCLUDE_LIBRARIES, which is not
an ideal user experience.
project(boost_core VERSION "${BOOST_SUPERPROJECT_VERSION}" LANGUAGES CXX)
The project declaration must generally be preceded only by the above version requirement directive, and sets the project name, the project version, and the languages (C, C++) that the source files will use.
Boost projects by convention are named boost_libname, in lowercase,
as in the above. (Libraries in numeric such as numeric/conversion
use an underscore in place of the slash: boost_numeric_conversion.)
The version is set to match the variable BOOST_SUPERPROJECT_VERSION,
which the Boost superproject CMakeLists.txt file sets to the current
Boost version (such as 1.77.0.)
If your library is included directly in a user project with
add_subdirectory, BOOST_SUPERPROJECT_VERSION will not be set and
the project version will be empty, as if it weren't given:
project(boost_core LANGUAGES CXX)
This is usually what one wants. Since manually maintaining a version
is time consuming and doesn't bring much, most libraries that do
include one fail to maintain it properly. It's better to leave it empty;
the version is of no significance in an add_subdirectory workflow.
The LANGUAGES portion should be left at the default CXX, which
enables the C++ language. If removed, CMake will configure both C and
C++. C is only needed if the library has C source files, which a
header-only library does not have.
add_library(boost_core INTERFACE)
The first add_library declares the library target, which by convention
is boost_libname, same as the project name. INTERFACE means that
this library is header-only and requires no building.
add_library(Boost::core ALIAS boost_core)
The second add_library declares an alternative name for the library,
which by convention is Boost::libname. It's good CMake practice to
only link to targets of this form (more specifically, to targets containing
::), because they are unambiguously CMake target names, whereas the
alphanumeric boost_core may refer to either a target or to a library
on disk named f.ex. libboost_core.so.
target_include_directories(boost_core INTERFACE include)
This directive declares the directory containing the library headers, which
for Boost libraries is the include subdirectory. (A relative path is
interpreted as relative to CMAKE_CURRENT_SOURCE_DIR, that is, to the
location of the current CMakeLists.txt file.)
If you are familiar with CMake, your first impulse would be to declare this line wrong, and replace it with
target_include_directories(boost_core INTERFACE
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include)
or
target_include_directories(boost_core INTERFACE
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include
$<INSTALL_INTERFACE:include>)
or perhaps
target_include_directories(boost_core INTERFACE
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include
$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)
You shouldn't; the line is, in fact, correct. The Boost superproject will
automatically invoke boost_install for your target, which will patch
the value of the include path to something like that last alternative
(but it will take into account the Boost-specific variables
BOOST_INSTALL_LAYOUT and BOOST_INSTALL_INCLUDE_SUBDIR.)
target_link_libraries(boost_core
INTERFACE
Boost::assert
Boost::config
Boost::static_assert
)
Traditionally, Boost has had all the headers copied (in a release) or
linked (in a modular layout) into a single boost/ directory. This made
it possible to include headers from any library (A) into any other (B),
without the need to declare that B depends on A.
With CMake, we will no longer maintain a single boost/ directory where
all the headers are copied. Headers of A will remain in libs/A/include,
and if this directory isn't in the include path of B, B will not be able
to include a header from A.
In order for the include path of B to contain libs/A/include, B must
explicitly declare a dependency on A. In CMake, this is accomplished by
"linking" to A, even when A is header-only.
This is the purpose of the target_link_libraries directive above. In
this specific case, it declares that boost_core depends on Boost::assert,
Boost::config, and Boost::static_assert, and will result into
libs/assert/include, libs/config/include, and libs/static_assert/include
being added to the include path of Core. (More precisely, they will be added
to the include paths of the users of Boost::core. Core itself needs no
include path because it doesn't require any compilation. This is what the
INTERFACE keyword means - it sets the "usage requirements" of the target,
which are propagated upwards to its users.)
The exact form of the directive, with each Boost::libname target on its
own line, with nothing else, is significant. (In particular, the closing
parenthesis should not be placed on the same line as the last target.)
This requirement is imposed by the behavior of the user-settable
BOOST_INCLUDE_LIBRARIES option of the superproject, which requests only
the listed libraries and their dependencies to be configured, built, and/or
installed. To determine the dependencies, a simple-minded parser scans the
CMakeLists.txt files, looking for strings matching Boost::libname on
their own line.
if(BUILD_TESTING AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/test/CMakeLists.txt")
add_subdirectory(test)
endif()
The final portion of the generated CMakeLists.txt file adds support for
invoking the library tests from the Boost superproject. Since not all
libraries have one, this is only enabled when
libs/libname/test/CMakeLists.txt exists.
In principle, since you know whether this file exists for your library or
not, you can either remove this condition or remove this entire section; but
doing so will make your CMakeLists.txt file not match the generated output,
which has its downsides.
BUILD_TESTING is the standard CMake option (typically defined by the CTest
CMake module) that allows the user to enable or disable tests for a project.
It's used here to skip the inclusion of the test subproject in order to
speed up the configure and build phases of Boost when testing is not required
or desired.
If your library has a test/CMakeLists.txt file that is not intended to be
used from the Boost superproject, and is incompatible with it, replace this
block with either
if(BUILD_TESTING AND CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
add_subdirectory(test)
endif()
when your test suite is only intended to be used when your library is the root project (that's usually the case, so this option is the recommended one), or
if(BUILD_TESTING AND NOT BOOST_SUPERPROJECT_VERSION)
add_subdirectory(test)
endif()
when your test suite is also intended to be invoked when your library is a subproject of a user project. (This case is rare and user projects are typically not interested in running their subprojects' tests, so you probably don't want this.)
You may have noticed by now that no installation support is declared in the
CMakeLists.txt file. Nevertheless, the library can in fact be installed.
The Boost superproject automatically adds the necessary support to libraries
which declare a target boost_libname that matches the directory of the
CMakeLists.txt file (libs/libname) and whose target_include_directories
directive matches the one above.
It is recommended that you don't attempt to add your own installation support. Let the superproject handle it.
If your library needs C++11 or above, you can declare this requirement by adding the following directive:
target_compile_features(boost_libname INTERFACE cxx_std_11)
(use cxx_std_14 for C++14, cxx_std_17 for C++17, and so on.)
This will increase your CMake requirement to 3.8, so you should also update the preamble to reflect this.
If your meta/libraries.json already declares the C++ requirement by means
of "cxxstd": "xx", Boostdep 1.77+ will automatically take this into
account and add the above target_compile_features.
This is all you need to have a header-only library that integrates into the
Boost CMake infrastructure. It is also a well-behaved suproject that can be
included into user CMake projects via add_subdirectory. Avoid the urge to
add more functionality unless it's really necessary, as it will compromise
the usability of your library as a subproject.
Many library authors who use CMake, however, add development-centric
functionality to their CMakeLists.txt file; you might already have. In this
case, try to keep the CMakeLists.txt portions described so far as close to
unchanged as possible, and at the end, add a section guarded with
if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
# Functionality enabled only when we're the root project
endif()
and put all your current developer-centric functionality there. This way, subproject use will be unaffected, and you can still use CMake from your library directory for development-related activities such as generating Visual Studio workspaces, or testing outside the Boost tree.
Even if your library requires compilation, you can still use
boostdep --cmake libname at least as a starting point. We'll take
Timer as an example, with the output of boostdep --cmake timer given
below:
# Generated by `boostdep --cmake timer`
# Copyright 2020 Peter Dimov
# Distributed under the Boost Software License, Version 1.0.
# https://www.boost.org/LICENSE_1_0.txt
cmake_minimum_required(VERSION 3.5...3.16)
project(boost_timer VERSION "${BOOST_SUPERPROJECT_VERSION}" LANGUAGES CXX)
add_library(boost_timer
src/auto_timers_construction.cpp
src/cpu_timer.cpp
)
add_library(Boost::timer ALIAS boost_timer)
target_include_directories(boost_timer PUBLIC include)
target_link_libraries(boost_timer
PUBLIC
Boost::config
Boost::core
Boost::system
PRIVATE
Boost::chrono
Boost::io
Boost::predef
Boost::throw_exception
)
target_compile_definitions(boost_timer
PUBLIC BOOST_TIMER_NO_LIB
PRIVATE BOOST_TIMER_SOURCE
)
if(BUILD_SHARED_LIBS)
target_compile_definitions(boost_timer PUBLIC BOOST_TIMER_DYN_LINK)
else()
target_compile_definitions(boost_timer PUBLIC BOOST_TIMER_STATIC_LINK)
endif()
if(BUILD_TESTING AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/test/CMakeLists.txt")
add_subdirectory(test)
endif()
We won't be repeating the explanations of the sections that match the header-only case, and will only focus on the differences.
add_library(boost_timer
src/auto_timers_construction.cpp
src/cpu_timer.cpp
)
For a compiled library, you need to declare your source files. This is
accomplished by listing them in the add_library directive. boostdep uses
the contents of your src subdirectory (but ignores any subdirectories.)
Since Timer is a simple library, this works as-is. Many compiled libraries however might require adjusting the source file list, or choosing it based on the platform. For example, Thread needs something like
if(BOOST_THREAD_THREADAPI STREQUAL win32)
set(THREAD_SOURCES
src/win32/thread.cpp
src/win32/tss_dll.cpp
src/win32/tss_pe.cpp
src/win32/thread_primitives.cpp
src/future.cpp
)
else()
set(THREAD_SOURCES
src/pthread/thread.cpp
src/pthread/once.cpp
src/future.cpp
)
endif()
add_library(boost_thread ${THREAD_SOURCES})
The logic for choosing the source files is already spelled out in your
Jamfile, so you will need to port it to CMake.
If your library has C source files, you'll need to also enable C as a language in your project declaration:
project(boost_container VERSION "${BOOST_SUPERPROJECT_VERSION}" LANGUAGES C CXX)
although boostdep might already have done so for you.
The add_library(libname sources...) declaration generates either a static
or a shared library depending on whether BUILD_SHARED_LIBS is set to ON
or OFF. This is idiomatic CMake behavior and is what we want.
target_include_directories(boost_timer PUBLIC include)
The only difference with the header-only case is the use of PUBLIC instead
of INTERFACE. PUBLIC applies to both the library and its dependents; in
b2 terms it declares both a requirement and a usage-requirement.
target_link_libraries(boost_timer
PUBLIC
Boost::config
Boost::core
Boost::system
PRIVATE
Boost::chrono
Boost::io
Boost::predef
Boost::throw_exception
)
Again, the difference here is in the use of the scope keywords PUBLIC and
PRIVATE (applies only to the library, not to dependents) instead of
INTERFACE. boostdep puts the dependencies referred to from the include
subdirectory in the PUBLIC section, and those referred to from the src
subdirectory in the PRIVATE section.
target_compile_definitions(boost_timer
PUBLIC BOOST_TIMER_NO_LIB
PRIVATE BOOST_TIMER_SOURCE
)
The compile definitions are passed to the compiler with a -D option and
define macros. In this case by Boost convention we define BOOST_TIMER_NO_LIB
to disable autolink and BOOST_TIMER_SOURCE when compiling the library to
properly declare exported functions as exported (as opposed to imported,
which will be the case when using the library.)
if(BUILD_SHARED_LIBS)
target_compile_definitions(boost_timer PUBLIC BOOST_TIMER_DYN_LINK)
else()
target_compile_definitions(boost_timer PUBLIC BOOST_TIMER_STATIC_LINK)
endif()
When building shared libraries, we define BOOST_TIMER_DYN_LINK, and when
building static libraries, we define BOOST_TIMER_STATIC_LINK. Again, this
is needed to properly export and import functions from dynamic libraries, in
particular on the Windows platform.
These defines are described in the Boost document about separate compilation and you can look at how the Timer library uses them as an example.
If your build results in more than one library being built, or if the name
of your library target does not match your directory name, you need to invoke
the installation support manually. As an example, Serialization builds two
library targets, boost_serialization and boost_wserialization, and the
procedure to install them entails adding
the following section
to CMakeLists.txt:
if(BOOST_SUPERPROJECT_VERSION AND NOT CMAKE_VERSION VERSION_LESS 3.13)
boost_install(TARGETS boost_serialization boost_wserialization
VERSION ${BOOST_SUPERPROJECT_VERSION} HEADER_DIRECTORY include)
endif()
The check for BOOST_SUPERPROJECT_VERSION is necessary because without the
superproject, boost_install is not available. The check for the CMake
version is needed because the automatic Boost installation support requires
CMake 3.13. Even though boost_install will work on earlier CMake versions,
you will likely get errors at generate time because the dependencies of your
library will lack install support.
For another example of a CMakeLists.txt file building and installing more
than one library, see Boost.Test.
If your library uses multiple threads or threading primitives, you need to
add the following snippet to your CMakeLists.txt file:
set(THREADS_PREFER_PTHREAD_FLAG ON)
find_package(Threads REQUIRED)
and then link to the target Threads::Threads in your
target_link_libraries directive. Typically, this would go in the PUBLIC
section (or INTERFACE if your library is header-only.)
(PRIVATE would imply that your library needs threading, but the clients
of your library do not, which is rarely the case.)
Note that this will abort the CMake configure phase with an error if
threading support can't be enabled. This is usually acceptable, but it's also
possible to omit the REQUIRED in find_package(Threads REQUIRED) and then
check Threads_FOUND and take some appropriate action when it's FALSE, such
as setting a preprocessor definition via target_compile_definitions.
Some libraries allow different functionality or backends. For example,
Iostreams has optional support for compressed streams and can use one or more
of the compression libraries ZLib, BZip2, LibLZMA, or Zstd, if these are
present on the system when the library is built. Locale, for another example,
can use Iconv, ICU, POSIX newlocale, or the Windows API, again depending on
availability at build time.
The recommended way to provide such optional functionality is to allow user configuration with sensible defaults, as shown in the following example that allows optional use of ZLib:
find_package(ZLIB QUIET) # Look for ZLib
option(BOOST_MYLIB_ENABLE_ZLIB "Boost.MyLib: enable ZLib support" ${ZLIB_FOUND})
if(BOOST_MYLIB_ENABLE_ZLIB)
find_package(ZLIB REQUIRED) # For real this time
target_compile_definitions(boost_mylib PRIVATE BOOST_MYLIB_ENABLE_ZLIB=1)
target_add_sources(boost_mylib PRIVATE src/zlib.cpp)
target_link_libraries(boost_mylib PRIVATE ZLIB::ZLIB)
endif()
The general pattern is
- determine a sensible default
- add a CMake option to allow user control and override
- if the option is
ON, enable functionality
Avoid silently enabling functionality on the basis of autodetection; it's better to allow user control, in both directions. That is, the user should be allowed to disable the functionality even if it's possible to incorporate it, and the user should also be allowed to enable the functionality even if autodetection says it won't work.
find_package in quiet mode is not the only possible way to determine the
default. You can also use platform detection (if(WIN32)), the result of a
configure check (cxx_check_source_compiles), and other measures.
After all the build options have been declared and taken into account, the library should emit a single line of status output that shows the selected configuration. For Iostreams, this output is of the form
-- Boost.Iostreams: ZLIB OFF, BZip2 OFF, LZMA OFF, Zstd OFF
Other Boost libraries that allow configuration are Context, Fiber, Locale, Python, Stacktrace, Thread. For reference, their corresponding output is
-- Boost.Context: architecture x86_64, binary format pe, ABI ms, assembler masm, suffix .asm, implementation fcontext
-- Boost.Fiber: NUMA target OS is windows
-- Boost.Locale: iconv OFF, ICU OFF, POSIX OFF, std ON, winapi ON
-- Boost.Python: using Python 3.9.5 with NumPy at C:/Python39/Lib/site-packages/numpy/core/include
-- Boost.Stacktrace: noop ON, backtrace OFF, addr2line OFF, basic ON, windbg ON, windbg_cached ON
-- Boost.Thread: threading API is win32
When your library is built as part of Boost, it should only add CMake options and cache variables when they materially affect the way it's built or it will operate.
Remember that Boost contains more than 140 libraries. If every such library
adds four "nice to have" options, this will result in 560 options in total in
cmake-gui for the user to wade through, most of which of no relevance for
the use at hand.
Either add the options only when BOOST_SUPERPROJECT_VERSION is not defined,
or only add them when your project is the root project (recommended).
(The difference is whether you insist on your options appearing when someone
uses the library with add_subdirectory. Typically, the options people add
to their libraries are only relevant when the library is the root project.)
Definitely don't do this:
option(BOOST_MYLIB_MYOPTION "" ON)
if(BOOST_MYLIB_MYOPTION AND NOT BOOST_SUPERPROJECT_VERSION)
# Do highly valuable optional things
endif()
This displays the option, but makes it do nothing. Instead, either put the
option declaration inside an if, or use
CMakeDependentOption:
include(CMakeDependentOption)
cmake_dependent_option(BOOST_MYLIB_MYOPTION "" ON "NOT BOOST_SUPERPROJECT_VERSION" OFF)
if(BOOST_MYLIB_MYOPTION)
# Do highly valuable optional things
endif()
When your library is built as part of Boost, avoid the urge to emit status output unless it's relevant.
Remember that Boost contains more than 140 libraries. If every such library emits two lines of status output, this will result in 280 lines in total, most of them of no interest to the user.
Status output should be reserved for information that is of importance to the user building and installing Boost, which usually means that it should only be emitted by libraries that materially alter their operation on the basis of user configuration or properties of the build environment.
Starting with CMake 3.15,
message
now supports VERBOSE and DEBUG message types, which would be ideal for
the purpose of developer-centric output, if we could require CMake 3.15.
We don't (yet), so the current convention is to only emit "debug" output when
Boost_DEBUG is ON, and only emit "verbose" output when Boost_DEBUG is
ON or Boost_VERBOSE is ON.
(The rule of thumb separating "verbose" from "debug" is that the target
audience of the "debug" output is the person authoring the CMakeLists.txt
file, whereas the target audience of the "verbose" output is the user who
prefers verbosity over conciseness.)
Target names are global. Always prefix your target names with the name of your
project/library, such as boost_mylib-mytarget.
(This is typically only of relevance if you write your own tests by hand using
add_executable and add_test.)
BUILD_TESTING is the standard CMake variable that controls whether
add_test does anything. Unless BUILD_TESTING is ON, to save time, you
should avoid creating any tests or targets on which they depend. Usually, this
translates to
if(BUILD_TESTING)
add_subdirectory(test)
endif()
Since CMake doesn't support any inline function calls or expressions,
programmers are tempted to use generator expressions. In a situation where
one would write in C++ foo? "bar": "baz", one could write in CMake
$<IF:$<BOOL:${FOO}>,BAR,BAZ>.
Don't do this. It's not the same. Generator expressions are evaluated in the generate phase, which happens after the configure phase. If you do
target_compile_definitions(boost_mylib PUBLIC $<IF:$<BOOL:${BUILD_SHARED_LIBS}>,BOOST_MYLIB_DYN_LINK,BOOST_MYLINK_STATIC_LINK>)
(and assuming BUILD_SHARED_LIBS is ON), you're not setting the
COMPILE_DEFINITIONS property of boost_mylib to BOOST_MYLIB_DYN_LINK, but
to $<IF:$<BOOL:ON>,BOOST_MYLIB_DYN_LINK,BOOST_MYLINK_STATIC_LINK>.
Yes, it will still be evaluated to the right thing during generation, but it's better to perform evaluations that only depend on configuration-time values at configuration time and write the less "clever"
if(BUILD_SHARED_LIBS)
target_compile_definitions(boost_mylib PUBLIC BOOST_MYLIB_DYN_LINK)
else()
target_compile_definitions(boost_mylib PUBLIC BOOST_MYLINK_STATIC_LINK)
endif()
The primary scenario we will support is, obviously, building and installing Boost with CMake (and optionally, running the tests, if one has a few days to spare).
The building procedure would generally involve issuing (from the Boost root)
mkdir __build
cd __build
cmake <configuration options> ..
cmake --build . -j <threads>
which should result in Boost libraries being built with the specified
configuration options in subdirectories of the "stage" directory, by default
stage/lib and stage/bin.
Subsequent installation would be performed with
cmake --build . --target install
assuming that CMAKE_INSTALL_PREFIX was set beforehand to the desired
destination directory.
Under Windows, when using the default Visual Studio generator, the building
and installation procedure would need to be performed twice, once with
--config Debug, and once with --config Release (or perhaps with
--config RelWithDebInfo, as desired.)
Testing the entire Boost would be performed with
cmake -DBUILD_TESTING=ON ..
cmake --build . --target tests -j <threads>
ctest --output-on-failure -j <threads>
Again, when using the Visual Studio generator, this would be
cmake --build . --target tests -j <threads> --config Debug
ctest --output-on-failure -j <threads> -C Debug
resp.
cmake --build . --target tests -j <threads> --config Release
ctest --output-on-failure -j <threads> -C Release
The secondary scenario we would like to support would be user projects
"consuming" Boost libraries piecemeal without the superproject, by having
them in subdirectories in their project (as Git submodules, or acquired
with FetchContent), and then using add_subdirectory to incorporate them
in the master CMake project.
A sample project that demonstrates how users would consume individual Boost libraries in this manner is available at github.com/pdimov/boost_cmake_demo.
Note that BOOST_SUPERPROJECT_VERSION is not set in this scenario, but all of
the recommendations in the preceding sections still apply. Be sure to not
degrade the experience of the users choosing to embed Boost libraries in this
manner because your logic relies on checking BOOST_SUPERPROJECT_VERSION.
Some Boost developers wish to support a scenario in which their library is
included via add_subdirectory into the user project, but other Boost
libraries are not. To obtain access to their Boost dependencies, they rely
on preexisting Boost installations, found using find_package(Boost).
This rarely makes sense. Since the library is a Boost library, if
find_package(Boost) works for it, it will also work for the user, which
will make that library available (it being part of Boost.) There is no
need to incorporate it individually.
The cases where this does make sense generally concern a new library that
is not yet accepted into Boost, has not yet appeared in a Boost release, or
is sufficiently new that the typical find_package(Boost) finds a Boost
release that does not contain it.
These conditions only apply in the short term, and supporting this use case
is not recommended, because in the long term it's both a maintenance burden
and a source of problems. (When find_package(Boost) does find a Boost
release containing the library, it will rarely be the same version, which can
easily lead to the user project containing two versions of the library, with
the associated ODR violations which would at best manifest as link errors.)
If you insist on supporting this scenario, please make sure to not compromise the user experience in the previous two cases.
Installing an individual Boost library, without the rest of Boost, is an even
worse idea. It can easily lead to a broken Boost, and there's not much to be
gained even if it "works". Don't do it. If you do, please don't use the same
package name (boost_libname) or target names (boost_libname,
Boost::libname) as the legitimate Boost installation; if possible, also do
not use the boost namespace, to avoid link errors or ODR violations when
the "standalone" library and the legitimate Boost library end up in the same
binary (this happens more often than you might think.)
- Creating IDE Projects