Skip to content

bzlmod

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.

Migrating to Bazel Modules (a.k.a. Bzlmod) - The Easy Parts

You may be aware that Bazel will remove support for WORKSPACE in Bazel 9 in favor of Bazel Modules (a.k.a. Bzlmod). The current mainstream release is Bazel 7.2.0, so there's plenty of time to migrate. However, there's no time like the present to get started, to avoid further WORKSPACE dependencies and a pile of migration work in the future.

I recently completed the Bzlmod migration for EngFlow/example and our internal repos. This experience taught me a lot about Bzlmod and about migrating complex projects with challenging dependency issues that I'll share over a few blog posts. I'll also borrow from Sara Adams's earlier post, in which she described an example bzlmod migration based on EngFlow's Bazel Invocation Analyzer repo.