Boost logo

Boost :

Subject: [boost] Installing CMake configuration files
From: Peter Dimov (lists_at_[hidden])
Date: 2018-10-13 03:00:54

I've taken another stab at installing CMake configuration files along with
the libraries in `b2 install`. CMake configuration files are .cmake files,
typically installed into $prefix/lib or $prefix/lib/cmake, that allow f.ex.
`find_package(boost_system)` in a CMakeLists.txt file to find the installed
Boost.System library and declare a CMake target Boost::system that refers to
it. CMake targets can then link to Boost::system and all is well.

The work in its current state is available on the feature/cmake-config
branch of the superproject:

    git clone --recursive -b feature/cmake-config
    cd boost
    b2 --prefix=... install

After that .../lib should contain the libraries and .../lib/cmake - the
config files. Then from CMake

    cmake -DCMAKE_INSTALL_PREFIX=... ..

as usual.

See for example the test scripts at


Since `b2 install` installs more than one library variant, the CMake
configurations need to pick the correct one and to do so look at (a subset
of) the FindBoost-compatible variables as described at:

Boost_USE_STATIC_RUNTIME, Boost_COMPILER, Boost_DEBUG are honored and have
the same meaning as in FindBoost. Boost_USE_MULTITHREADED and
Boost_USE_DEBUG_RUNTIME are presently ignored, but probably shouldn't be.

The default of Boost_USE_STATIC_LIBS being OFF is a bit inconvenient on
Windows, where without `--build-type=complete` our installation only gives
you static libraries, and there are suggestions to respect it being ON or
OFF, but when not set, to look at BUILD_SHARED_LIBS instead.

Under the hood this represents a refactoring of the current centralized
installation approach in which the superproject staged and installed the
libraries on `b2 stage` and `b2 install`. Now the top level stage and
install targets just delegate to each library's stage and install targets,
which are responsible for staging/installing that particular library, its
CMake config, and its dependencies.

These library-level stage and install targets are created by the helper b2
rule boost-install, which already existed (in Jamroot), but is now much
enhanced and lives in its own module tools/boost_install.

In addition, a metalibrary libs/headers is introduced, which corresponds to
the headers as present in a release (in subdirectory boost/) or as installed
by `b2 install`. Its install target, in fact, installs the headers, and its
stage target, currently empty, should probably assume the function of
linking the headers (which at the moment also lives in Jamroot.)

At some future point, when we decide to switch to releasing the headers in
their original libs/$lib/include locations, the install target of a library
will just copy that library's headers; but we aren't there yet.

The header-only libraries are used from CMake by finding the package
boost_headers and linking to the target Boost::headers. I've deliberately
not done anything about Boost::boost and find_package(Boost), to allow
FindBoost.cmake to delegate to the config files if present (when Boost
1.69/1.70 or higher is installed), while preserving backward compatibility
(when 1.68 or lower is installed.)

Boost list run by bdawes at, gregod at, cpdaniel at, john at