Boost compatibility levels 🧵

[kgreenek]

There was a discussion in person today at bazelcon about boost's compatibility levels in the bcr, and I think it would be good to continue the discussion here with more folks.

tl;dr Is it really necessary for boost to increment the compatibility_level for each minor release? If not that would make our maintenance burden easier. If so, then I outline the implications and some potential ideas for making it more manageable.

Right now the compatibility level is incremented in the bcr for each boost minor version.

For example, the compatibility level was set to 108900 for Boost 1.89 modules, 108700 for Boost 1.87 modules, etc. See:
https://github.com/bazelbuild/bazel-central-registry/blob/main/modules/boost.any/1.89.0/MODULE.bazel#L5

This means that every module that depends on boost must explicitly be updated with a new bcr release in order to support newer versions of boost. That is necessary because the boost compatibility level was incremented, which indicates to bazel that it is NOT compatible with older versions (more discussion on this below).

Let's create a hypothetical example:

We have the following modules which depend on different versions of boost:

foo/1.1.0 -> Boost 1.83
bar/2.1.0 -> Boost 1.83
baz/3.1.0 -> Boost 1.89

Now when you depend on baz in your MODULE.bazel file, you can no longer depend on foo or bar because bazel will tell you Boost 1.83 is not compatible with Boost 1.89 (compatibility_level 108300 < 108900).

The solution so far has been to create new bcr versions for every module which depends on boost.

So in our example, we will end up with this:

foo/1.1.0 -> Boost 1.83
foo/1.1.0.bcr.1 -> Boost 1.89   # New
bar/2.1.0 -> Boost 1.83
bar/2.1.0.bcr.1 -> Boost 1.89  # New
baz/3.1.0 -> Boost 1.89

Now if you want to depend on baz, you need to depend on the new bcr.1 versions of foo and bar. That works, but there is a problem. What about folks who depend on foo or bar, but want to use an older version of boost?

After a while of new releases being published, we might end up with this:

foo/1.1.0 -> Boost 1.83
foo/1.1.0.bcr.1 -> Boost 1.89
foo/1.1.1 -> Boost 1.89
bar/2.1.0 -> Boost 1.83
bar/2.1.0.bcr.1 -> Boost 1.89
bar/2.2.0 -> Boost 1.89
baz/3.1.0 -> Boost 1.89

We can no longer depend on the newest version of foo or bar while using an older version of boost -- even though foo and bar in our example are actually compatible with Boost back to 1.83.

This approach was done recently in @UebelAndre 's PRs to add boost 1.89. Many thanks for all that work!

Boost is generally very stable and does a good job of maintaining backwards compatibility in my experience (although not always perfectly). I am wondering if we can simply stop incrementing the compatibility_level in the boost modules in the bcr. Then foo would not need to be updated to support newer versions of Boost, and it can continue supporting older versions of Boost easily.

There are many examples in the repo of projects which can use any version of boost from 1.83+ and don't need to be updated or changed to be compatible with newer version of boost. To name a few: folly, fizz, wangle, behaviortree_ros2, pcl, proxygen, lanelet2, and more.

If we cannot drop the boost compatibility_levels, then there is a matrix expansion effect that needs to happen in order to support older versions of boost with newer versions of all the modules that depend on Boost.

Here is one way that might play out with our example:

# The matrix expansion of Foo v1.1.0 (and a bcr.1 bug fix) for all boost versions it supports.
foo/1.1.0.boost.1.83 -> Boost 1.83
foo/1.1.0.boost.1.87 -> Boost 1.87
foo/1.1.0.boost.1.89 -> Boost 1.89
foo/1.1.0.boost.1.83.bcr.1 -> Boost 1.83
foo/1.1.0.boost.1.87.bcr.1 -> Boost 1.87
foo/1.1.0.boost.1.89.bcr.1 -> Boost 1.89

# The matrix expansion of Bar v2.1.0 (and a bcr bug fix) for all boost versions it supports.
bar/2.1.0.boost.1.83 -> Boost 1.83
bar/2.1.0.boost.1.87 -> Boost 1.87
bar/2.1.0.boost.1.89 -> Boost 1.89
bar/2.1.0.boost.1.83.bcr.1 -> Boost 1.83
bar/2.1.0.boost.1.87.bcr.1 -> Boost 1.87
bar/2.1.0.boost.1.89.bcr.1 -> Boost 1.89

# Baz only supports Boost 1.89 (and presumably future boost releases)
baz/3.1.0.boost.1.89 -> Boost 1.89

That is obviously pretty non-ideal. So how can we avoid this?

The bazel_dep macro does have a max_compatibility_level arg we can pass. For everything that depends on Boost, we could set the compatibility level to something large up to the next major version.

Given the current compabitility_level convention, that would look like this:

# Depend on any version of boost from 1.83+ up to the next major version.
bazel_dep(name = "boost.core", version = "1.83.0", max_compatibility_level=109999)

This avoids the need to update our module whenever the boost version is updated as long as we are confident future version of boost will remain backwards compatible with 1.83.

