From d3aed7fc7986971ea15313871e7ffe8b4a5efa18 Mon Sep 17 00:00:00 2001 From: Dmitri Gribenko Date: Thu, 10 Oct 2019 14:27:14 +0000 Subject: Revert "[FileCheck] Implement --ignore-case option." This reverts commit r374339. It broke tests: http://lab.llvm.org:8011/builders/clang-x86_64-debian-fast/builds/19066 llvm-svn: 374359 --- llvm/docs/CommandGuide/FileCheck.rst | 1407 +++++++++++++++++----------------- 1 file changed, 701 insertions(+), 706 deletions(-) (limited to 'llvm/docs/CommandGuide/FileCheck.rst') diff --git a/llvm/docs/CommandGuide/FileCheck.rst b/llvm/docs/CommandGuide/FileCheck.rst index 7d8ecaa7bfa..e8b324d080d 100644 --- a/llvm/docs/CommandGuide/FileCheck.rst +++ b/llvm/docs/CommandGuide/FileCheck.rst @@ -1,706 +1,701 @@ -FileCheck - Flexible pattern matching file verifier -=================================================== - -.. program:: FileCheck - -SYNOPSIS --------- - -:program:`FileCheck` *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*] - -DESCRIPTION ------------ - -: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 read from standard input unless the -:option:`--input-file` option is used. - -OPTIONS -------- - -Options are parsed from the environment variable ``FILECHECK_OPTS`` -and from the command line. - -.. option:: -help - - Print a summary of command line options. - -.. 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 - :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-prefixes prefix1,prefix2,... - - An alias of :option:`--check-prefix` that allows multiple prefixes to be - specified as a comma separated list. - -.. option:: --input-file filename - - File to check (defaults to stdin). - -.. option:: --match-full-lines - - By default, FileCheck allows matches of anywhere on a line. This - option will require all positive matches to cover an entire - line. Leading and trailing whitespace is ignored, unless - :option:`--strict-whitespace` is also specified. (Note: negative - matches from ``CHECK-NOT`` are not affected by this option!) - - Passing this option is equivalent to inserting ``{{^ *}}`` or - ``{{^}}`` before, and ``{{ *$}}`` or ``{{$}}`` after every positive - check pattern. - -.. 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 :option:`--strict-whitespace` argument disables this behavior. End-of-line - sequences are canonicalized to UNIX-style ``\n`` in all modes. - -.. option:: --ignore-case - - By default, FileCheck uses case-sensitive matching. This option causes - FileCheck to use case-insensitive matching. - -.. option:: --implicit-check-not check-pattern - - 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:: --dump-input - - Dump input to stderr, adding annotations representing currently enabled - diagnostics. Do this either 'always', on 'fail', or 'never'. Specify 'help' - to explain the dump format and quit. - -.. option:: --dump-input-on-failure - - When the check fails, dump all of the original input. This option is - deprecated in favor of `--dump-input=fail`. - -.. option:: --enable-var-scope - - Enables scope for regex variables. - - Variables with names that start with ``$`` are considered global and - remain set throughout the file. - - All other variables get undefined after each encountered ``CHECK-LABEL``. - -.. option:: -D - - Sets a filecheck pattern variable ``VAR`` with value ``VALUE`` that can be - used in ``CHECK:`` lines. - -.. option:: -D#= - - Sets a filecheck numeric variable ``NUMVAR`` to the result of evaluating - ```` that can be used in ``CHECK:`` lines. See section - ``FileCheck Numeric Variables and Expressions`` for details on supported - numeric expressions. - -.. option:: -version - - Show the version number of this program. - -.. option:: -v - - Print good directive pattern matches. However, if ``-input-dump=fail`` or - ``-input-dump=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 - information as input annotations instead. - -.. option:: --allow-deprecated-dag-overlap - - Enable overlapping among matches in a group of consecutive ``CHECK-DAG:`` - directives. This option is deprecated and is only provided for convenience - as old tests are migrated to the new non-overlapping ``CHECK-DAG:`` - implementation. - -.. option:: --color - - Use colors in output (autodetected by default). - -EXIT STATUS ------------ - -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 --------- - -FileCheck is typically used from LLVM regression tests, being invoked on the RUN -line of the test. A simple example of using FileCheck from a RUN line looks -like this: - -.. code-block:: llvm - - ; 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) -against the filename argument specified (the original ``.ll`` file specified by -"``%s``"). To see how this works, let's look at the rest of the ``.ll`` file -(after the RUN line): - -.. code-block:: llvm - - define void @sub1(i32* %p, i32 %v) { - entry: - ; CHECK: sub1: - ; CHECK: subl - %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v) - ret void - } - - define void @inc4(i64* %p) { - entry: - ; CHECK: inc4: - ; CHECK: incq - %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1) - 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 -verify that it matches what the "``CHECK:``" lines specify. - -The syntax of the "``CHECK:``" lines is very simple: they are fixed strings that -must occur in order. FileCheck defaults to ignoring horizontal whitespace -differences (e.g. a space is allowed to match a tab) but otherwise, the contents -of the "``CHECK:``" line is required to match some thing in the test file exactly. - -One nice thing about FileCheck (compared to grep) is that it allows merging -test cases together into logical groups. For example, because the test above -is checking for the "``sub1:``" and "``inc4:``" labels, it will not match -unless there is a "``subl``" in between those labels. If it existed somewhere -else in the file, that would not count: "``grep subl``" matches if "``subl``" -exists anywhere in the file. - -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 -:program:`llc`. Here's a simple example: - -.. code-block:: llvm - - ; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \ - ; RUN: | FileCheck %s -check-prefix=X32 - ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \ - ; RUN: | FileCheck %s -check-prefix=X64 - - define <4 x i32> @pinsrd_1(i32 %s, <4 x i32> %tmp) nounwind { - %tmp1 = insertelement <4 x i32>; %tmp, i32 %s, i32 1 - ret <4 x i32> %tmp1 - ; X32: pinsrd_1: - ; X32: pinsrd $1, 4(%esp), %xmm0 - - ; X64: pinsrd_1: - ; X64: pinsrd $1, %edi, %xmm0 - } - -In this case, we're testing that we get the expected code generation with -both 32-bit and 64-bit code generation. - -The "CHECK-NEXT:" directive -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sometimes you want to match lines and would like to verify that matches -happen on exactly consecutive lines with no other lines in between them. In -this case, you can use "``CHECK:``" and "``CHECK-NEXT:``" directives to specify -this. If you specified a custom check prefix, just use "``-NEXT:``". -For example, something like this works as you'd expect: - -.. code-block:: llvm - - define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) { - %tmp3 = load <2 x double>* %A, align 16 - %tmp7 = insertelement <2 x double> undef, double %B, i32 0 - %tmp9 = shufflevector <2 x double> %tmp3, - <2 x double> %tmp7, - <2 x i32> < i32 0, i32 2 > - store <2 x double> %tmp9, <2 x double>* %r, align 16 - ret void - - ; CHECK: t2: - ; CHECK: movl 8(%esp), %eax - ; CHECK-NEXT: movapd (%eax), %xmm0 - ; CHECK-NEXT: movhpd 12(%esp), %xmm0 - ; CHECK-NEXT: movl 4(%esp), %eax - ; CHECK-NEXT: movapd %xmm0, (%eax) - ; CHECK-NEXT: ret - } - -"``CHECK-NEXT:``" directives reject the input unless there is exactly one -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 "``-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-EMPTY:" directive -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you need to check that the next line has nothing on it, not even whitespace, -you can use the "``CHECK-EMPTY:``" directive. - -.. code-block:: llvm - - declare void @foo() - - declare void @bar() - ; CHECK: foo - ; CHECK-EMPTY: - ; CHECK-NEXT: bar - -Just like "``CHECK-NEXT:``" the directive will fail if there is more than one -newline before it finds the next blank line, and it cannot be the first -directive in a file. - -The "CHECK-NOT:" directive -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The "``CHECK-NOT:``" directive is used to verify that a string doesn't occur -between two matches (or before the first match, or after the last match). For -example, to verify that a load is removed by a transformation, a test like this -can be used: - -.. code-block:: llvm - - define i8 @coerce_offset0(i32 %V, i32* %P) { - store i32 %V, i32* %P - - %P2 = bitcast i32* %P to i8* - %P3 = getelementptr i8* %P2, i32 2 - - %A = load i8* %P3 - ret i8 %A - ; CHECK: @coerce_offset0 - ; CHECK-NOT: load - ; CHECK: ret i8 - } - -The "CHECK-COUNT:" directive -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you need to match multiple lines with the same pattern over and over again -you can repeat a plain ``CHECK:`` as many times as needed. If that looks too -boring you can instead use a counted check "``CHECK-COUNT-:``", where -```` is a positive decimal number. It will match the pattern exactly -```` times, no more and no less. If you specified a custom check prefix, -just use "``-COUNT-:``" for the same effect. -Here is a simple example: - -.. code-block:: text - - Loop at depth 1 - Loop at depth 1 - Loop at depth 1 - Loop at depth 1 - Loop at depth 2 - Loop at depth 3 - - ; CHECK-COUNT-6: Loop at depth {{[0-9]+}} - ; CHECK-NOT: Loop at depth {{[0-9]+}} - -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:: text - - ; 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:: text - - ; 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. - -A ``CHECK-DAG:`` directive skips matches that overlap the matches of any -preceding ``CHECK-DAG:`` directives in the same ``CHECK-DAG:`` block. Not only -is this non-overlapping behavior consistent with other directives, but it's -also necessary to handle sets of non-unique strings or patterns. For example, -the following directives look for unordered log entries for two tasks in a -parallel program, such as the OpenMP runtime: - -.. code-block:: text - - // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin - // CHECK-DAG: [[THREAD_ID]]: task_end - // - // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin - // CHECK-DAG: [[THREAD_ID]]: task_end - -The second pair of directives is guaranteed not to match the same log entries -as the first pair even though the patterns are identical and even if the text -of the log entries is identical because the thread ID manages to be reused. - -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. -If ``--enable-var-scope`` is in effect, all local variables are cleared at the -beginning of the 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 Regex Matching Syntax -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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, -surrounded by double braces: ``{{yourregex}}``. FileCheck implements a POSIX -regular expression matcher; it supports Extended POSIX regular expressions -(ERE). Because we want to use fixed string matching for a majority of what we -do, FileCheck has been designed to support mixing and matching fixed string -matching with regular expressions. This allows you to write things like this: - -.. code-block:: llvm - - ; CHECK: movhpd {{[0-9]+}}(%esp), {{%xmm[0-7]}} - -In this case, any offset from the ESP register will be allowed, and any xmm -register will be allowed. - -Because regular expressions are enclosed with double braces, they are -visually distinct, and you don't need to use escape characters within the double -braces like you would in C. In the rare case that you want to match double -braces explicitly from the input, you can use something ugly like -``{{[}][}]}}`` as your pattern. Or if you are using the repetition count -syntax, for example ``[[:xdigit:]]{8}`` to match exactly 8 hex digits, you -would need to add parentheses like this ``{{([[:xdigit:]]{8})}}`` to avoid -confusion with FileCheck's closing double-brace. - -FileCheck String Substitution Blocks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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, :program:`FileCheck` supports string substitution blocks that allow -string variables to be defined and substituted into patterns. Here is a simple -example: - -.. code-block:: llvm - - ; CHECK: test5: - ; CHECK: notw [[REGISTER:%[a-z]+]] - ; CHECK: andw {{.*}}[[REGISTER]] - -The first check line matches a regex ``%[a-z]+`` and captures it into the -string variable ``REGISTER``. The second line verifies that whatever is in -``REGISTER`` occurs later in the file after an "``andw``". :program:`FileCheck` -string substitution blocks are always contained in ``[[ ]]`` pairs, and string -variable 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 substitution. - -:program:`FileCheck` variables can be defined multiple times, and substitutions -always get the latest value. Variables can also be substituted 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. - -If ``--enable-var-scope`` is in effect, variables with names that -start with ``$`` are considered to be global. All others variables are -local. All local variables get undefined at the beginning of each -CHECK-LABEL block. Global variables are not affected by CHECK-LABEL. -This makes it easier to ensure that individual tests are not affected -by variables set in preceding tests. - -FileCheck Numeric Substitution Blocks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:program:`FileCheck` also supports numeric substitution blocks that allow -defining numeric variables and checking for numeric values that satisfy a -numeric expression constraint based on those variables via a numeric -substitution. This allows ``CHECK:`` directives to verify a numeric relation -between two numbers, such as the need for consecutive registers to be used. - -The syntax to define a numeric variable is ``[[#:]]`` where -```` is the name of the numeric variable to define to the matching -value. - -For example: - -.. code-block:: llvm - - ; CHECK: mov r[[#REG:]], 42 - -would match ``mov r5, 42`` and set ``REG`` to the value ``5``. - -The syntax of a numeric substitution is ``[[#]]`` where ```` is an -expression. An expression is recursively defined as: - -* a numeric operand, or -* an expression followed by an operator and a numeric operand. - -A numeric operand is a previously defined numeric variable, or an integer -literal. The supported operators are ``+`` and ``-``. Spaces are accepted -before, after and between any of these elements. - -For example: - -.. code-block:: llvm - - ; CHECK: load r[[#REG:]], [r0] - ; CHECK: load r[[#REG+1]], [r1] - -The above example would match the text: - -.. code-block:: gas - - load r5, [r0] - load r6, [r1] - -but would not match the text: - -.. code-block:: gas - - load r5, [r0] - load r7, [r1] - -due to ``7`` being unequal to ``5 + 1``. - -The syntax also supports an empty expression, equivalent to writing {{[0-9]+}}, -for cases where the input must contain a numeric value but the value itself -does not matter: - -.. code-block:: gas - - ; CHECK-NOT: mov r0, r[[#]] - -to check that a value is synthesized rather than moved around. - -A numeric variable can also be defined to the result of a numeric expression, -in which case the numeric expression is checked and if verified the variable is -assigned to the value. The unified syntax for both defining numeric variables -and checking a numeric expression is thus ``[[#: ]]`` with each -element as described previously. - -The ``--enable-var-scope`` option has the same effect on numeric variables as -on string variables. - -Important note: In its current implementation, an expression cannot use a -numeric variable defined earlier in the same CHECK directive. - -FileCheck Pseudo Numeric Variables -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sometimes there's a need to verify output that contains 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 expressions understand the ``@LINE`` pseudo -numeric variable which evaluates to the line number of the CHECK pattern where -it is found. - -This way match patterns can be put near the relevant test lines and include -relative line number references, for example: - -.. code-block:: c++ - - // CHECK: test.cpp:[[# @LINE + 4]]:6: error: expected ';' after top level declarator - // CHECK-NEXT: {{^int a}} - // CHECK-NEXT: {{^ \^}} - // CHECK-NEXT: {{^ ;}} - int a - -To support legacy uses of ``@LINE`` as a special string variable, -:program:`FileCheck` also accepts the following uses of ``@LINE`` with string -substitution block syntax: ``[[@LINE]]``, ``[[@LINE+]]`` and -``[[@LINE-]]`` without any spaces inside the brackets and where -``offset`` is an integer. - -Matching Newline Characters -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To match newline characters in regular expressions the character class -``[[:space:]]`` can be used. For example, the following pattern: - -.. code-block:: c++ - - // CHECK: DW_AT_location [DW_FORM_sec_offset] ([[DLOC:0x[0-9a-f]+]]){{[[:space:]].*}}"intd" - -matches output of the form (from llvm-dwarfdump): - -.. code-block:: text - - DW_AT_location [DW_FORM_sec_offset] (0x00000233) - DW_AT_name [DW_FORM_strp] ( .debug_str[0x000000c9] = "intd") - -letting us set the :program:`FileCheck` variable ``DLOC`` to the desired value -``0x00000233``, extracted from the line immediately preceding "``intd``". +FileCheck - Flexible pattern matching file verifier +=================================================== + +.. program:: FileCheck + +SYNOPSIS +-------- + +:program:`FileCheck` *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*] + +DESCRIPTION +----------- + +: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 read from standard input unless the +:option:`--input-file` option is used. + +OPTIONS +------- + +Options are parsed from the environment variable ``FILECHECK_OPTS`` +and from the command line. + +.. option:: -help + + Print a summary of command line options. + +.. 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 + :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-prefixes prefix1,prefix2,... + + An alias of :option:`--check-prefix` that allows multiple prefixes to be + specified as a comma separated list. + +.. option:: --input-file filename + + File to check (defaults to stdin). + +.. option:: --match-full-lines + + By default, FileCheck allows matches of anywhere on a line. This + option will require all positive matches to cover an entire + line. Leading and trailing whitespace is ignored, unless + :option:`--strict-whitespace` is also specified. (Note: negative + matches from ``CHECK-NOT`` are not affected by this option!) + + Passing this option is equivalent to inserting ``{{^ *}}`` or + ``{{^}}`` before, and ``{{ *$}}`` or ``{{$}}`` after every positive + check pattern. + +.. 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 :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 + + 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:: --dump-input + + Dump input to stderr, adding annotations representing currently enabled + diagnostics. Do this either 'always', on 'fail', or 'never'. Specify 'help' + to explain the dump format and quit. + +.. option:: --dump-input-on-failure + + When the check fails, dump all of the original input. This option is + deprecated in favor of `--dump-input=fail`. + +.. option:: --enable-var-scope + + Enables scope for regex variables. + + Variables with names that start with ``$`` are considered global and + remain set throughout the file. + + All other variables get undefined after each encountered ``CHECK-LABEL``. + +.. option:: -D + + Sets a filecheck pattern variable ``VAR`` with value ``VALUE`` that can be + used in ``CHECK:`` lines. + +.. option:: -D#= + + Sets a filecheck numeric variable ``NUMVAR`` to the result of evaluating + ```` that can be used in ``CHECK:`` lines. See section + ``FileCheck Numeric Variables and Expressions`` for details on supported + numeric expressions. + +.. option:: -version + + Show the version number of this program. + +.. option:: -v + + Print good directive pattern matches. However, if ``-input-dump=fail`` or + ``-input-dump=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 + information as input annotations instead. + +.. option:: --allow-deprecated-dag-overlap + + Enable overlapping among matches in a group of consecutive ``CHECK-DAG:`` + directives. This option is deprecated and is only provided for convenience + as old tests are migrated to the new non-overlapping ``CHECK-DAG:`` + implementation. + +.. option:: --color + + Use colors in output (autodetected by default). + +EXIT STATUS +----------- + +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 +-------- + +FileCheck is typically used from LLVM regression tests, being invoked on the RUN +line of the test. A simple example of using FileCheck from a RUN line looks +like this: + +.. code-block:: llvm + + ; 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) +against the filename argument specified (the original ``.ll`` file specified by +"``%s``"). To see how this works, let's look at the rest of the ``.ll`` file +(after the RUN line): + +.. code-block:: llvm + + define void @sub1(i32* %p, i32 %v) { + entry: + ; CHECK: sub1: + ; CHECK: subl + %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v) + ret void + } + + define void @inc4(i64* %p) { + entry: + ; CHECK: inc4: + ; CHECK: incq + %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1) + 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 +verify that it matches what the "``CHECK:``" lines specify. + +The syntax of the "``CHECK:``" lines is very simple: they are fixed strings that +must occur in order. FileCheck defaults to ignoring horizontal whitespace +differences (e.g. a space is allowed to match a tab) but otherwise, the contents +of the "``CHECK:``" line is required to match some thing in the test file exactly. + +One nice thing about FileCheck (compared to grep) is that it allows merging +test cases together into logical groups. For example, because the test above +is checking for the "``sub1:``" and "``inc4:``" labels, it will not match +unless there is a "``subl``" in between those labels. If it existed somewhere +else in the file, that would not count: "``grep subl``" matches if "``subl``" +exists anywhere in the file. + +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 +:program:`llc`. Here's a simple example: + +.. code-block:: llvm + + ; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \ + ; RUN: | FileCheck %s -check-prefix=X32 + ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \ + ; RUN: | FileCheck %s -check-prefix=X64 + + define <4 x i32> @pinsrd_1(i32 %s, <4 x i32> %tmp) nounwind { + %tmp1 = insertelement <4 x i32>; %tmp, i32 %s, i32 1 + ret <4 x i32> %tmp1 + ; X32: pinsrd_1: + ; X32: pinsrd $1, 4(%esp), %xmm0 + + ; X64: pinsrd_1: + ; X64: pinsrd $1, %edi, %xmm0 + } + +In this case, we're testing that we get the expected code generation with +both 32-bit and 64-bit code generation. + +The "CHECK-NEXT:" directive +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes you want to match lines and would like to verify that matches +happen on exactly consecutive lines with no other lines in between them. In +this case, you can use "``CHECK:``" and "``CHECK-NEXT:``" directives to specify +this. If you specified a custom check prefix, just use "``-NEXT:``". +For example, something like this works as you'd expect: + +.. code-block:: llvm + + define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) { + %tmp3 = load <2 x double>* %A, align 16 + %tmp7 = insertelement <2 x double> undef, double %B, i32 0 + %tmp9 = shufflevector <2 x double> %tmp3, + <2 x double> %tmp7, + <2 x i32> < i32 0, i32 2 > + store <2 x double> %tmp9, <2 x double>* %r, align 16 + ret void + + ; CHECK: t2: + ; CHECK: movl 8(%esp), %eax + ; CHECK-NEXT: movapd (%eax), %xmm0 + ; CHECK-NEXT: movhpd 12(%esp), %xmm0 + ; CHECK-NEXT: movl 4(%esp), %eax + ; CHECK-NEXT: movapd %xmm0, (%eax) + ; CHECK-NEXT: ret + } + +"``CHECK-NEXT:``" directives reject the input unless there is exactly one +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 "``-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-EMPTY:" directive +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need to check that the next line has nothing on it, not even whitespace, +you can use the "``CHECK-EMPTY:``" directive. + +.. code-block:: llvm + + declare void @foo() + + declare void @bar() + ; CHECK: foo + ; CHECK-EMPTY: + ; CHECK-NEXT: bar + +Just like "``CHECK-NEXT:``" the directive will fail if there is more than one +newline before it finds the next blank line, and it cannot be the first +directive in a file. + +The "CHECK-NOT:" directive +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The "``CHECK-NOT:``" directive is used to verify that a string doesn't occur +between two matches (or before the first match, or after the last match). For +example, to verify that a load is removed by a transformation, a test like this +can be used: + +.. code-block:: llvm + + define i8 @coerce_offset0(i32 %V, i32* %P) { + store i32 %V, i32* %P + + %P2 = bitcast i32* %P to i8* + %P3 = getelementptr i8* %P2, i32 2 + + %A = load i8* %P3 + ret i8 %A + ; CHECK: @coerce_offset0 + ; CHECK-NOT: load + ; CHECK: ret i8 + } + +The "CHECK-COUNT:" directive +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need to match multiple lines with the same pattern over and over again +you can repeat a plain ``CHECK:`` as many times as needed. If that looks too +boring you can instead use a counted check "``CHECK-COUNT-:``", where +```` is a positive decimal number. It will match the pattern exactly +```` times, no more and no less. If you specified a custom check prefix, +just use "``-COUNT-:``" for the same effect. +Here is a simple example: + +.. code-block:: text + + Loop at depth 1 + Loop at depth 1 + Loop at depth 1 + Loop at depth 1 + Loop at depth 2 + Loop at depth 3 + + ; CHECK-COUNT-6: Loop at depth {{[0-9]+}} + ; CHECK-NOT: Loop at depth {{[0-9]+}} + +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:: text + + ; 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:: text + + ; 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. + +A ``CHECK-DAG:`` directive skips matches that overlap the matches of any +preceding ``CHECK-DAG:`` directives in the same ``CHECK-DAG:`` block. Not only +is this non-overlapping behavior consistent with other directives, but it's +also necessary to handle sets of non-unique strings or patterns. For example, +the following directives look for unordered log entries for two tasks in a +parallel program, such as the OpenMP runtime: + +.. code-block:: text + + // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin + // CHECK-DAG: [[THREAD_ID]]: task_end + // + // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin + // CHECK-DAG: [[THREAD_ID]]: task_end + +The second pair of directives is guaranteed not to match the same log entries +as the first pair even though the patterns are identical and even if the text +of the log entries is identical because the thread ID manages to be reused. + +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. +If ``--enable-var-scope`` is in effect, all local variables are cleared at the +beginning of the 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 Regex Matching Syntax +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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, +surrounded by double braces: ``{{yourregex}}``. FileCheck implements a POSIX +regular expression matcher; it supports Extended POSIX regular expressions +(ERE). Because we want to use fixed string matching for a majority of what we +do, FileCheck has been designed to support mixing and matching fixed string +matching with regular expressions. This allows you to write things like this: + +.. code-block:: llvm + + ; CHECK: movhpd {{[0-9]+}}(%esp), {{%xmm[0-7]}} + +In this case, any offset from the ESP register will be allowed, and any xmm +register will be allowed. + +Because regular expressions are enclosed with double braces, they are +visually distinct, and you don't need to use escape characters within the double +braces like you would in C. In the rare case that you want to match double +braces explicitly from the input, you can use something ugly like +``{{[}][}]}}`` as your pattern. Or if you are using the repetition count +syntax, for example ``[[:xdigit:]]{8}`` to match exactly 8 hex digits, you +would need to add parentheses like this ``{{([[:xdigit:]]{8})}}`` to avoid +confusion with FileCheck's closing double-brace. + +FileCheck String Substitution Blocks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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, :program:`FileCheck` supports string substitution blocks that allow +string variables to be defined and substituted into patterns. Here is a simple +example: + +.. code-block:: llvm + + ; CHECK: test5: + ; CHECK: notw [[REGISTER:%[a-z]+]] + ; CHECK: andw {{.*}}[[REGISTER]] + +The first check line matches a regex ``%[a-z]+`` and captures it into the +string variable ``REGISTER``. The second line verifies that whatever is in +``REGISTER`` occurs later in the file after an "``andw``". :program:`FileCheck` +string substitution blocks are always contained in ``[[ ]]`` pairs, and string +variable 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 substitution. + +:program:`FileCheck` variables can be defined multiple times, and substitutions +always get the latest value. Variables can also be substituted 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. + +If ``--enable-var-scope`` is in effect, variables with names that +start with ``$`` are considered to be global. All others variables are +local. All local variables get undefined at the beginning of each +CHECK-LABEL block. Global variables are not affected by CHECK-LABEL. +This makes it easier to ensure that individual tests are not affected +by variables set in preceding tests. + +FileCheck Numeric Substitution Blocks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:program:`FileCheck` also supports numeric substitution blocks that allow +defining numeric variables and checking for numeric values that satisfy a +numeric expression constraint based on those variables via a numeric +substitution. This allows ``CHECK:`` directives to verify a numeric relation +between two numbers, such as the need for consecutive registers to be used. + +The syntax to define a numeric variable is ``[[#:]]`` where +```` is the name of the numeric variable to define to the matching +value. + +For example: + +.. code-block:: llvm + + ; CHECK: mov r[[#REG:]], 42 + +would match ``mov r5, 42`` and set ``REG`` to the value ``5``. + +The syntax of a numeric substitution is ``[[#]]`` where ```` is an +expression. An expression is recursively defined as: + +* a numeric operand, or +* an expression followed by an operator and a numeric operand. + +A numeric operand is a previously defined numeric variable, or an integer +literal. The supported operators are ``+`` and ``-``. Spaces are accepted +before, after and between any of these elements. + +For example: + +.. code-block:: llvm + + ; CHECK: load r[[#REG:]], [r0] + ; CHECK: load r[[#REG+1]], [r1] + +The above example would match the text: + +.. code-block:: gas + + load r5, [r0] + load r6, [r1] + +but would not match the text: + +.. code-block:: gas + + load r5, [r0] + load r7, [r1] + +due to ``7`` being unequal to ``5 + 1``. + +The syntax also supports an empty expression, equivalent to writing {{[0-9]+}}, +for cases where the input must contain a numeric value but the value itself +does not matter: + +.. code-block:: gas + + ; CHECK-NOT: mov r0, r[[#]] + +to check that a value is synthesized rather than moved around. + +A numeric variable can also be defined to the result of a numeric expression, +in which case the numeric expression is checked and if verified the variable is +assigned to the value. The unified syntax for both defining numeric variables +and checking a numeric expression is thus ``[[#: ]]`` with each +element as described previously. + +The ``--enable-var-scope`` option has the same effect on numeric variables as +on string variables. + +Important note: In its current implementation, an expression cannot use a +numeric variable defined earlier in the same CHECK directive. + +FileCheck Pseudo Numeric Variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes there's a need to verify output that contains 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 expressions understand the ``@LINE`` pseudo +numeric variable which evaluates to the line number of the CHECK pattern where +it is found. + +This way match patterns can be put near the relevant test lines and include +relative line number references, for example: + +.. code-block:: c++ + + // CHECK: test.cpp:[[# @LINE + 4]]:6: error: expected ';' after top level declarator + // CHECK-NEXT: {{^int a}} + // CHECK-NEXT: {{^ \^}} + // CHECK-NEXT: {{^ ;}} + int a + +To support legacy uses of ``@LINE`` as a special string variable, +:program:`FileCheck` also accepts the following uses of ``@LINE`` with string +substitution block syntax: ``[[@LINE]]``, ``[[@LINE+]]`` and +``[[@LINE-]]`` without any spaces inside the brackets and where +``offset`` is an integer. + +Matching Newline Characters +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To match newline characters in regular expressions the character class +``[[:space:]]`` can be used. For example, the following pattern: + +.. code-block:: c++ + + // CHECK: DW_AT_location [DW_FORM_sec_offset] ([[DLOC:0x[0-9a-f]+]]){{[[:space:]].*}}"intd" + +matches output of the form (from llvm-dwarfdump): + +.. code-block:: text + + DW_AT_location [DW_FORM_sec_offset] (0x00000233) + DW_AT_name [DW_FORM_strp] ( .debug_str[0x000000c9] = "intd") + +letting us set the :program:`FileCheck` variable ``DLOC`` to the desired value +``0x00000233``, extracted from the line immediately preceding "``intd``". -- cgit v1.2.3