[boost] Installing CMake configuration files

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 
https://github.com/boostorg/boost
    cd boost
    bootstrap
    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

https://github.com/boostorg/boost_install/blob/master/.travis.yml#L60

and

https://github.com/boostorg/boost_install/blob/master/appveyor.yml#L40

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:

https://github.com/Kitware/CMake/blob/master/Modules/FindBoost.cmake#L122

Boost_USE_DEBUG_LIBS, Boost_USE_RELEASE_LIBS, Boost_USE_STATIC_LIBS, 
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.)