This is a lot nicer than the boost matrix expansion. However, I think it would present a common gotcha for folks when they depend on boost. They would need to specify this max_compatibility_level every time they depend on boost or else updating boost would be a chore in the future.

Another idea: Rather than having a single compatibility_level that is shared across all boost modules, each module could have its own compatibility_level which is incremented when a breaking change actually occurred in that particular module.

For example, maybe there was a breaking change in boost.geometry between 1.88 and 1.89. In this case boost.geometry's compatibility_level could be bumped from e.g. 0 to 1. But all the other boost modules would not have to be affected. This would be much more granular and would likely avoid the version-matrix-expansion problem for the most part. The downside is that it would require the boost module maintainers to be more familiar with what changed between releases.

Tagging @UebelAndre @meteorcloudy @fmeum @cdelguercio @Vertexwahn

edit for typos

[kgreenek]

I just saw that many of @UebelAndre 's PRs had to be closed due to incompatibilities with boost 1.89. So maybe it is not so straight-forward as I was hoping. Would love others' insights here.

[kgreenek]

just giving this a nudge so it stays top of mind

[UebelAndre]

I am also planning to add new bcr versions for boost 1.83 and 1.87 in a follow-up PR so those can be used without a compatibility version as well.

Are you gonna use the script to fill in missing dependencies? When doing 1.89.0.bcr.1 I ended up hard-coding this to return 1.88.0.bcr.2 since I'd already done the ground work to get it to compile correctly.

bazel-central-registry/modules/boost/add_boost_version.py

Lines 201 to 212 in 0748633

	def find_closest_version(target_version: str, available_versions: list[str]) -> str:
	"""Find the closest existing version to copy from.
	For BCR versions (X.Y.Z.bcr.N):
	- First tries to find the latest BCR version of the same base release (X.Y.Z.bcr.M where M < N)
	- If not found, tries the base version (X.Y.Z)
	- Falls back to closest lower version
	Examples:
	- 1.89.0.bcr.1 -> prefers 1.89.0
	- 1.89.0.bcr.2 -> prefers 1.89.0.bcr.1, then 1.89.0
	"""

The deltas were minimal but as a warning the worst part of the change was Windows since I don't have any other way to test that platform outside of Github runners.

[kgreenek]

Thank you that is helpful! Yes I'm planning to use the script to create new bcr versions for 1.83 and 1.87. I'm hoping that getting it to build shouldn't be a problem since I'm not changing anything besides the compatibility_level in the MODULE.bazel files. But we will see once CI runs on the PR I suppose.

[UebelAndre]

Something to look out for is that boost.test will take ~6 hours to finish it's tests lol. The PR is best opened on Friday and reviewed on Monday 😅 (Also I didn't do that, I'm a victim like everyone else)

[kgreenek]

Good to know lol. Thank you

[UebelAndre]

Just for the record, I don't have any desire to maintain boost modules. I needed boost for a dependency and the state of the libraries were all over the place with libraries missing in some versions and compatibility preventing me from mixing. I would like it if there was some protection for libraries in a single version of boost (e.g. 1.88.0) to only depend on transitive boost libraries from the same version. But beyond this I'm just a stubborn bystander who wanted their libraries to work so took it upon myself to fix a few versions. Anything beyond boost 1.89.0 should have some modernized BUILD files and (hopefully) only require minimal lifts to get it working.

[fmeum]

We haven't done a good job communicating this, but `max_compatibility_level` has pathological performance implications and can't really be used for more than a handful modules *across the entire build*. You couldn't know that, but the new module will likely cause severe performance issues once used in a module graph with multiple reachable versions of boost. I would suggest doing the following: 1. Yank the modules added in #6516. 2. Use a slightly modified version of @UebelAndre's script to add new versions of the boost libraries that keep the compatibility level constant while adding `bazel_dep`s with `repo_name = None` for each real boost module to the boost meta module. This cycle forces all boost modules to the same, highest version requested. It does require bumping the minimum Bazel version to 7.6.0, which added support for such "nodep" dep edges. 3. Release new versions of the yanked modules that don't use `max_compatibility_level`. I can help with 2. if you run into issues.

…

On Wed, Nov 12, 2025, 04:28 Kevin Greene ***@***.***> wrote: Forgot to link the pr: #6516 <#6516> — Reply to this email directly, view it on GitHub <#6511 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABA4Y7ZYHFM64QC5OF2JSKD34KSNTAVCNFSM6AAAAACL2BVII2VHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTIOJUGIYTOMQ> . You are receiving this because you were mentioned.Message ID: <bazelbuild/bazel-central-registry/repo-discussions/6511/comments/14942172 @github.com>

[Vertexwahn]

What would happen if we yank all Boost modules that were created until today, and add bcr fixes ([email protected] to [email protected]) where we simply set the compatibility level to "0". Would yanked modules simply be ignored when resolving the build graph, and would this solve all our issues (besides that this is some work to do)? The new modules should of course use the no_deps features to make sure that a certion version of a Boost modules just uses other Boost modules of the same version.