Add a warning that `$(SRCS)` and `$(OUTS)` are in fact not safe to interpolate into commands without processing.
The fix suggested here was necessary when a genrule consumed a target with a `'` in its name (which in a turn consumed a source file also with this character in its name).
There the approach used was:
```python
def _extract_makevar_array(name):
"""
Extracts the contents of the make variable `$(NAME)` into an array variable `$${NAME}`.
This makes it possible to correctly handle cases where `$(NAME)` contains special characters.
It probably still doesn't work if `$(NAME)` contains spaces.
"""
return """
mapfile %s <<< "$$(sed -e 's/ /\\n/g' <<'a_long_unique_identifier'
$(%s)
a_long_unique_identifier
)"
""" % (name, name)
```
and passing `cmd = _extract_makevar_array("SRCS") + """for F in "$${SRCS[@]}"; do echo $F; done"""`.
PiperOrigin-RevId: 688984848
Change-Id: I798372778e4b46252902731585cb0b55f1166f36
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/make-variables.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/make-variables.vm
index 5bc19b8..9e2fe53 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be/make-variables.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be/make-variables.vm
@@ -229,6 +229,24 @@
</li>
</ul>
+<p>
+ <b>Note:</b> If the filenames corresponding to the input labels or the output
+ filenames contain spaces, <code>'</code>, or other special characters (or your
+ genrule is part of a Starlark macro which downstream users may invoke on such
+ files), then <code>$(SRCS)</code> and <code>$(OUTS)</code> are not suitable
+ for interpolation into a command line, as they do not have the semantics that
+ <code>"${@}"</code> would in Bash.
+</p>
+<p>One workaround is to convert to a Bash array, with
+ <pre><code>mapfile SRCS <<< "$$(sed -e 's/ /\\n/g' <<'genrule_srcs_expansion'
+$(SRC)
+genrule_srcs_expansion
+)</code></pre>
+and then use <code>"$$\{SRCS[@]}"</code> in subsequent command lines in place
+of <code>$(SRCS)</code>. A more robust option is to write a Starlark rule
+instead.
+</p>
+
<h2 id="predefined_label_variables">Predefined source/output path variables</h2>
<p>
