This tutorial will focus on how to take a bazel rule set and migrate to using bzlmod. Significant differences and capabilities exist between using a WORKSPACE file and using bzlmod and MODULE.bazel.
Rough draft outline:
Introduction
introduction to bzlmod and differences between WORKSPACE and MODULE.bazel.
Migrating to bzlmod
bzlmod extensions
passing values between extensions
introduction to module_extension and tag_classes
hub-spoke pattern
toolchain registration
doing internal toolchain registrations
dealing with sub-modules registering toolchains
managing rule set dependencies
introduction to how looping through module_ctx.modules works
cover best practices, such as putting a single module within a single bzl file.
document how to deploy your ruleset to the bazel-central-registry
writing examples and documentation
Complexities with bzlmod
unsupported native calls in bzlmod - native.register_toolchains
debugging bzlmod code by running specific targets
folder layout differences inside of the cache
introduction to migrating from using load statements in your WORKSPACE file to using an extension and MODULES.bzlmod.
detecting when you are running with bzlmod vs. a WORKSPACE
dealing with sub-modules overriding ruleset values
Empty WORKSPACE file
WORKSPACE.bzlmod to prevent leaking dependencies
Why not include code in WORKSPACE.bzlmod
use_repo names that are created and then used. How the naming creates a repo
repo name collision with repo creation
maintaining two different code bases for WORKSPACE and bzlmod.
@alexeagle @meteorcloudy @rickeylev - any guidance is appreciated!
Yeah, that all sounds like a good introduction to creating your own bzlmod-based project.
Something I don't see explicitly mentioned is:
Visibility. This is a part of bzlmod that took me awhile to get a handle on. (I'm not sure I entirely do, still :sweat_smile:, but enough to understand errors enough usually)
Apparent vs canonical repos: when you should or shouldn't use one or the other. A common thing I saw with initial bzlmod work was trying to use canonical repo names more than necessary. Visibility issues go away once you have the canonical name, but doing that probably causes issues in some other context.
The upcoming isolated=True parameter of use_extension, maybe? @fmeum
This tutorial will focus on how to take a bazel rule set and migrate to using bzlmod. Significant differences and capabilities exist between using a WORKSPACE file and using bzlmod and MODULE.bazel.
Rough draft outline:
Introduction
Migrating to bzlmod
module_extension
andtag_classes
module_ctx.modules
worksComplexities with bzlmod
native.register_toolchains
load
statements in your WORKSPACE file to using an extension and MODULES.bzlmod.use_repo
names that are created and then used. How the naming creates a repo@alexeagle @meteorcloudy @rickeylev - any guidance is appreciated!