From 8186fbb47ab964a9affa9a0fc6315fcdbde2b5aa Mon Sep 17 00:00:00 2001
From: Yuval Kaplan <yuvalk@gmail.com>
Date: Tue, 9 Mar 2021 13:32:16 -0800
Subject: [PATCH] Documentation for #13110

Closes #13167.

PiperOrigin-RevId: 361885312
---
 site/docs/exec-groups.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/site/docs/exec-groups.md b/site/docs/exec-groups.md
index f9a6bfb89d213d..3bcae707fa8755 100644
--- a/site/docs/exec-groups.md
+++ b/site/docs/exec-groups.md
@@ -132,6 +132,13 @@ 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
+
+The following execution groups are available for actions defined by native rules:
+
+* `test`: Test runner actions.
+* `cpp_link`: C++ linking actions.
+
 ### Creating exec groups to set exec properties
 
 Sometimes you want to use an exec group to give specific actions different exec
@@ -162,3 +169,36 @@ my_rule = rule(
 #
 ```
 
+### Execution groups and platform execution properties
+
+It is possible to define `exec_properties` for arbitrary execution groups on
+platform targets (unlike `exec_properties` set directly on a target, where
+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:
+
+```python
+constraint_setting(name = "resource")
+constraint_value(name = "has_resource", constraint_setting = ":resource")
+
+platform(
+    name = "platform_with_resource",
+    constraint_values = [":has_resource"],
+    exec_properties = {
+        "test.resource": "...",
+    },
+)
+
+cc_test(
+    name = "my_test",
+    srcs = ["my_test.cc"],
+    exec_compatible_with = [":has_resource"],
+)
+```
+
+`exec_properties` defined directly on targets take precedence over those that
+are inherited from the execution platform.