Repository: bazelbuild/bazel
Issue: Document the exec_compatible_with attribute
Labels: type: documentation (cleanup)
P1
team-Configurability

We should document the `exec_compatible_with` attribute that can be used to influence the execution platform for a specific target.

Issue comments:
@spomorski, we have https://docs.bazel.build/versions/master/be/common-definitions.html, where should the `exec_compatible_with` attribute be documented? It can currently be used with any test rule, and shell rule, or genrule, but we may expand that set in the future.
I think that page is fine. You didn't mention build rules, does it work
with just test/shell/genrules (I might just be misunderstanding
shell/genrules)? If it works for build rules, let's just stick it in
"Attributes common to all build rules."

On Tue, Oct 30, 2018 at 3:24 PM katre <notifications@github.com> wrote:

> @spomorski <https://github.com/spomorski>, we have
> https://docs.bazel.build/versions/master/be/common-definitions.html,
> where should the exec_compatible_with attribute be documented? It can
> currently be used with any test rule, and shell rule, or genrule, but we
> may expand that set in the future.
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> <https://github.com/bazelbuild/bazel/issues/6558#issuecomment-434434630>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/AbdI8hfZz5YpyVNoQ1Ya7B5uzkbzbDRCks5uqKd7gaJpZM4YCrC7>
> .
>

Sorry, by shell rules I mean sh_library, sh_binary, and sh_test.

I'll start adding some documentation to the common definitions.

Pull request review comments:
"The" -> "A" and mention they're not the only ones. How about:

> A list of <...>constraint_values</...> that must be present in the execution platform for this target. This is in addition to any constraints already imposed by the rule type. Constraints are used to restrict the list of available execution platforms during <...>toolchain resolution</...>.
I'd remove "being configured", it's clear from context what target we're talking about. Even rule authors don't always know exactly what's entailed by the configuration phase or think in terms of "configured targets".
"that do not match these constraints" -- Arguably it's not just "the target's" constraints if we're talking about constraints specified by the rule as well.
Done.
Done.
Done.

Patch that resolved the issue:
diff --git a/site/docs/platforms.md b/site/docs/platforms.md
index 8935ebbff69e1d..4c3079e2b59e52 100644
--- a/site/docs/platforms.md
+++ b/site/docs/platforms.md
@@ -27,8 +27,7 @@ appropriate
 for build actions. Platforms can also be used in combination with the
 [config_setting](be/general.html#config_setting)
 rule to write
-  <a href="https://docs.bazel.build/versions/master/configurable-attributes.html">
-  configurable attributes</a>.
+<a href="configurable-attributes.html"> configurable attributes</a>.
 
 Bazel recognizes three roles that a platform may serve:
 
diff --git a/site/docs/toolchains.md b/site/docs/toolchains.md
index ac0e57b2f564af..94bab12b16097c 100644
--- a/site/docs/toolchains.md
+++ b/site/docs/toolchains.md
@@ -98,7 +98,7 @@ bar_binary(
 ```
 
 We can improve on this solution by using `select` to choose the `compiler`
-[based on the platform](https://docs.bazel.build/versions/master/configurable-attributes.html):
+[based on the platform](configurable-attributes.html):
 
 ```python
 config_setting(
@@ -207,7 +207,7 @@ To define some toolchains for a given toolchain type, we need three things:
    suite for different platforms.
 
 3. For each such target, an associated target of the generic
-[`toolchain`](https://docs.bazel.build/versions/master/be/platform.html#toolchain)
+[`toolchain`](be/platform.html#toolchain)
 rule, to provide metadata used by the toolchain framework.
 
 For our running example, here's a definition for a `bar_toolchain` rule. Our
@@ -361,33 +361,39 @@ This will end up building `//bar_tools:barc_linux` but not
 **Note:** Some Bazel rules do not yet support toolchain resolution.
 
 For each target that uses toolchains, Bazel's toolchain resolution procedure
-determines the target's concrete dependencies. The procedure takes as input a
-set of required toolchain types, the target platform, a list of available
-execution platforms, and a list of available toolchains. Its outputs are a
+determines the target's concrete toolchain dependencies. The procedure takes as input a
+set of required toolchain types, the target platform, the list of available
+execution platforms, and the list of available toolchains. Its outputs are a
 selected toolchain for each toolchain type as well as a selected execution
 platform for the current target.
 
 The available execution platforms and toolchains are gathered from the
 `WORKSPACE` file via
-[`register_execution_platforms`](https://docs.bazel.build/versions/master/skylark/lib/globals.html#register_execution_platforms)
+[`register_execution_platforms`](skylark/lib/globals.html#register_execution_platforms)
 and
-[`register_toolchains`](https://docs.bazel.build/versions/master/skylark/lib/globals.html#register_toolchains).
+[`register_toolchains`](skylark/lib/globals.html#register_toolchains).
 Additional execution platforms and toolchains may also be specified on the
 command line via
-[`--extra_execution_platforms`](https://docs.bazel.build/versions/master/command-line-reference.html#flag--extra_execution_platforms)
+[`--extra_execution_platforms`](command-line-reference.html#flag--extra_execution_platforms)
 and
-[`--extra_toolchains`](https://docs.bazel.build/versions/master/command-line-reference.html#flag--extra_toolchains).
+[`--extra_toolchains`](command-line-reference.html#flag--extra_toolchains).
 The host platform is automatically included as an available execution platform.
 Available platforms and toolchains are tracked as ordered lists for determinism,
-with preference given to earlier items in the list.
 
 The resolution steps are as follows.
 
-1. For each available execution platform, we associate each toolchain type with
+1. If the target specifies the
+   [`exec_compatible_with` attribute](be/common-definitions.html#common.exec_compatible_with)
+   (or the rule specifies the
+   [`exec_compatible_with` argument](skylark/lib/globals.html#rule.exec_compatible_with),
+   the list of available execution platforms is filtered to remove
+   any that do not match the execution constraints.
+
+2. For each available execution platform, we associate each toolchain type with
    the first available toolchain, if any, that is compatible with this execution
    platform and the target platform.
 
-2. Any execution platform that failed to find a compatible toolchain for one of
+3. Any execution platform that failed to find a compatible toolchain for one of
    its toolchain types is ruled out. Of the remaining platforms, the first one
    becomes the current target's execution platform, and its associated
    toolchains become dependencies of the target.
diff --git a/src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java b/src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java
index 03e711ebde9725..1ba093511c2c4c 100644
--- a/src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java
+++ b/src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java
@@ -48,6 +48,7 @@ public class PredefinedAttributes {
           "templates/attributes/common/deprecation.html",
           "templates/attributes/common/deps.html",
           "templates/attributes/common/distribs.html",
+          "templates/attributes/common/exec_compatible_with.html",
           "templates/attributes/common/features.html",
           "templates/attributes/common/licenses.html",
           "templates/attributes/common/restricted_to.html",
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_compatible_with.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_compatible_with.html
new file mode 100644
index 00000000000000..081830f21f4b15
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_compatible_with.html
@@ -0,0 +1,16 @@
+<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional</code></p>
+
+<p>
+A list of
+<code><a href="platform.html#constraint_value">constraint_values</a></code>
+that must be present in the execution platform for this target. This is in
+addition to any constraints already set by the rule type. Constraints are used
+to restrict the list of available execution platforms, see the description of
+<a href="../toolchains.html#toolchain-resolution">toolchain resolution</a> for
+details.
+</p>
+
+<p>
+This attribute is available only on <code><a href="general.html#genrule">genrule</a></code>,
+<a href="shell.html">shell rules</a>, and all test rules (*_test).
+</p>


Test patch: