Document the environment_group pseudo-rule and environment rule

[katre]

There is no documentation for either the environment_group pseudo-rule or the environment rule. environment appears to have one piece of documentation (for the fullfills attribute), but that can't be found because the overall rule isn't documented. environment_rule is implemented by a Starlark function and is explicitly called out as undocumented.

[katre]

Tagging @gregestren for context and history.

[gregestren]

This is fair. We've kept it undocumented because platforms should (I think) supplant most practical uses of this and we don't want too forked an API as we can help it.

But the cat's out of the bag already and we can clarify these relationships and best practices in the docs.

[shahms]

One thing that isn't covered by platforms but can be done with constraints (although awkwardly) is preventing a target from transitively depending on targets which are mutually exclusive (regardless of platform), e.g.

environment(name = "a-env")

environment(name = "b-env")

environment_group(
    name = "a_xor_b",
    defaults = [
        ":a-env",
        ":b-env",
    ],
    environments = [
        ":a-env",
        ":b-env",
    ],
)
cc_library(
    name = "a_lib",
    srcs = ["a.cc"],
    restricted_to = [":a-env"],
)

cc_library(
    name = "b_lib",
    srcs = ["b.cc"],
    restricted_to = [":b-env"],
)

cc_binary(
    name = "main",
    srcs = ["main.cc"],
    deps = select({
        ":env-a": [":a_lib"], # Succeeds.
        ":env-b": [":b_lib"], # Succeeds.
        "//conditions:default": [ # Fails.
            ":a_lib",
            ":b_lib",
        ],
    }),
)

There shouldn't be any need to define and use a new platform to express and enforce this kind of constraing.

[gregestren]

I acknowledge platforms don't solve all use cases naturally. Product features (like "free" vs. "premium") are a prominent counterexample.

In your above example, would a-env and b-env refer to anything in particular? What's the non-platform mutual exclusivity you're thinking?

[shahms]

This case came up internally specifically around avoiding known ODR violations at build time by declaring two libraries explicitly incompatible. A fairly niche case, to be sure, but considering the hard-to-debug breakages such issues can cause seemed potentially valuable to support.

[github-actions]

Thank you for contributing to the Bazel repository! This issue has been marked as stale since it has not had any activity in the last 1+ years. It will be closed in the next 90 days unless any other activity occurs. If you think this issue is still relevant and should stay open, please post any comment here and the issue will no longer be marked as stale.