Make tools in action inputs an error.

Supporting tools in inputs introduces a slow linear scan. Such tools should be moved to the 'tools' attribute. If --incompatible_no_support_tools_in_action_inputs is set the inputs are scanned, but a helpful error message is issued to the user.

Eventually we will remove the slow scanning. Errors will surface in the execution phase instead of during analysis, and the resulting error messages will be less obvious.

RELNOTES: None
RELNOTES[INC]: With --incompatible_no_support_tools_in_action_inputs enabled, Skylark action inputs are no longer scanned for tools. Move any such inputs to the newly introduced 'tools' attribute.
PiperOrigin-RevId: 198996093

1 files changed, 39 insertions, 0 deletions

diff --git a/site/docs/skylark/backward-compatibility.md b/site/docs/skylark/backward-compatibility.md
index f6fe1e51f8..aac35278ce 100644
--- a/site/docs/skylark/backward-compatibility.md
+++ b/site/docs/skylark/backward-compatibility.md
@@ -45,6 +45,7 @@ guarded behind flags in the current release:
 *   [Remove native git repository](#remove-native-git-repository)
 *   [Remove native http archive](#remove-native-http-archive)
 *   [New-style JavaInfo constructor](#new-style-java_info)
+*   [Disallow tools in action inputs](#disallow-tools-in-action-inputs)
 
 
 ### Dictionary concatenation
@@ -349,4 +350,42 @@ provider = JavaInfo(
 )
 ```
 
+### Disallow tools in action inputs
+
+A tool is an input coming from an attribute of type `label`
+where the attribute has been marked `executable = True`. In order for an action
+to run a tool, it needs access to its runfiles.
+
+Under the old API, tools are passed to `ctx.actions.run()` and
+`ctx.actions.run_shell()` via their `inputs` parameter. Bazel scans this
+argument (which may be a large depset) to find all the inputs that are tools,
+and adds their runfiles automatically.
+
+In the new API, tools are instead passed to a dedicated `tools` parameter. The
+`inputs` are not scanned. If a tool is accidentally put in `inputs` instead of
+`tools`, the action will fail during the execution phase with an error due to
+missing runfiles. This may be somewhat cryptic.
+
+To support a gradual transition, all actions with a `tools` argument are opted
+into the new API, while all actions without a `tools` argument still follow the
+old one. In the future (when this flag is removed), all actions will use the new
+API unconditionally.
+
+This flag turns on a safety check that is useful for migrating existing code.
+The safety check applies to all actions that do not have a `tools` argument. It
+scans the `inputs` looking for tools, and if it finds any, it raises an error
+during the analysis phase that clearly identifies the offending tools.
+
+In the rare case that your action requires a tool as input, but does not
+actually run the tool and therefore does not need its runfiles, the safety check
+will fail even though the action would have succeeded. In this case, you can
+bypass the check by adding a (possibly empty) `tools` argument to your action.
+Note that once an action has been modified to take a `tools` argument, you will
+no longer get helpful analysis-time errors for any remaining tools that should
+have been migrated from `inputs`.
+
+
+*   Flag: `--incompatible_no_support_tools_in_action_inputs`
+*   Default: `false`
+
 <!-- Add new options here -->