diff options
Diffstat (limited to 'llvm/docs/CommandGuide/FileCheck.rst')
-rw-r--r-- | llvm/docs/CommandGuide/FileCheck.rst | 73 |
1 files changed, 70 insertions, 3 deletions
diff --git a/llvm/docs/CommandGuide/FileCheck.rst b/llvm/docs/CommandGuide/FileCheck.rst index 55fc3f0..7d9a69e 100644 --- a/llvm/docs/CommandGuide/FileCheck.rst +++ b/llvm/docs/CommandGuide/FileCheck.rst @@ -39,15 +39,31 @@ and from the command line. match. By default, these patterns are prefixed with "``CHECK:``". If you'd like to use a different prefix (e.g. because the same input file is checking multiple different tool or options), the - :option:`--check-prefix` argument allows you to specify one or more - prefixes to match. Multiple prefixes are useful for tests which might - change for different run options, but most lines remain the same. + :option:`--check-prefix` argument allows you to specify (without the trailing + "``:``") one or more prefixes to match. Multiple prefixes are useful for tests + which might change for different run options, but most lines remain the same. + + FileCheck does not permit duplicate prefixes, even if one is a check prefix + and one is a comment prefix (see :option:`--comment-prefixes` below). .. option:: --check-prefixes prefix1,prefix2,... An alias of :option:`--check-prefix` that allows multiple prefixes to be specified as a comma separated list. +.. option:: --comment-prefixes prefix1,prefix2,... + + By default, FileCheck ignores any occurrence in ``match-filename`` of any check + prefix if it is preceded on the same line by "``COM:``" or "``RUN:``". See the + section `The "COM:" directive`_ for usage details. + + These default comment prefixes can be overridden by + :option:`--comment-prefixes` if they are not appropriate for your testing + environment. However, doing so is not recommended in LLVM's LIT-based test + suites, which should be easier to maintain if they all follow a consistent + comment style. In that case, consider proposing a change to the default + comment prefixes instead. + .. option:: --input-file filename File to check (defaults to stdin). @@ -236,6 +252,57 @@ circumstances, for example, testing different architectural variants with In this case, we're testing that we get the expected code generation with both 32-bit and 64-bit code generation. +The "COM:" directive +~~~~~~~~~~~~~~~~~~~~ + +Sometimes you want to disable a FileCheck directive without removing it +entirely, or you want to write comments that mention a directive by name. The +"``COM:``" directive makes it easy to do this. For example, you might have: + +.. code-block:: llvm + + ; X32: pinsrd_1: + ; X32: pinsrd $1, 4(%esp), %xmm0 + + ; COM: FIXME: X64 isn't working correctly yet for this part of codegen, but + ; COM: X64 will have something similar to X32: + ; COM: + ; COM: X64: pinsrd_1: + ; COM: X64: pinsrd $1, %edi, %xmm0 + +Without "``COM:``", you would need to use some combination of rewording and +directive syntax mangling to prevent FileCheck from recognizing the commented +occurrences of "``X32:``" and "``X64:``" above as directives. Moreover, +FileCheck diagnostics have been proposed that might complain about the above +occurrences of "``X64``" that don't have the trailing "``:``" because they look +like directive typos. Dodging all these problems can be tedious for a test +author, and directive syntax mangling can make the purpose of test code unclear. +"``COM:``" avoids all these problems. + +A few important usage notes: + +* "``COM:``" within another directive's pattern does *not* comment out the + remainder of the pattern. For example: + + .. code-block:: llvm + + ; X32: pinsrd $1, 4(%esp), %xmm0 COM: This is part of the X32 pattern! + + If you need to temporarily comment out part of a directive's pattern, move it + to another line. The reason is that FileCheck parses "``COM:``" in the same + manner as any other directive: only the first directive on the line is + recognized as a directive. + +* For the sake of LIT, FileCheck treats "``RUN:``" just like "``COM:``". If this + is not suitable for your test environment, see :option:`--comment-prefixes`. + +* FileCheck does not recognize "``COM``", "``RUN``", or any user-defined comment + prefix as a comment directive if it's combined with one of the usual check + directive suffixes, such as "``-NEXT:``" or "``-NOT:``", discussed below. + FileCheck treats such a combination as plain text instead. If it needs to act + as a comment directive for your test environment, define it as such with + :option:`--comment-prefixes`. + The "CHECK-NEXT:" directive ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |