From 3b4e5ec4df1532f41520256ce8817262c651f0b8 Mon Sep 17 00:00:00 2001
From: Alex Eagle <alex@aspect.dev>
Date: Mon, 28 Nov 2022 04:33:17 -0800
Subject: [PATCH] genrule doc points to run_binary

Many new usages of `genrule` should be avoided, as `run_binary` says:
> Runs a binary as a build action. This rule does not require Bash (unlike native.genrule()).

Even when `genrule` starts hermetic, it's easy to accidentally grow into a longer bash script after subsequent changes.

Closes #16779.

PiperOrigin-RevId: 491308775
Change-Id: I92df653e3a8a4c592d9fc8e5bc7497eda71789a4
---
 .../build/lib/bazel/rules/genrule/BazelGenRuleRule.java    | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/genrule/BazelGenRuleRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/genrule/BazelGenRuleRule.java
index 2170f8602e9160..93ac4085df4581 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/genrule/BazelGenRuleRule.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/genrule/BazelGenRuleRule.java
@@ -70,6 +70,13 @@ public RuleDefinition.Metadata getMetadata() {
   to the existing <code>cc_*</code> rules, because all the heavy lifting has already been done
   for you.
 </p>
+<p>
+  Note that genrule requires a shell to interpret the command argument.
+  It is also easy to reference arbitrary programs available on the PATH, however this makes the
+  command non-hermetic and may not be reproducible.
+  If you only need to run a single tool, consider using
+  <a href="https://github.com/bazelbuild/bazel-skylib/blob/main/docs/run_binary_doc.md">run_binary</a>
+  instead.
 <p>
   Do not use a genrule for running tests. There are special dispensations for tests and test
   results, including caching policies and environment variables. Tests generally need to be run