[boost] Cmake

Subject: [boost] Cmake
From: Peter Dimov (lists_at_[hidden])
Date: 2017-06-24 08:59:12

There is considerable interest in Boost supporting CMake, but it seems that 
everyone has different ideas as to what this support will entail. After 
deliberation and discussions, I have identified the following (separate) 
scenarios:

1. The user installs a Boost release as usual with `b2 install`, which makes 
the installation visible to CMake and usable via 
find_package(boost_libname).

2. The user brings several Boost libraries as git submodules into his 
CMake-based project and uses add_subdirectory in his CMakeLists.txt to link 
to them.

3. The user uses CMake to install an individual Boost library, which is then 
available for find_package.

4. The user uses CTest to run the tests of an individual Boost library.

5. CMake is supported as a way to build and install the entire Boost, in 
place of b2.

6. CTest is supported as a way to run the tests for the entire Boost, in 
place of b2.

At the moment, I think that we should concentrate on (1) and (2) as 
providing most bang for the buck. 5-6 in particular require that all 
Jamfiles are ported at once, which is a serious undertaking for a 
questionable benefit as what we have already works.

I've done a proof of concept for (2), which can be seen here:

https://github.com/pdimov/boost-cmake-demo-2

This repository uses git submodules in ext/ to bring in Boost.System (our 
guinea pig) and its dependencies, then uses them via add_subdirectory in

https://github.com/pdimov/boost-cmake-demo-2/blob/master/CMakeLists.txt

The required CMake infrastructure is on branch feature/cmake in those six 
libraries (assert, config, core, predef, system, winapi.) It consists of 
CMakeLists.txt in the root:

https://github.com/boostorg/system/blob/c306d479e8326a68d07ee7f058a415fe8b67429b/CMakeLists.txt

and supporting .cmake files in cmake/ :

https://github.com/boostorg/system/tree/c306d479e8326a68d07ee7f058a415fe8b67429b/cmake

The goal here is for Boost library developers to be able to remain ignorant 
of CMake if they so choose; so of those files, only sources.cmake requires 
their input (it's empty for header-only, so those require nothing at all.)

BoostVersion.cmake and default.cmake are common for all libraries and are 
copied from the superproject. dependencies.cmake is automatically generated 
with boostdep. There is a Jamfile in cmake/ that updates these three files:

https://github.com/boostorg/system/blob/c306d479e8326a68d07ee7f058a415fe8b67429b/cmake/Jamfile

and the intent is for this to be done automatically in a superproject script 
that invokes "b2 cmake" for the superproject:

https://github.com/pdimov/boost-cmake-demo/blob/master/cmake/Jamfile

which in turn invokes "b2 cmake" in each library having "cmake/Jamfile".

Copying BoostVersion.cmake and default.cmake, instead of referring to them, 
allows libraries to be used without a superproject, to support scenarios (2) 
and (3) above. (Scenario (3) is also supported by default.cmake.)

What remains to be done is (a) to extend this to the rest of the Boost 
libraries, if we decide to do so, which would require figuring out a way to 
cope with the numeric/ irregular libraries, and (b) support for scenario (1) 
above.

Scenario (1), that is, `b2 install` making the installed Boost available for 
CMake find_package use, is an entirely separate undertaking, completely 
independent of what I've done - except for possibly reusing the 
dependencies.cmake files. It would entail generating 
boost_libname-config.cmake and boost_libname-config-version.cmake files for 
each library, and boost_libname-config-<suffix>.cmake subconfiguration files 
for each build variant (toolset, variant=debug/release, link=static/shared, 
runtime-link=static/shared, runtime-debugging=on/off, 
threading=single/multi, and possibly python-debugging=on/off.)

This would probably require us to define CMake variables controlling these 
features, such as BOOST_BUILD_TOOLSET, BOOST_BUILD_VARIANT, BOOST_LINK_TYPE, 
BOOST_RUNTIME_LINK, and so on, with them having appropriate default values 
inferred from the CMake environment.

Then, boost_system-config-vc141-mt-gd-1_65.cmake will check these values and 
if BOOST_BUILD_TOOLSET is "vc141", BOOST_LINK_TYPE is SHARED, 
BOOST_RUNTIME_LINK is SHARED and BOOST_RUNTIME_DEBUGGING is ON, it will 
declare an imported target pointing to 
boost_system-vc141-mt-gd-1_65.lib/dll, otherwise it would do nothing. (Not 
sure how relevant is threading=single/multi today, but in principle, it 
should also check BOOST_THREADING == MULTI.)

Generating these -config.cmake files would ideally be done as part of the 
`b2 install` procedure and require no changes to the individual libraries. 
The changes to the `b2 install` procedure significantly exceed my bjam-fu 
however, so if we decide to proceed with this - and I don't see how we could 
claim CMake support in a meaningful way without it - the interested parties 
would need to figure out a way to make that happen. At this point, I know 
what needs to be done, but not how to bring it about.