[FileCheck] Make FILECHECK_OPTS useful for its test suite

Without this patch, `FILECHECK_OPTS` isn't propagated to FileCheck's
test suite so that `FILECHECK_OPTS` doesn't inadvertently affect test
results by affecting the output of FileCheck calls under test.  As a
result, `FILECHECK_OPTS` is useless for debugging FileCheck's test
suite.

In `llvm/test/FileCheck/lit.local.cfg`, this patch provides a new
subsitution, `%ProtectFileCheckOutput`, to address this problem for
both `FILECHECK_OPTS` and the deprecated
`FILECHECK_DUMP_INPUT_ON_FAILURE`.  The rest of the patch uses
`%ProtectFileCheckOutput` throughout the test suite

Fixes PR40284.

Reviewed By: probinson, thopre

Differential Revision: https://reviews.llvm.org/D65121

1 files changed, 7 insertions, 0 deletions

diff --git a/llvm/docs/TestingGuide.rst b/llvm/docs/TestingGuide.rst
index f147a9fbd7a..7216c7c838e 100644
--- a/llvm/docs/TestingGuide.rst
+++ b/llvm/docs/TestingGuide.rst
@@ -549,6 +549,13 @@ RUN lines:
    ``i686-pc-mingw32``. This allows a test to run with a specific ABI without
    constraining it to a specific triple.
 
+**FileCheck-specific substitutions:**
+
+``%ProtectFileCheckOutput``
+   This should precede a ``FileCheck`` call if and only if the call's textual
+   output affects test results.  It's usually easy to tell: just look for
+   redirection or piping of the ``FileCheck`` call's stdout or stderr.
+
 To add more substituations, look at ``test/lit.cfg`` or ``lit.local.cfg``.