Update docs after adding exec_group_compatible_with

In addition to documenting the new attribute, existing documented best practices around exec constraints also need to change.

Last part of #24964. Closes #24964.

PiperOrigin-RevId: 722710541
Change-Id: I92d957311e911899070830eaa867484917b4acae

site/en/extending/exec-groups.md

@@ -100,6 +100,13 @@ that execution group in the action declaration, that may potentially cause
 issues. A mismatch like this may not immediately cause failures, but is a latent
 problem.
 
+### Default execution groups {:#exec-groups-for-native-rules}
+
+The following execution groups are predefined:
+
+* `test`: Test runner actions, available on all test rules.
+* `cpp_link`: C++ linking actions.
+
 ## Using execution groups to set execution properties {:#using-exec-groups-for-exec-properties}
 
 Execution groups are integrated with the
@@ -126,12 +133,43 @@ All actions with `exec_group = "link"` would see the exec properties
 dictionary as `{"mem": "16g"}`. As you see here, execution-group-level
 settings override target-level settings.
 
-### Execution groups for native rules {:#exec-groups-for-native-rules}
+## Using execution groups to set platform constraints {:#using-exec-groups-for-platform-constraints}
 
-The following execution groups are available for actions defined by native rules:
+Execution groups are also integrated with the
+[`exec_compatible_with`](/reference/be/common-definitions#common-attributes) and
+[`exec_group_compatible_with`](/reference/be/common-definitions#common-attributes)
+attributes that exist on every rule and allow the target writer to specify
+additional constraints that must be satisfied by the execution platforms
+selected for the target's actions.
 
-* `test`: Test runner actions.
-* `cpp_link`: C++ linking actions.
+For example, if the rule `my_test` defines the `link` execution group in
+addition to the default and the `test` execution group, then the following
+usage of these attributes would run actions in the default execution group on
+a platform with a high number of CPUs, the test action on Linux, and the link
+action on the default execution platform:
+
+```python
+# BUILD
+constraint_setting(name = "cpu")
+constraint_value(name = "high_cpu", constraint_setting = ":cpu")
+
+platform(
+  name = "high_cpu_platform",
+  constraint_values = [":high_cpu"],
+  exec_properties = {
+    "cpu": "256",
+  },
+)
+
+my_test(
+    name = "my_test",
+    exec_compatible_with = ["//constraints:high_cpu"],
+    exec_group_compatible_with = {
+        "test": ["@platforms//os:linux"],
+    },
+    ...
+)
+```
 
 ### Execution groups and platform execution properties {:#platform-execution-properties}
 
@@ -141,17 +179,14 @@ properties for unknown execution groups are rejected). Targets then inherit the
 execution platform's `exec_properties` that affect the default execution group
 and any other relevant execution groups.
 
-For example, suppose running a C++ test requires some resource to be available,
-but it isn't required for compiling and linking; this can be modelled as
-follows:
+For example, suppose running tests on the exec platform requires some resource
+to be available, but it isn't required for compiling and linking; this can be
+modelled as follows:
 
 ```python
-constraint_setting(name = "resource")
-constraint_value(name = "has_resource", constraint_setting = ":resource")
-
+# BUILD
 platform(
-    name = "platform_with_resource",
-    constraint_values = [":has_resource"],
+    name = "exec_platform",
     exec_properties = {
         "test.resource": "...",
     },
@@ -160,7 +195,6 @@ platform(
 cc_test(
     name = "my_test",
     srcs = ["my_test.cc"],
-    exec_compatible_with = [":has_resource"],
 )
 ```
 

src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java

@@ -62,6 +62,7 @@ public class PredefinedAttributes {
           "templates/attributes/common/deprecation.html",
           "templates/attributes/common/distribs.html",
           "templates/attributes/common/exec_compatible_with.html",
+          "templates/attributes/common/exec_group_compatible_with.html",
           "templates/attributes/common/exec_properties.html",
           "templates/attributes/common/features.html",
           "templates/attributes/common/package_metadata.html",

src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_compatible_with.html

@@ -5,9 +5,14 @@
 <p>
 A list of
 <code><a href="platforms-and-toolchains.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. For more details, see
+that must be present in the execution platform of this target's default exec
+group. This is in addition to any constraints already set by the rule type.
+Constraints are used to restrict the list of available execution platforms.
+
+For more details, see
 the description of
   <a href="/docs/toolchains#toolchain-resolution">toolchain resolution</a>.
-  </p>
+  and
+  <a href="/extending/exec-groups">exec groups</a>
+
+</p>

src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_group_compatible_with.html

@@ -0,0 +1,18 @@
+<p>Dictionary of strings to lists of <a href="${link build-ref#labels}">labels</a>;
+  <a href="#configurable-attributes">nonconfigurable</a>; default is <code>{}</code>
+</p>
+
+<p>
+A dictionary of exec group names to lists of
+<code><a href="platforms-and-toolchains.html#constraint_value">constraint_values</a></code>
+that must be present in the execution platform for the given exec group. This
+is in addition to any constraints already set on the exec group's definition.
+Constraints are used to restrict the list of available execution platforms.
+
+For more details, see
+the description of
+  <a href="/docs/toolchains#toolchain-resolution">toolchain resolution</a>.
+  and
+  <a href="/extending/exec-groups">exec groups</a>
+
+</p>

src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_properties.html

@@ -3,3 +3,5 @@
 <p> A dictionary of strings that will be added to the <code>exec_properties</code> of a platform selected for this target. See <code>exec_properties</code> of the <a href="platforms-and-toolchains.html#platform">platform</a> rule.</p>
 
 <p>If a key is present in both the platform and target-level properties, the value will be taken from the target.</p>
+
+<p>Keys can be prefixed with the name of an execution group followed by a <code>.</code> to apply them only to that particular exec group.</p>