Re: [boost] Boost CMake support - Request for Comment

Subject: Re: [boost] Boost CMake support - Request for Comment
From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2018-10-09 23:08:48

Let me start by thanking you, Robert, for getting this process
started. CMake has been a hot topic for a long time with little action
and getting a review going is important.

On Mon, Oct 1, 2018 at 8:07 PM Robert Ramey via Boost
<boost_at_[hidden]> wrote:
>
> Scope, Requirements and Features
> ================================
>
> Library Build
> -------------
>         “Effective CMake" - https://www.youtube.com/watch?v=bsXLMQ6WgIk
> Recommends that all libraries - including header only libraries have a
> CMakeList.txt file.  What should this include for Boost Libraries?

I suppose, every library, header-only or not, will have to include
CMakeLists.txt. For separately compiled libraries, CMakeLists.txt
should support building the library, similarly to Boost.Build. These
CMakeLists.txt files, along with the one of the superproject, will
have to be included in the source code packages we distribute. And
also in the Windows binary packages we distribute.

Note that here I assume that at this point we are continuing to
distribute monolithic Boost releases for the time being. This may
change in the future as we modularize Boost but for now having CMake
alone is a big enough task by itself. Of course, if a certain CMake
proposal already presents a potential route for further
modularization, it can only be a plus.

> Library Test
> ------------
>         Should facilities for "testing" be only done by developers? or should
> users who acquire library packages also be able to test libraries.

I think, the ability to test libraries is essential for both Boost
developers and users (primarily, developers, though). I think,
potential solutions should include this functionality.

>         Should CMake testing results posting be used - CDASH?

I don't really know what CDash is, I've never used it.

>         Should we just skip the issue of Library Testing and continue to depend
> on Boost Build.

Building library docs is missing in this section. Having CMake able to
build docs is less important than being able to build and test
libraries, so we may omit this functionality at first. Docs are
available online and pretty readable in source form most of the time.
However, it would seem that this task should be the easiest one from
the build system standpoint, so it shouldn't be too difficult to add.

> Library Packaging
> -----------------
>         Is the library packaging facility provide by CMake - CPACK - useful to
> boost.  Should boost libraries be updated to support it?

I would really like us to not get into the packaging business beyond
preparing source packages of Boost releases. Packaging is a difficult
topic, very target system dependent. Let the people who has the domain
knowledge do it.

As someone who has built Debian packages of Boost for my project I can
tell that it is unlikely that I would use CPack. Not because something
is wrong with it (in fact, I've never had to use it, so I really don't
know), but because the current building pipeline doesn't involve it
and works backwards. I.e., as far as I know, CPack is designed to be
part of the build system, to which it adds packaging as one of the
steps, while the common workflow is that you invoke packaging tools
(dpkg, debhelper in case of Debian packages), which invokes the build
process and then collects and packages the artifacts from it. I don't
really see the benefit from changing the common workflow.

I suppose, CPack could be useful if we did packaging and deploy as
part of our CI process, but we don't.

> Dependencies
> ------------
>         If the above is implemented, can we depend upon CMake to handle library
> dependencies?  Or does some special functionality
>         Do circular dependencies constitute a problem?

I think, dependency management will be limited to enumerating
immediate dependencies for the targets in CMakeLists.txt, much like
what we have now with Boost.Build. Since we won't do packaging, we
won't have to deal with package dependencies, including dependencies
from system libraries, like zlib, for example.

I'm not sure how CMake manages dependencies between targets and
whether circular dependencies constitute a problem. CMake proposals
will have to clarify that, I guess.

> Modularity
> ----------
>         Currently boost is organized as a tightly integrated group of
> libraries.  This organization manifests itself in a number of ways.
>                 We have a Boost "super project" in github.  Boost libraries are "sub
> projects" of this super project.  This known structure is exploited by
> and depended upon by boost tools.  Should CMake support continue this
> policy/design.
>                 We distribute boost as "super project".  Should we continue to do this
> or distribute libraries on a library by library basis.  Does CMake/CPACK
> etc. make this "simple"?

As I said earlier, I don't think we should specifically target
modilarization at this point as just adding support for CMake alone is
a big enough task. Let us leave further modularization for future and
not require immediate support for it.

Therefore, I think, we will have a CMakeLists.txt in the superproject,
as well as in the libs directory.

> Documentation/testing
> ---------------------
>         What support should be require for uses of Boost CMake implementation.
> Documentation, examples, templates for helping library developers.  How
> should the CMake design/implementation be tested?

I think, documentation and examples are required. Given that,
presumably, library maintainers will be the ones who will have to
write CMakeLists.txt for their libraries, the docs quality is very
important. Besides the obvious stuff, like how to create a library or
a test, the docs should describe more intricate stuff, like how to add
compiler switches depending on compiler or how to test if the compiler
supports a certain feature and do something depending on that, or how
to set a custom visibility for a project, etc. From experience with
Boost.Build, I can say that it is these little details that are
difficult to find out.

It would help if, as a proof of concept, demonstrated one or two
converted libraries which cover most common and more inticate use
cases we have.

As for tests, these are, of course, welcome, but ultimately it is the
tool that helps the maintainer most, so I'd leave this to the authors'
discretion. I'm not even sure how one would test CMake scripts.