The 'Getting Started Doc' should use CMake as the primary way to build and use Boost

[camio]

This the build system that most people use so our documentation should cater to these folks. VCPkg consumption of the library should also get a nod since this is growing in popularity.

I found tvision's CMake build instructions to be fairly good so you may take inspiration from there.

[grafikrobot]

1. B2 is still the single officially supported way to build Boost.
2. There are other package managers that are more popular than vcpkg.

[camio]

I'm not sure what officially supported means. Just like everything else in Boost, people volunteer or not to address issues when they come up. As far as CMake goes, we've got someone who has been actively maintaining it.

Which package managers are you suggesting we additionally give a shout out to?

[Lastique]

I'm not sure what officially supported means.

In particular, this means:

• The support for CMake is experimental and not free from issues.
• You cannot run tests of Boost libraries using CMake. At least, not for the majority of Boost libraries. In fact, our official testers as well as each library's CI use Boost.Build to run tests, and at best libraries only have a basic "builds/doesn't build" test for CMake.
• Officially published pre-built Boost binaries are built using Boost.Build.
• Most downstream packages that I know of (e.g. for Debian) use Boost.Build to build Boost.

I think, both build systems should be covered in the getting started docs, but for CMake it should be made clear that its support is incomplete and experimental. As of now, the default should be Boost.Build. Enthusiastic users are free to try CMake on their own peril.

[alandefreitas]

I agree with @Lastique that both build systems should be covered in the getting started docs. The guide @pdimov wrote in https://github.com/boostorg/cmake is pretty good. It just needs more exposure. It addresses its limitations and its options quite well. Support is not so bad that it has to be hidden. The super-project CI runs tests with both b2 and CMake. Only boost.convert and boost.outcome are excluded from the tests: https://github.com/boostorg/boost/blob/013db32cf4e9efb3381dea2626e0cc7baaf15855/.github/workflows/ci.yml#L192

Covering vcpkg is also a good idea, although priority should be given to the standard installation method. The biggest C++ package managers remaining in the battle seem to be vcpkg and conan. While we can mention conan, vcpkg is the one we need to cover because it provides the modularized libraries people keep asking for, it's the one where I see boost maintainers have more direct control over the ports, and it's becoming ubiquitous as a viable/free/opt-in option now that VS and Jetbrains provide extra support for it out of the box.

[vinniefalco]

You can't build docs with cmake either although that might change with the new Asciidoc/Antora toolchains.

[grafikrobot]

I'm not sure what officially supported means.

It means that it's sufficiently tested and functional for the release managers to approve it for general use.

[pdimov]

Officially supported, for me, means part of the release criteria. This implies that testing that it works would be part of the release checklist. It also implies that if someone makes a CML change that breaks the CMake build, this would preclude a release from going out until it's fixed.

[pdimov]

@mclow @glenfe

[alandefreitas]

You can't build docs with cmake either

I think this is less relevant in the context of the getting-started guide because at this point the users already have a bundle with all docs as html.

[glenfe]

When CMake can do everything that b2 can do, only then do we want to think about treating it equivalently to B2 (or even think about replacing B2 with it, and only ensuring that things don't break CMake). i.e. At that point CMake could be the official build system of Boost and part of the release criteria.

Until then, the guide advertising CMake as preferred might be dangerous, because we would probably have more defects when building with CMake than with B2.

[pdimov]

People are using the CMake build right now, and it would help them if we ensure we don't break it.

That's doesn't yet make it equivalent to b2, just more supported than it is now.

[glenfe]

We can do that. Can you provide me with the minimal set of steps and tests you want executed (and verified) as part of the release process?

[pdimov]

https://github.com/boostorg/boost/blob/master/.github/workflows/ci.yml is probably a good starting point, although it doesn't actually try to use the built/installed Boost. (Although then again we don't tend to do that with b2 either.)

[alandefreitas]

When CMake can do everything that b2 can do

Is this only the docs and source directory layout? Is there anything else?

[vinniefalco]

If CMake is not ready for primetime yet, we should still include as much information on it as possible but make sure it is clearly marked as not complete or fully supported. And unfortunately it must be subordinate to b2 in terms of the order of appearance, until it is finished.

That said, there's nothing wrong with encouraging users to try it and report any problems or successes by opening an issue in the proper repository, this could be a great help.