[FileCheck] Fix up -dump-input* docs

In FileCheck.rst, add `-dump-input-context` and `-dump-input-filter`,
and fix some `-dump-input` documentation.

In `FileCheck -help`, `cl::value_desc("kind")` is being ignored for
`-dump-input-filter`, so just drop it.

Extend `-dump-input=help` to mention FILECHECK_OPTS.
This commit is contained in:
Joel E. Denny 2020-07-10 17:13:25 -04:00
parent ec2f2cec76
commit 6dda6ff0e0
2 changed files with 43 additions and 11 deletions

View File

@ -103,11 +103,37 @@ and from the command line.
-verify``. With this option FileCheck will verify that input does not contain
warnings not covered by any ``CHECK:`` patterns.
.. option:: --dump-input <mode>
.. option:: --dump-input <value>
Dump input to stderr, adding annotations representing currently enabled
diagnostics. Do this either 'always', on 'fail' (default), or 'never'.
Specify 'help' to explain the dump format and quit.
diagnostics. When there are multiple occurrences of this option, the
``<value>`` that appears earliest in the list below has precedence. The
default is ``fail``.
* ``help`` - Explain input dump and quit
* ``always`` - Always dump input
* ``fail`` - Dump input on failure
* ``never`` - Never dump input
.. option:: --dump-input-context <N>
In the dump requested by ``--dump-input``, print ``<N>`` input lines before
and ``<N>`` input lines after any lines specified by ``--dump-input-filter``.
When there are multiple occurrences of this option, the largest specified
``<N>`` has precedence. The default is 5.
.. option:: --dump-input-filter <value>
In the dump requested by ``--dump-input``, print only input lines of kind
``<value>`` plus any context specified by ``--dump-input-context``. When
there are multiple occurrences of this option, the ``<value>`` that appears
earliest in the list below has precedence. The default is ``error`` when
``--dump-input=fail``, and it's ``all`` when ``--dump-input=always``.
* ``all`` - All input lines
* ``annotation-full`` - Input lines with annotations
* ``annotation`` - Input lines with starting points of annotations
* ``error`` - Input lines with starting points of error annotations
.. option:: --enable-var-scope
@ -137,15 +163,15 @@ and from the command line.
.. option:: -v
Print good directive pattern matches. However, if ``-input-dump=fail`` or
``-input-dump=always``, add those matches as input annotations instead.
Print good directive pattern matches. However, if ``-dump-input=fail`` or
``-dump-input=always``, add those matches as input annotations instead.
.. option:: -vv
Print information helpful in diagnosing internal FileCheck issues, such as
discarded overlapping ``CHECK-DAG:`` matches, implicit EOF pattern matches,
and ``CHECK-NOT:`` patterns that do not have matches. Implies ``-v``.
However, if ``-input-dump=fail`` or ``-input-dump=always``, just add that
However, if ``-dump-input=fail`` or ``-dump-input=always``, just add that
information as input annotations instead.
.. option:: --allow-deprecated-dag-overlap

View File

@ -140,12 +140,11 @@ enum DumpInputFilterValue {
static cl::list<DumpInputFilterValue> DumpInputFilters(
"dump-input-filter",
cl::desc("In the dump requested by -dump-input, print only input lines of\n"
"kind <kind> plus any context specified by -dump-input-context.\n"
"When there are multiple occurrences of this option, the <kind>\n"
"kind <value> plus any context specified by -dump-input-context.\n"
"When there are multiple occurrences of this option, the <value>\n"
"that appears earliest in the list below has precedence. The\n"
"default is 'error' when -dump-input=fail, and it's 'all' when\n"
"-dump-input=always.\n"),
cl::value_desc("kind"),
cl::values(clEnumValN(DumpInputFilterAll, "all", "All input lines"),
clEnumValN(DumpInputFilterAnnotationFull, "annotation-full",
"Input lines with annotations"),
@ -226,14 +225,21 @@ static void DumpInputAnnotationHelp(raw_ostream &OS) {
<< "explain the input dump printed by FileCheck.\n"
<< "\n"
<< "Related command-line options:\n"
<< "\n"
<< " - -dump-input=<value> enables or disables the input dump\n"
<< " - -dump-input-filter=<kind> filters the input lines\n"
<< " - -dump-input-filter=<value> filters the input lines\n"
<< " - -dump-input-context=<N> adjusts the context of filtered lines\n"
<< " - -v and -vv add more annotations\n"
<< " - -color forces colors to be enabled both in the dump and below\n"
<< " - -help documents the above options in more detail\n"
<< "\n"
<< "Input dump annotation format:\n";
<< "These options can also be set via FILECHECK_OPTS. For example, for\n"
<< "maximum debugging output on failures:\n"
<< "\n"
<< " $ FILECHECK_OPTS='-dump-input-filter=all -vv -color' ninja check\n"
<< "\n"
<< "Input dump annotation format:\n"
<< "\n";
// Labels for input lines.
OS << " - ";