Supporting Bzlmod

[zachgrayio]

With the new bzlmod changes coming down the pike in 5.0, it seems this SIG might serve as a good centralized location to collaborate on getting the third-party rulesets onboarded. It will be gated behind a flag, but I am assuming the majority of the community will want to opt into this one, and Bazel itself already landed support for this. Anecdotally I've already heard folks in the community lamenting the fact it might take years for rulesets they depend on to support the new module system, so maybe we can do something to enable them to assist on making this happen?

I assume creating the metadata to PR to BCR is fairly easy but I know there's some other potential breaking changes around canonical names, and probably some other stuff to pay attention to regarding version support etc.

I think the following items might be useful:

1. track "bzlmod support" across the various ruleset repos centrally here somewhere (but don't recreate anything BCR does; maybe there's an existing tracking item for that somewhere? 🤷 ) of course one can browse the BCR module source tree but this isnt ideal
2. create a runbook of sorts to ease in adoption of bzlmod by ruleset authors and contributors
3. most important imo: use the SIG to match potential contributors to rulesets to get this work done in the event there's some heavy lifting required
4. share common tooling - BCR has a helper script to dump out metadata for a module, but this may be something that should be automated in CI as part of a release process, and across all the various ruleset repos. and then there's the version support testing of course, probably something to share here too
5. use a discussion under the SIG to centralize common roadblocks/solutions to adopting bzlmod for rulesets since the issues here are likely a bit different from the ones faced by end users who should be raising issues direclty in bazelbuild/bazel and various rulesets if necessary. This may be useful for collectively interacting with the core team on issues with bzlmod if there's common issues/concerns hitting third-party rules maintainers
6. What else??

[keith]

💯 I think getting some solid community testing on this feature would help validate it, and ideally help roll it out as quickly as possible if we could iron out any issues. I think a quick "here's the way to opt in guide would be great, but also that would ideally live in the bazel docs.

[zachgrayio]

yeah true, a "for rules authors" heading in the bzlmod user guide would make sense, should probably be an artifact of any work done here

[meteorcloudy]

@zachgrayio Hi, Zach. I recently added Bzlmod support for rules_java. We'll add more docs for migration soon. In the meantime you can check the rules_java PR and some issues we've found.

Feedback is welcomed, we can still make necessary changes to Bzlmod if something doesn't work well.

[zachgrayio]

👍 cool, yeah I was looking at that diff as well. I guess for most third-party rules it should be a smaller changeset as there's not this issue with moving code around from @bazel_tools.

That's a great issue filter, should pin that somewhere here too and make sure we get that tag applied to issues we come across.

[meteorcloudy]

@zachgrayio Thanks for starting this thread!

1. track "bzlmod support" across the various ruleset repos centrally here somewhere (but don't recreate anything BCR does; maybe there's an existing tracking item for that somewhere? 🤷 ) of course one can browse the BCR module source tree but this isnt ideal

This will be very helpful! I was thinking that we could even track all available modules in the BCR, like all available versions and their compatibility with Bazel, etc. If the community can help build this, that would be great!

2. create a runbook of sorts to ease in adoption of bzlmod by ruleset authors and contributors

Yes, more docs on migration will come.

3. most important imo: use the SIG to match potential contributors to rulesets to get this work done in the event there's some heavy lifting required

Sounds great!

4. share common tooling - BCR has a helper script to dump out metadata for a module, but this may be something that should be automated in CI as part of a release process, and across all the various ruleset repos. and then there's the version support testing of course, probably something to share here too

Tooling can definitely be improved, PRs are welcomed! Implementing the downstream and Bazel compatibility test pipelines are on my to-do list.

5. use a discussion under the SIG to centralize common roadblocks/solutions to adopting bzlmod for rulesets since the issues here are likely a bit different from the ones faced by end users who should be raising issues direclty in bazelbuild/bazel and various rulesets if necessary. This may be useful for collectively interacting with the core team on issues with bzlmod if there's common issues/concerns hitting third-party rules maintainers

Sounds good, feel free to also file issues to bazelbuild/bazel for any Bzlmod issues and ping @meteorcloudy and @Wyverald. We are also planning regular sync meetings with the community.

[jsharpe]

One of the open questions I have in thinking about how rules_foreign_cc might work in bzlmod is how a user should select which specific implementation of a toolchain should be used. I think the answer is going to be a specific constraint on the execution platform to select the right tool e.g. cmake built from source vs a binary distribution.

The other way would be to not have any registered toolchains at all in rules_foreign_cc but provide separate packages that provide the different configurations e.g. built_cmake_tool or native_cmake_tool and have the user select the set of instances of toolchains they want to use by depending on the tool implementation modules?

[aherrmann]

One of the open questions I have in thinking about how rules_foreign_cc might work in bzlmod is how a user should select which specific implementation of a toolchain should be used. I think the answer is going to be a specific constraint on the execution platform to select the right tool e.g. cmake built from source vs a binary distribution.

I agree, this is an important question. Thinking about rules_nixpkgs, the constraints alone are not always sufficient to pick the correct toolchain. The order in which they are declared matters too. I'll give an example:

The default CC toolchain generated by rules_cc on Linux has the constraints:

  '@platforms//cpu:x86_64',
  '@platforms//os:linux',

The CC toolchain generated by rules_nixpkgs on Linux has the constraints:

  "@platforms//cpu:x86_64",
  "@platforms//os:linux",
  "@io_tweag_rules_nixpkgs//nixpkgs/constraints:support_nix"

I.e. the rules_nixpkgs one has tighter constraints, the rules_cc one is broader.

In the current world we're careful to always configure the rules_nixpkgs toolchain before the rules_cc toolchain. Bazel's toolchain resolution will pick the first toolchain that matches the given constraints. So, if the rules_cc one were registered first, it would always be picked in favor of the rules_nixpkgs one. By registering the rules_nixpkgs one first, Bazel will pick it if the support_nix constraint is provided by the current platform and otherwise fall through to the rules_cc one.

If toolchain registration is tied to the Bazel module definition and thereby to the order imposed by the dependency graph, then the user looses control over the order in which toolchains are registered. This may cause situations where a toolchain that a user wants is unavailable.

[meteorcloudy]

We register the toolchains in BFS order, which means the toolchains registered in user's MODULE.bazel file are preferred. Isn't this enough? /cc @Wyverald

[aherrmann]

@meteorcloudy Thanks for clarifying. Indeed, that sounds like the user would have enough control to fix up issues by manually overriding any problematic registered toolchain from a dependency. It also sounds like rule sets could override toolchains from their dependencies. E.g. rules_nixpkgs could register a cc-toolchain that would take precedence over the toolchain registered by rules_cc.

[meteorcloudy]

Np! Feel free to try it out and add rules_nixpkgs into the BCR, let us know if anything doesn't work nicely.

[meteorcloudy]

Hi everyone, the first version of Bzlmod Migration Guide is finally ready! Please check https://docs.google.com/document/d/1JtXIVnXyFZ4bmbiBCr5gsTH4-opZAFf5DMMb-54kES0/edit?usp=sharing