Starlarkify native Bazel flags

[gregestren]

Starlarkify native Bazel flags

Part of Bazel's Starlarkification roadmap to move core rules like Java, C++, Python from Bazel's source code to .bzl. That way rule maintainers can own them without having to accommodate Bazel's development and release workflows.

This proposal is for language-specific build flags like --javacopt. Qualifying flags are defined in Bazel's Java code but only consumed in rules_* .bzl files. From a domain perspective they should live where their consuming rule logic lives.

Lead reviewer @mai93 .

Tracking issues:

• Python (added Sep 8, 2025)

[Wyverald]

cc @meteorcloudy this would eventually allow us to remove protobuf from bazel_tools

[gregestren]

@bazelbuild/java-team @bazelbuild/google-rules-python-team @bazelbuild/python-team @bazelbuild/protobuf-team @bazelbuild/android @bazelbuild/rules_apple-team

CC'ing because Bazel has native-defined flags in your language's domain.

[rickeylev]

+1 to the idea.

How about an auto-loading type of thing to make the transition easier?

As a rule author, if I add my own flag definition, there's now two sources trying to dictate the same behavior, but I have no way to disambiguate which is supposed to be preferred (preferred = "which came later in the CLI ordering", probably).

Proposal:

• An --autoload_flags arg (or equiv) causes --foo to map to @repo//whatever:foo
• Private API to answer the question of "was --foo used or --@repo//whatever:foo used?"

The first makes the transition easy on users. The second makes it possible for rules to use the correct value.

Follow a similar autoload rollout/semantics as was done for the core rules. IIRC:

• Phase 1: autoload_flags flag exists, you can opt-in if you want
• Phase 2: default behavior is autoload_flags flag cause --foo to map to @repo//whatever:foo. You can opt-out if you want
• Phase 3: Ability to opt-out removed, --foo always refers to @repo//whatever:foo
• Phase 4: Remove automatic mapping; users have to set their own flag alias using --flag_alias

---

Hm, is autoloading flags necessary if the "can detect which flag should be read" api is available? If that API is available, does this simply down to just: rules define flags and users expected to define flag alias; release rules; Bazel can then remove flag at leisure.

[gregestren]

Thanks for the feedback.

The proposal is intended to make all this seamless: across users, rule maintainers, and Bazel versions. And to provide enough toggles where anyone can override behavior but by default they don't even have to know this is going on (well, users at least - rule maintainers of course have to know!)

Your suggestion models it a bit differently. I'll think more if the proposed model misses any points there and update accordingly.

[rickeylev]

Oh, oops, I'm sorry, I totally skipped over that first link and didn't realize there was a link to an entire design doc! I gave it a quick read and I think it covers the same points I brought up. Thanks!

[gregestren]

The only part of Starlarkify native Bazel flags I'm still concerned about is Starlark API migration, i.e. ctx.fragments.<lang>.

Premise (discussed on proposal): We shouldn't force existing .bzl code to upgrade. Because transitive dependency upgrades are a pain.

That means:

1. select() on --javacopt should still work even when --javacopt is an alias for some Starlark flag. Bazel already supports this.
2. Same for transitions on //command_line_option:javacopt. Not yet supported but should be a straightforward Bazel patch
3. ctx.fragments.lang.foo should change to a direct reference to the related Starlark flag

3 is what I worry about. ctx.fragments.lang.foo is principally an alias mapping just like 1. and 2. But it's not as straightforward as native flag -> Starlark flag and the proposed MODULE.bazel flag_alias function doesn't cover it.

So what do we do when Bazel 9 flips use Starlark flags but depends on some transitive module with ctx.fragments.lang.foo, which references the now-outdated native flag?

1. Release a new module version that version-checks Bazel and routes Bazel 9+ to the Starlark reference, earlier Bazels to the native reference. All Bazel 9 users must use the new version module.
2. Make Bazel 9 capable of using the Starlark flag but don't default that to on until everything is upgraded.
3. Extend flag_alias somehow to support this mapping.
4. Hard-code a simple mapping in Bazel 9's code base and apply that.

I'd like to think 1. can work but I worry that updating modules isn't always straightforward and can bog us down. 2. risks a partial migration that lingers forever. 3's a bit awkward.

I'm most tempted by 4 but open to any good ideas.