SYNOPSIS
--------
-**FileCheck** *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*]
+:program:`FileCheck` *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*]
DESCRIPTION
-----------
-**FileCheck** reads two files (one from standard input, and one specified on the
-command line) and uses one to verify the other. This behavior is particularly
-useful for the testsuite, which wants to verify that the output of some tool
-(e.g. llc) contains the expected information (for example, a movsd from esp or
-whatever is interesting). This is similar to using grep, but it is optimized
-for matching multiple different inputs in one file in a specific order.
+:program:`FileCheck` reads two files (one from standard input, and one
+specified on the command line) and uses one to verify the other. This
+behavior is particularly useful for the testsuite, which wants to verify that
+the output of some tool (e.g. :program:`llc`) contains the expected information
+(for example, a movsd from esp or whatever is interesting). This is similar to
+using :program:`grep`, but it is optimized for matching multiple different
+inputs in one file in a specific order.
-The *match-filename* file specifies the file that contains the patterns to
-match. The file to verify is always read from standard input.
+The ``match-filename`` file specifies the file that contains the patterns to
+match. The file to verify is read from standard input unless the
+:option:`--input-file` option is used.
OPTIONS
-------
-**-help**
+.. option:: -help
Print a summary of command line options.
-**--check-prefix** *prefix*
+.. option:: --check-prefix prefix
- FileCheck searches the contents of *match-filename* for patterns to 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 **--check-prefix** argument allows you to specify
- a specific prefix to match.
+ FileCheck searches the contents of ``match-filename`` for patterns to
+ 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.
-**--input-file** *filename*
+.. option:: --input-file filename
File to check (defaults to stdin).
-**--strict-whitespace**
+.. option:: --strict-whitespace
By default, FileCheck canonicalizes input horizontal whitespace (spaces and
tabs) which causes it to ignore these differences (a space will match a tab).
- The **--strict-whitespace** argument disables this behavior.
+ The :option:`--strict-whitespace` argument disables this behavior. End-of-line
+ sequences are canonicalized to UNIX-style ``\n`` in all modes.
+.. option:: --implicit-check-not check-pattern
-**-version**
+ Adds implicit negative checks for the specified patterns between positive
+ checks. The option allows writing stricter tests without stuffing them with
+ ``CHECK-NOT``\ s.
+
+ For example, "``--implicit-check-not warning:``" can be useful when testing
+ diagnostic messages from tools that don't have an option similar to ``clang
+ -verify``. With this option FileCheck will verify that input does not contain
+ warnings not covered by any ``CHECK:`` patterns.
+
+.. option:: -version
Show the version number of this program.
EXIT STATUS
-----------
-If **FileCheck** verifies that the file matches the expected contents, it exits
-with 0. Otherwise, if not, or if an error occurs, it will exit with a non-zero
-value.
+If :program:`FileCheck` verifies that the file matches the expected contents,
+it exits with 0. Otherwise, if not, or if an error occurs, it will exit with a
+non-zero value.
TUTORIAL
--------
; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s
-
This syntax says to pipe the current file ("``%s``") into ``llvm-as``, pipe
that into ``llc``, then pipe the output of ``llc`` into ``FileCheck``. This
means that FileCheck will be verifying its standard input (the llc output)
ret void
}
-
Here you can see some "``CHECK:``" lines specified in comments. Now you can
see how the file is piped into ``llvm-as``, then ``llc``, and the machine code
output is what we are verifying. FileCheck checks the machine code output to
The FileCheck -check-prefix option
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The FileCheck ``-check-prefix`` option allows multiple test configurations to be
-driven from one .ll file. This is useful in many circumstances, for example,
-testing different architectural variants with llc. Here's a simple example:
+The FileCheck :option:`-check-prefix` option allows multiple test
+configurations to be driven from one `.ll` file. This is useful in many
+circumstances, for example, testing different architectural variants with
+:program:`llc`. Here's a simple example:
.. code-block:: llvm
newline between it and the previous directive. A "``CHECK-NEXT:``" cannot be
the first directive in a file.
+The "CHECK-SAME:" directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes you want to match lines and would like to verify that matches happen
+on the same line as the previous match. In this case, you can use "``CHECK:``"
+and "``CHECK-SAME:``" directives to specify this. If you specified a custom
+check prefix, just use "``<PREFIX>-SAME:``".
+
+"``CHECK-SAME:``" is particularly powerful in conjunction with "``CHECK-NOT:``"
+(described below).
+
+For example, the following works like you'd expect:
+
+.. code-block:: llvm
+
+ !0 = !DILocation(line: 5, scope: !1, inlinedAt: !2)
+
+ ; CHECK: !DILocation(line: 5,
+ ; CHECK-NOT: column:
+ ; CHECK-SAME: scope: ![[SCOPE:[0-9]+]]
+
+"``CHECK-SAME:``" directives reject the input if there are any newlines between
+it and the previous directive. A "``CHECK-SAME:``" cannot be the first
+directive in a file.
+
The "CHECK-NOT:" directive
~~~~~~~~~~~~~~~~~~~~~~~~~~
; CHECK: ret i8
}
+The "CHECK-DAG:" directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If it's necessary to match strings that don't occur in a strictly sequential
+order, "``CHECK-DAG:``" could be used to verify them between two matches (or
+before the first match, or after the last match). For example, clang emits
+vtable globals in reverse order. Using ``CHECK-DAG:``, we can keep the checks
+in the natural order:
+
+.. code-block:: c++
+
+ // RUN: %clang_cc1 %s -emit-llvm -o - | FileCheck %s
+
+ struct Foo { virtual void method(); };
+ Foo f; // emit vtable
+ // CHECK-DAG: @_ZTV3Foo =
+
+ struct Bar { virtual void method(); };
+ Bar b;
+ // CHECK-DAG: @_ZTV3Bar =
+
+``CHECK-NOT:`` directives could be mixed with ``CHECK-DAG:`` directives to
+exclude strings between the surrounding ``CHECK-DAG:`` directives. As a result,
+the surrounding ``CHECK-DAG:`` directives cannot be reordered, i.e. all
+occurrences matching ``CHECK-DAG:`` before ``CHECK-NOT:`` must not fall behind
+occurrences matching ``CHECK-DAG:`` after ``CHECK-NOT:``. For example,
+
+.. code-block:: llvm
+
+ ; CHECK-DAG: BEFORE
+ ; CHECK-NOT: NOT
+ ; CHECK-DAG: AFTER
+
+This case will reject input strings where ``BEFORE`` occurs after ``AFTER``.
+
+With captured variables, ``CHECK-DAG:`` is able to match valid topological
+orderings of a DAG with edges from the definition of a variable to its use.
+It's useful, e.g., when your test cases need to match different output
+sequences from the instruction scheduler. For example,
+
+.. code-block:: llvm
+
+ ; CHECK-DAG: add [[REG1:r[0-9]+]], r1, r2
+ ; CHECK-DAG: add [[REG2:r[0-9]+]], r3, r4
+ ; CHECK: mul r5, [[REG1]], [[REG2]]
+
+In this case, any order of that two ``add`` instructions will be allowed.
+
+If you are defining `and` using variables in the same ``CHECK-DAG:`` block,
+be aware that the definition rule can match `after` its use.
+
+So, for instance, the code below will pass:
+
+.. code-block:: llvm
+
+ ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]
+ ; CHECK-DAG: vmov.32 [[REG2]][1]
+ vmov.32 d0[1]
+ vmov.32 d0[0]
+
+While this other code, will not:
+
+.. code-block:: llvm
+
+ ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]
+ ; CHECK-DAG: vmov.32 [[REG2]][1]
+ vmov.32 d1[1]
+ vmov.32 d0[0]
+
+While this can be very useful, it's also dangerous, because in the case of
+register sequence, you must have a strong order (read before write, copy before
+use, etc). If the definition your test is looking for doesn't match (because
+of a bug in the compiler), it may match further away from the use, and mask
+real bugs away.
+
+In those cases, to enforce the order, use a non-DAG directive between DAG-blocks.
+
+The "CHECK-LABEL:" directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes in a file containing multiple tests divided into logical blocks, one
+or more ``CHECK:`` directives may inadvertently succeed by matching lines in a
+later block. While an error will usually eventually be generated, the check
+flagged as causing the error may not actually bear any relationship to the
+actual source of the problem.
+
+In order to produce better error messages in these cases, the "``CHECK-LABEL:``"
+directive can be used. It is treated identically to a normal ``CHECK``
+directive except that FileCheck makes an additional assumption that a line
+matched by the directive cannot also be matched by any other check present in
+``match-filename``; this is intended to be used for lines containing labels or
+other unique identifiers. Conceptually, the presence of ``CHECK-LABEL`` divides
+the input stream into separate blocks, each of which is processed independently,
+preventing a ``CHECK:`` directive in one block matching a line in another block.
+For example,
+
+.. code-block:: llvm
+
+ define %struct.C* @C_ctor_base(%struct.C* %this, i32 %x) {
+ entry:
+ ; CHECK-LABEL: C_ctor_base:
+ ; CHECK: mov [[SAVETHIS:r[0-9]+]], r0
+ ; CHECK: bl A_ctor_base
+ ; CHECK: mov r0, [[SAVETHIS]]
+ %0 = bitcast %struct.C* %this to %struct.A*
+ %call = tail call %struct.A* @A_ctor_base(%struct.A* %0)
+ %1 = bitcast %struct.C* %this to %struct.B*
+ %call2 = tail call %struct.B* @B_ctor_base(%struct.B* %1, i32 %x)
+ ret %struct.C* %this
+ }
+
+ define %struct.D* @D_ctor_base(%struct.D* %this, i32 %x) {
+ entry:
+ ; CHECK-LABEL: D_ctor_base:
+
+The use of ``CHECK-LABEL:`` directives in this case ensures that the three
+``CHECK:`` directives only accept lines corresponding to the body of the
+``@C_ctor_base`` function, even if the patterns match lines found later in
+the file. Furthermore, if one of these three ``CHECK:`` directives fail,
+FileCheck will recover by continuing to the next block, allowing multiple test
+failures to be detected in a single invocation.
+
+There is no requirement that ``CHECK-LABEL:`` directives contain strings that
+correspond to actual syntactic labels in a source or output language: they must
+simply uniquely match a single line in the file being verified.
+
+``CHECK-LABEL:`` directives cannot contain variable definitions or uses.
FileCheck Pattern Matching Syntax
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The "``CHECK:``" and "``CHECK-NOT:``" directives both take a pattern to match.
+All FileCheck directives take a pattern to match.
For most uses of FileCheck, fixed string matching is perfectly sufficient. For
some things, a more flexible form of matching is desired. To support this,
FileCheck allows you to specify regular expressions in matching strings,
It is often useful to match a pattern and then verify that it occurs again
later in the file. For codegen tests, this can be useful to allow any register,
-but verify that that register is used consistently later. To do this, FileCheck
-allows named variables to be defined and substituted into patterns. Here is a
-simple example:
+but verify that that register is used consistently later. To do this,
+:program:`FileCheck` allows named variables to be defined and substituted into
+patterns. Here is a simple example:
.. code-block:: llvm
The first check line matches a regex ``%[a-z]+`` and captures it into the
variable ``REGISTER``. The second line verifies that whatever is in
-``REGISTER`` occurs later in the file after an "``andw``". FileCheck variable
-references are always contained in ``[[ ]]`` pairs, and their names can be
-formed with the regex ``[a-zA-Z][a-zA-Z0-9]*``. If a colon follows the name,
+``REGISTER`` occurs later in the file after an "``andw``". :program:`FileCheck`
+variable references are always contained in ``[[ ]]`` pairs, and their names can
+be formed with the regex ``[a-zA-Z][a-zA-Z0-9]*``. If a colon follows the name,
then it is a definition of the variable; otherwise, it is a use.
-FileCheck variables can be defined multiple times, and uses always get the
-latest value. Note that variables are all read at the start of a "``CHECK``"
-line and are all defined at the end. This means that if you have something
-like "``CHECK: [[XYZ:.*]]x[[XYZ]]``", the check line will read the previous
-value of the ``XYZ`` variable and define a new one after the match is
-performed. If you need to do something like this you can probably take
-advantage of the fact that FileCheck is not actually line-oriented when it
-matches, this allows you to define two separate "``CHECK``" lines that match on
-the same line.
+:program:`FileCheck` variables can be defined multiple times, and uses always
+get the latest value. Variables can also be used later on the same line they
+were defined on. For example:
+
+.. code-block:: llvm
+ ; CHECK: op [[REG:r[0-9]+]], [[REG]]
+
+Can be useful if you want the operands of ``op`` to be the same register,
+and don't care exactly which register it is.
FileCheck Expressions
~~~~~~~~~~~~~~~~~~~~~
-
-Sometimes there's a need to verify output which refers line numbers of the match
-file, e.g. when testing compiler diagnostics. This introduces a certain
-fragility of the match file structure, as CHECK: lines contain absolute line
-numbers in the same file, which have to be updated whenever line numbers change
-due to text addition or deletion.
+Sometimes there's a need to verify output which refers line numbers of the
+match file, e.g. when testing compiler diagnostics. This introduces a certain
+fragility of the match file structure, as "``CHECK:``" lines contain absolute
+line numbers in the same file, which have to be updated whenever line numbers
+change due to text addition or deletion.
To support this case, FileCheck allows using ``[[@LINE]]``,
``[[@LINE+<offset>]]``, ``[[@LINE-<offset>]]`` expressions in patterns. These
projects / oota-llvm.git / blobdiff