Add 'toolchain' parameter to actions.{run,run_shell} (bazelbuild#16964)

If set, the action executes on a specific execution platform connected to this toolchain (not to the default exec group).

Design doc with more information: https://docs.google.com/document/d/1-rbP_hmKs9D639YWw5F_JyxPxL2bi6dSmmvj_WXak9M.

PiperOrigin-RevId: 493894090
Change-Id: Ieb928cec469c01879eebe6249ff1db5df1da0527

Co-authored-by: Googler <kotlaja@google.com>

src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkActionFactory.java

@@ -362,7 +362,8 @@ public void run(
       Object inputManifestsUnchecked,
       Object execGroupUnchecked,
       Object shadowedActionUnchecked,
-      Object resourceSetUnchecked)
+      Object resourceSetUnchecked,
+      Object toolchainUnchecked)
       throws EvalException {
     context.checkMutable("actions.run");
 
@@ -455,7 +456,8 @@ public void runShell(
       Object inputManifestsUnchecked,
       Object execGroupUnchecked,
       Object shadowedActionUnchecked,
-      Object resourceSetUnchecked)
+      Object resourceSetUnchecked,
+      Object toolchainUnchecked)
       throws EvalException {
     context.checkMutable("actions.run_shell");
     RuleContext ruleContext = getRuleContext();

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkActionFactoryApi.java

@@ -15,6 +15,7 @@
 package com.google.devtools.build.lib.starlarkbuildapi;
 
 import com.google.devtools.build.docgen.annot.DocCategory;
+import com.google.devtools.build.lib.cmdline.Label;
 import com.google.devtools.build.lib.collect.nestedset.Depset;
 import net.starlark.java.annot.Param;
 import net.starlark.java.annot.ParamType;
@@ -457,6 +458,25 @@ void symlink(
                     + " <code>--experimental_action_resource_set</code> is false, the default"
                     + " values are used.<p>The callback must be top-level (lambda and nested"
                     + " functions aren't allowed)."),
+        @Param(
+            name = "toolchain",
+            allowedTypes = {
+              @ParamType(type = Label.class),
+              @ParamType(type = String.class),
+              @ParamType(type = NoneType.class),
+            },
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc =
+                "<p>Toolchain type of the executable or tools used in this action. The parameter"
+                    + " must be set, so that, the action executes on the correct execution"
+                    + " platform. </p><p>It's a no-op right now, but we recommend to set it when a"
+                    + " toolchain is used, because it will be required in the future Bazel"
+                    + " releases.</p><p>Note that the rule which creates this action needs to"
+                    + " define this toolchain inside its 'rule()' function.</p><p>When `toolchain`"
+                    + " and `exec_group` parameters are both set, `exec_group` will be used. An"
+                    + " error is raised in case the `exec_group` doesn't specify the same."),
       })
   void run(
       Sequence<?> outputs,
@@ -473,7 +493,8 @@ void run(
       Object inputManifestsUnchecked,
       Object execGroupUnchecked,
       Object shadowedAction,
-      Object resourceSetUnchecked)
+      Object resourceSetUnchecked,
+      Object toolchainUnchecked)
       throws EvalException;
 
   @StarlarkMethod(
@@ -674,6 +695,26 @@ void run(
             doc =
                 "A callback function for estimating resource usage if run locally. See"
                     + "<a href=\"#run.resource_set\"><code>ctx.actions.run()</code></a>."),
+        @Param(
+            name = "toolchain",
+            allowedTypes = {
+              @ParamType(type = Label.class),
+              @ParamType(type = String.class),
+              @ParamType(type = NoneType.class),
+            },
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc =
+                "<p>Toolchain type of the executable or tools used in this action. The parameter"
+                    + " must be set, so that, the action executes on the correct execution"
+                    + " platform. </p><p>It's a no-op right now, but we recommend to set it when a"
+                    + " toolchain is used, because it will be required in the future Bazel"
+                    + " releases.</p><p>Note that the rule which creates this action needs to"
+                    + " define this toolchain inside its 'rule()' function.</p><p>When `toolchain`"
+                    + " and `exec_group` parameters are both set, `exec_group` will be used. An"
+                    + " error is raised in case the `exec_group` doesn't specify the same."
+                    + " toolchain.</p>"),
       })
   void runShell(
       Sequence<?> outputs,
@@ -689,7 +730,8 @@ void runShell(
       Object inputManifestsUnchecked,
       Object execGroupUnchecked,
       Object shadowedAction,
-      Object resourceSetUnchecked)
+      Object resourceSetUnchecked,
+      Object toolchainUnchecked)
       throws EvalException;
 
   @StarlarkMethod(