The 'Getting Started Doc' should review the presentation of package managers

[alandefreitas]

Which documentation does this apply to?

User's Guide

The problem

These new Getting Started guides are often including sentences like:

using package managers (...) simplifies the installation of software packages

If you do not wish to use a package manager, (...)

I keep reading these kinds of statements there. The guides usually go on to present the package manager first rather than the official installation method. I think some content in those guides is biased toward the assumption that using a package manager is always better as a default. There's no consensus about that at all.

A small comparison

I'm not even sure it's always simpler. That's how you install brew+boost:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install boost

And that's how you install the official boost package in a way where you can get whatever version you want, including the latest version:

curl -L "https://boostorg.jfrog.io/artifactory/main/release/1.82.0/source/boost_1_82_0.tar.gz" | tar -xz -C /tmp/
cd /tmp/boost_1_82_0/ && ./bootstrap.sh && ./b2 -j "$(nproc)" --prefix=/usr/local install

Copying and pasting any of these has basically the same cost. This difference is even more questionable on Windows, where there's no dominant system package manager.

The cons need to be listed

These package managers are the best option for many people in many cases, especially if they are already in their eco-system. They are also a good way to get started if they are not looking at any specific boost library that requires some boost version. And we should totally cover the existence of package managers in these guides.

However, the documentation should be neutral about which one is best and include appropriate admonitions to indicate the trade-offs. Package managers have their cons, and these are not listed in these guides. This can lead the user to end up making uninformed decisions based on these documents. Some things have to be clear about package managers when writing these guides:

1. People need a standalone guide to create the packages in the first place.
2. External packages are not officially maintained or supported
3. The most important point in the context of these guides: Package managers are always a few or many versions behind and promoting these versions in this very guide is contradictory with our goals.

Docs as a reference for packages

First of all, if the docs don't present boost as something easily packageable more than something that has been packaged many times, this is a problem, because this is the documentation people creating packages are going to read.

If you use Linux or macOS, you already know you can apt-get anything slightly famous. You're probably reading this guide because you tried that and had some kind of problem. And if you use Windows, you are probably here because you know you're always out of luck regarding system package managers. choco is not quite there yet.

Docs as a reference for the supported methods

Regarding support, although packages are convenient, we don't officially provide support for these packages in any way, and by that I mean we don't test or even control what is in these packages. This should be a big warning admonition on all pages that mention package managers. It's a safety issue. It should even be in a ROOT/partial/package-manager-warning.adoc so it can be included in all sections about package managers.

Imagine you are a user trying to install Boost for the first time. You go to stack overflow or ask ChatGPT. They tell you to use a package manager and let's say the command it gave you fails. Maybe it gives you something that works now but we don't know if it's going to work in six months. How would you know all package managers will keep working without testing them? But that's OK because ChatGPT is allowed to fail. And SO answers often don't solve your problem.

But if the user follows the instructions in this very guide and it fails, that's a much bigger problem. Not only the quick uncaring method failed but the official method also failed. We have a responsibility here. If the very instructions coming from Boost fail, the user has only one possible conclusion: boost sucks. There's no hope even another package will work because that's where the instructions for packages come from.

Another situation we have to imagine is a user who tried using the package manager before getting to this page, which is also a common scenario. Or assume you want to use a boost feature and the version is too old because you used a package manager. OS and ChatGPT give you proper instructions to fix the problem. But you try the solution and it doesn't work for you because you used a package manager. You go to the website and read the instructions to get Boost from a package manager again. And it fails again. You're out of luck.

Docs as a reference for the latest version

But the most important problem is this: we're about to release boost 1.83, while brew provides boost 1.81 (release 6 months ago). But not that many users are on Macos anyway. Consider systems whose default repositories don't change because they're not external, which are the package managers most people will use: apt-get libboost-all-dev will get you Boost 1.65 (from 5 years ago!) in Ubuntu bionic, boost 1.71 (3 years ago) in Ubuntu focal, and Boost 1.74 (2.25 years ago) in Ubuntu jammy (the latest LTS). Let alone users who want to use boost master or develop.

These old versions of Boost are ok for their goals, which is to provide a system dependency that works with their other system dependencies, based on the assumption that only those versions of Boost are supported. From their POV, the best way to upgrade Boost is to upgrade the whose operating system. That's in conflict with our goals, which is to promote the most recent version of Boost for new applications.

