Skip to content

bzlmod

Migrating to Bazel Modules (a.k.a. Bzlmod) - Maintaining Compatibility, Part 3

After the massive, yet warranted digression regarding updating legacy WORKSPACE macros that use Label, we now resume our regularly scheduled programming.

We've covered techniques for ensuring that your project remains compatible with different Bazel versions, both Bzlmod and legacy WORKSPACE builds, and older dependency versions. However, we shouldn't make any promises until we've validated that these properties actually hold, preferably via automated testing and continuous integration.

This third post in our four part trilogy covers writing Bazel tests that allow for flexibly switching between various Bazel configurations. We'll consider advice on how to run the tests locally while developing and how to run them in continuous integration.

Migrating to Bazel Modules (a.k.a. Bzlmod) - Maintaining Compatibility, Part 2

In the previous post, we reviewed guidelines for maintaining compatibility with both Bzlmod and legacy WORKSPACE builds, and older and newer dependency versions. I promised that in this post and the next, we'd discuss testing approaches to help ensure that this remains the case.

However, a discussion in the Bazel Slack workspace has revealed a Bzlmod and legacy WORKSPACE compatibilty issue I'd missed in the previous post. So in this post, I'll discuss what to do with the class of legacy WORKSPACE configuration macros that use Label with computed repository names.

As we'll see, this one issue alone ended up meriting a substantial post in itself. We'll cover adding dependency attributes to repository rules, generating .bzl files to resolve Labels, chaining together module extensions, and using macros in generated BUILD files. The former two options are relatively straightforward, but we cover the latter two options in case your use case requires them.

Such legacy WORKSPACE macros commonly seem to pertain to toolchain configuration, selecting repositories to instantiate based on user defined parameters. So we'll use a small example project to illustrate these solutions as they apply specifically to toolchain configuration.

In the next post, I promise to get into the tasty testing stuff, in what promises to be the third of a four part trilogy.

Migrating to Bazel Modules (a.k.a. Bzlmod) - Maintaining Compatibility, Part 1

As we're well aware by now, Bzlmod is the new hotness, and WORKSPACE is old and busted and going away in Bazel 9. However, Bazel 8 still supports WORKSPACE, and thus legacy WORKSPACE usage won't completely disappear for some years yet. Despite the Bazel community's efforts to help facilitate Bzlmod migrations (including this blog series), some projects may remain unable to migrate sooner than later.

What's more, publishing your repository for use by other projects raises the challenge of supporting a range of older and newer versions of its dependencies. Your repository should work with the newest versions of Bazel, rules_java, protobuf, and other dependencies in order to stay current. However, not every project that could benefit from the latest version of your repository will want to upgrade these other dependencies right away.

This post describes how to design a repository to remain compatible with both WORKSPACE and Bzlmod, and with newer and older dependency versions. Just as importantly, in the next two posts, we'll discuss testing approaches to help ensure that this remains the case.

Migrating to Bazel Modules (a.k.a. Bzlmod) - Toolchainization

Part of the promise of Bazel modules is that they are largely self-initializing in an order-independent way. Rule sets, in particular, no longer need to burden users with importing and invoking macros to instantiate repositories and toolchains in a specific order. This burden now shifts to rule set maintainers, but the existing implementation may not provide this ease of use without modification.

This post describes the introduction of a new "toolchainized" API for rules_scala v7.0.0 that better encapsulates toolchain configurations and dependencies. We'll see how this new design enables optimal Bzlmod compatibility, while simultaneously shrinking the legacy WORKSPACE API surface without losing functionality. We'll also see how the Bzlmod and legacy WORKSPACE APIs provide similar interfaces while sharing the same underlying implementation, facilitating Bzlmod migrations.

Migrating to Bazel Modules (a.k.a. Bzlmod) - Repo Names, Again…

The apparent and canonical repository name schema under Bzlmod is the gift that keeps on giving. Much of what it has to give is quite good—once you learn how to really hold it right. Which is to say, to avoid holding canonical repo names at all. That's what the three previous "Repo Names..." posts in this series were all about.

Those previous posts, however, pertained to using BUILD rules, or when accessing runfiles. In those situations, solutions exist to avoid handling canonical repo names directly as a consumer.

If you maintain a Bazel rule set, or need to fix a rule set upon which your project depends, this is the post for you. We'll see how improper repo name usages sneak into rule implementations, and how to shoo them out. Examples include removing canonical repo names from embedded resource paths, filtering lists of target labels, and generating default repository target names. We also discuss removing internal references to your project's own apparent repository name to avoid minor yet preventable issues.

Migrating to Bazel Modules (a.k.a. Bzlmod) - Fixing and Patching Breakages

In the previous Bzlmod post, we covered writing your own Bazel module extensions to adapt your own setup code for dependencies that aren't Bzlmod compatible. However, there are other Bzlmod incompatibilities and related breakages that module extensions alone can't fix, such as forbidden API usage or Windows path length errors.

This post shows you how to patch your dependencies and covers several situations where patching is the only solution. We'll describe how to create and apply patches for your dependencies, if you can't wait for upstream fixes (or contribute them yourself).

Migrating to Bazel Modules (a.k.a. Bzlmod) - Module Extensions

So far, we've covered relatively easy Bzlmod fixes, how to hold runfiles and pkg_tar correctly, and how to access canonical repo names when absolutely necessary. Now we'll discuss replacing WORKSPACE statements with your own module extensions. You can use them to wrap your project's setup macros, and to adapt external repositories that aren't Bzlmod compatible to work with your Bzlmodified project.

Migrating to Bazel Modules (a.k.a. Bzlmod) - Repo Names, Macros, and Variables

The previous two posts in this series showed how to use runfiles mechanisms and rules_pkg mechanisms to avoid dealing with canonical repository names under Bzlmod. However, one special case remains: when you need to depend on the name of a repository directory, either at build time or runtime. This post explains how to access canonical repository names in a portable way to solve such problems. We'll use a macro when we can, and a custom Make Variable when we can't, including when dealing with alias targets.

Migrating to Bazel Modules (a.k.a. Bzlmod) - Repo Names and rules_pkg

The previous post in our Bzlmod migration series demonstrated how to make runfiles paths portable to a Bzlmod world. Another common source of Bzlmod file path breakages are misconfigured rules from rules_pkg, which contains rules for building archives from build outputs and/or external repositories. This post will explain key details of some of these rules, so you can stop "holding it wrong" and easily migrate archive targets to Bzlmod.

Migrating to Bazel Modules (a.k.a. Bzlmod) - Repo Names and Runfiles

The first post in our Bzlmod migration series explained many of the problems that may arise when migrating your project. These next three posts will explore various solutions to problems arising from changes in how Bazel handles repository names under Bzlmod, beginning with runfiles paths. After applying the techniques in this post, your project should be well insulated from runfiles path related breakages, now and well into the future.