Incentivizing users to use such old versions of Boost is detrimental to Boost itself and contradictory with the purpose of a getting started guide that comes from Boost. Imagine we promote a new version of boost on twitter and the big selling point is that it now includes the boost.mysql library. Users on all kinds of platforms follow the instructions in this guide and no boost.mysql. This is going against the goals of anything we are promoting.

Package managers and modularization

Two notable exceptions regarding the last point about versions are vcpkg and conan. Because they are C++ package managers rather than system package managers, the versions of boost they provide are not stuck in the past to maintain compatibility with some systems. They want the opposite of that. They are also in competition, which gives them the incentive to keep updating it.

Although this might change, vcpkg always has a recent version of boost. Their latest commit to the boost port is from two weeks ago. conan also has reasonably recent versions, although usually a little bit behind. Their latest version is 1.81. But most importantly, in the case of vcpkg, it actually achieves something the official method doesn't, which is modularization. This is one of the biggest complaints about boost and a good reason to list it.

There are some other official modularization methods, like boostorg/boostdep and some ways of integrating with cmake. This should be documented at some point but the official methods are currently less convenient than vcpkg.

Tentative initial guidelines

So, in conclusion, there must be some warnings and some constraints on how package managers are presented and which package managers are presented. These are some initial guidelines I would consider:

• Guides coming from boost cannot have the assumption that using a package manager is always a better default method to install boost, because there's no consensus at all on that.
• The default and supported methods are b2 and cmake. Although the limitations from boostorg/cmake should be disclaimed or handled (the specifics are being discussed in parallel in The 'Getting Started Doc' should use CMake as the primary way to build and use Boost #17)
• A package manager can never be presented as the default way of installing boost
• Whenever a package manager is presented, an admonition with the disclaimer about support should be included from partials
• Some package managers are more important than others in the context of these guides (this list is not exclusive):
  • package managers that only provide very old versions of boost are less important or should be discarded
  • system package managers of which more than 90% of users are already aware are less important
  • package managers providing modularized libraries are more important as this is a recurrent complaint

[anarthal]

I completely agree with @alandefreitas. The presentation for Linux is right now really dangerous, since you shouldn't install with apt unless there isn't other option - you'll get a super old Boost distribution.

Do we really need to separate "getting started on Linux" and "getting started on Linux with package managers"? I'd place these together, since they achieve the same goal.

For Linux, I'd present:

1. Install from source. We should state that this is the "official" (as in "we've tested it and we guarantee this will work").
2. Install using vcpkg
3. Install using conan
4. Install using a system package manager

For Ubuntu, it must state the problems (old libs) you'll get with apt.

[alandefreitas]

@anarthal Exactly.

getting started on Linux with package managers

This is kind of super generic too, because the title suggests the content is about any package manager. In practice, it's only about vcpkg. And this creates another problem because getting started with vcpkg is the same in both linux and windows. That's kind of the point of vcpkg.

So all "getting started on * with package managers" could become a single "getting started with package managers", which would list a few relevant package managers or the section could be removed entirely and be included as a partial in all of the other "Getting started on X" sections. I believe the partial would achieve would @anarthal is proposing.

The partial could include:

• vcpkg and conan, since they are the dominant package managers
• content about the vcpkg modularized packages, which is its biggest pro
• an admonition about the cons of relying on these packages.

System package managers would not be included in the partial since windows and macos don't have default system package managers providing boost. The closest alternatives we have are choco and brew. We have three options here regarding system package managers:

• Not listing any of them, since they provide very old versions of boost
• Listing only apt after the partial in the getting started on linux page, since it's the only one that's officially supported with the system, and include an extra admonition about the versions being old
• Listing choco, apt-get, and brew after the partial in the getting started on windows/linux/macos pages, since they are the most common alternatives in each platform, and include an extra admonition about the versions being old

I guess I would go with one of the first two options, since 1) these package managers don't achieve anything vcpkg and conan don't, and 2) anyone on these systems is either already aware of them or would find the process more complex than the official installation method with no extra benefit.

[anarthal]

I'd do a quick mention (since the first thing I try when installing new stuff is apt-cache search xxx) - essentially a small paragraph discouraging people from doing that bc they'll get obsolete software.

[alandefreitas]

That makes sense. I was in the mindset that we don't need to mention apt-get because users already know they have this option when they do. But it makes more sense to mention apt-get because users already know they have this option when they do and we need to discourage that before they get started with boost 1.65.