963 lines · plain
1FileCheck - Flexible pattern matching file verifier2===================================================3 4.. program:: FileCheck5 6SYNOPSIS7--------8 9:program:`FileCheck` *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*]10 11DESCRIPTION12-----------13 14:program:`FileCheck` reads two files (one from standard input, and one15specified on the command line) and uses one to verify the other. This16behavior is particularly useful for the testsuite, which wants to verify that17the output of some tool (e.g. :program:`llc`) contains the expected information18(for example, a movsd from esp or whatever is interesting). This is similar to19using :program:`grep`, but it is optimized for matching multiple different20inputs in one file in a specific order.21 22The ``match-filename`` file specifies the file that contains the patterns to23match. The file to verify is read from standard input unless the24:option:`--input-file` option is used.25 26OPTIONS27-------28 29Options are parsed from the environment variable ``FILECHECK_OPTS``30and from the command line.31 32.. option:: -help33 34 Print a summary of command line options.35 36.. option:: --check-prefix prefix37 38 FileCheck searches the contents of ``match-filename`` for patterns to39 match. By default, these patterns are prefixed with "``CHECK:``".40 If you'd like to use a different prefix (e.g. because the same input41 file is checking multiple different tool or options), the42 :option:`--check-prefix` argument allows you to specify (without the trailing43 "``:``") one or more prefixes to match. Multiple prefixes are useful for tests44 which might change for different run options, but most lines remain the same.45 46 FileCheck does not permit duplicate prefixes, even if one is a check prefix47 and one is a comment prefix (see :option:`--comment-prefixes` below).48 49.. option:: --check-prefixes prefix1,prefix2,...50 51 An alias of :option:`--check-prefix` that allows multiple prefixes to be52 specified as a comma separated list.53 54.. option:: --comment-prefixes prefix1,prefix2,...55 56 By default, FileCheck ignores any occurrence in ``match-filename`` of any check57 prefix if it is preceded on the same line by "``COM:``" or "``RUN:``". See the58 section `The "COM:" directive`_ for usage details.59 60 These default comment prefixes can be overridden by61 :option:`--comment-prefixes` if they are not appropriate for your testing62 environment. However, doing so is not recommended in LLVM's LIT-based test63 suites, which should be easier to maintain if they all follow a consistent64 comment style. In that case, consider proposing a change to the default65 comment prefixes instead.66 67.. option:: --allow-unused-prefixes68 69 This option controls the behavior when using more than one prefix as specified70 by :option:`--check-prefix` or :option:`--check-prefixes`, and some of these71 prefixes are missing in the test file. If true, this is allowed, if false,72 FileCheck will report an error, listing the missing prefixes. The default value73 is false.74 75.. option:: --input-file filename76 77 File to check (defaults to stdin).78 79.. option:: --match-full-lines80 81 By default, FileCheck allows matches of anywhere on a line. This82 option will require all positive matches to cover an entire83 line. Leading and trailing whitespace is ignored, unless84 :option:`--strict-whitespace` is also specified. (Note: negative85 matches from ``CHECK-NOT`` are not affected by this option!)86 87 Passing this option is equivalent to inserting ``{{^ *}}`` or88 ``{{^}}`` before, and ``{{ *$}}`` or ``{{$}}`` after every positive89 check pattern.90 91.. option:: --strict-whitespace92 93 By default, FileCheck canonicalizes input horizontal whitespace (spaces and94 tabs) which causes it to ignore these differences (a space will match a tab).95 The :option:`--strict-whitespace` argument disables this behavior. End-of-line96 sequences are canonicalized to UNIX-style ``\n`` in all modes.97 98.. option:: --ignore-case99 100 By default, FileCheck uses case-sensitive matching. This option causes101 FileCheck to use case-insensitive matching.102 103.. option:: --implicit-check-not check-pattern104 105 Adds implicit negative checks for the specified patterns between positive106 checks. The option allows writing stricter tests without stuffing them with107 ``CHECK-NOT``\ s.108 109 For example, "``--implicit-check-not warning:``" can be useful when testing110 diagnostic messages from tools that don't have an option similar to ``clang111 -verify``. With this option FileCheck will verify that input does not contain112 warnings not covered by any ``CHECK:`` patterns.113 114.. option:: --dump-input <value>115 116 Dump input to stderr, adding annotations representing currently enabled117 diagnostics. When there are multiple occurrences of this option, the118 ``<value>`` that appears earliest in the list below has precedence. The119 default is ``fail``.120 121 * ``help`` - Explain input dump and quit122 * ``always`` - Always dump input123 * ``fail`` - Dump input on failure124 * ``never`` - Never dump input125 126.. option:: --dump-input-context <N>127 128 In the dump requested by ``--dump-input``, print ``<N>`` input lines before129 and ``<N>`` input lines after any lines specified by ``--dump-input-filter``.130 When there are multiple occurrences of this option, the largest specified131 ``<N>`` has precedence. The default is 5.132 133.. option:: --dump-input-filter <value>134 135 In the dump requested by ``--dump-input``, print only input lines of kind136 ``<value>`` plus any context specified by ``--dump-input-context``. When137 there are multiple occurrences of this option, the ``<value>`` that appears138 earliest in the list below has precedence. The default is ``error`` when139 ``--dump-input=fail``, and it's ``all`` when ``--dump-input=always``.140 141 * ``all`` - All input lines142 * ``annotation-full`` - Input lines with annotations143 * ``annotation`` - Input lines with starting points of annotations144 * ``error`` - Input lines with starting points of error annotations145 146.. option:: --enable-var-scope147 148 Enables scope for regex variables.149 150 Variables with names that start with ``$`` are considered global and151 remain set throughout the file.152 153 All other variables get undefined after each encountered ``CHECK-LABEL``.154 155.. option:: -D<VAR=VALUE>156 157 Sets a filecheck pattern variable ``VAR`` with value ``VALUE`` that can be158 used in ``CHECK:`` lines.159 160.. option:: -D#<FMT>,<NUMVAR>=<NUMERIC EXPRESSION>161 162 Sets a filecheck numeric variable ``NUMVAR`` of matching format ``FMT`` to163 the result of evaluating ``<NUMERIC EXPRESSION>`` that can be used in164 ``CHECK:`` lines. See section165 ``FileCheck Numeric Variables and Expressions`` for details on supported166 numeric expressions.167 168.. option:: -version169 170 Show the version number of this program.171 172.. option:: -v173 174 Print good directive pattern matches. However, if ``-dump-input=fail`` or175 ``-dump-input=always``, add those matches as input annotations instead.176 177.. option:: -vv178 179 Print information helpful in diagnosing internal FileCheck issues, such as180 discarded overlapping ``CHECK-DAG:`` matches, implicit EOF pattern matches,181 and ``CHECK-NOT:`` patterns that do not have matches. Implies ``-v``.182 However, if ``-dump-input=fail`` or ``-dump-input=always``, just add that183 information as input annotations instead.184 185.. option:: --allow-deprecated-dag-overlap186 187 Enable overlapping among matches in a group of consecutive ``CHECK-DAG:``188 directives. This option is deprecated and is only provided for convenience189 as old tests are migrated to the new non-overlapping ``CHECK-DAG:``190 implementation.191 192.. option:: --allow-empty193 194 Allow checking empty input. By default, empty input is rejected.195 196.. option:: --color197 198 Use colors in output (autodetected by default).199 200EXIT STATUS201-----------202 203If :program:`FileCheck` verifies that the file matches the expected contents,204it exits with 0. Otherwise, if not, or if an error occurs, it will exit with a205non-zero value.206 207TUTORIAL208--------209 210FileCheck is typically used from LLVM regression tests, being invoked on the RUN211line of the test. A simple example of using FileCheck from a RUN line looks212like this:213 214.. code-block:: llvm215 216 ; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s217 218This syntax says to pipe the current file ("``%s``") into ``llvm-as``, pipe219that into ``llc``, then pipe the output of ``llc`` into ``FileCheck``. This220means that FileCheck will be verifying its standard input (the llc output)221against the filename argument specified (the original ``.ll`` file specified by222"``%s``"). To see how this works, let's look at the rest of the ``.ll`` file223(after the RUN line):224 225.. code-block:: llvm226 227 define void @sub1(i32* %p, i32 %v) {228 entry:229 ; CHECK: sub1:230 ; CHECK: subl231 %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v)232 ret void233 }234 235 define void @inc4(i64* %p) {236 entry:237 ; CHECK: inc4:238 ; CHECK: incq239 %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1)240 ret void241 }242 243Here you can see some "``CHECK:``" lines specified in comments. Now you can244see how the file is piped into ``llvm-as``, then ``llc``, and the machine code245output is what we are verifying. FileCheck checks the machine code output to246verify that it matches what the "``CHECK:``" lines specify.247 248The syntax of the "``CHECK:``" lines is very simple: they are fixed strings that249must occur in order. FileCheck defaults to ignoring horizontal whitespace250differences (e.g. a space is allowed to match a tab) but otherwise, the contents251of the "``CHECK:``" line is required to match some thing in the test file exactly.252 253One nice thing about FileCheck (compared to grep) is that it allows merging254test cases together into logical groups. For example, because the test above255is checking for the "``sub1:``" and "``inc4:``" labels, it will not match256unless there is a "``subl``" in between those labels. If it existed somewhere257else in the file, that would not count: "``grep subl``" matches if "``subl``"258exists anywhere in the file.259 260The FileCheck -check-prefix option261~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~262 263The FileCheck `-check-prefix` option allows multiple test264configurations to be driven from one `.ll` file. This is useful in many265circumstances, for example, testing different architectural variants with266:program:`llc`. Here's a simple example:267 268.. code-block:: llvm269 270 ; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \271 ; RUN: | FileCheck %s -check-prefix=X32272 ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \273 ; RUN: | FileCheck %s -check-prefix=X64274 275 define <4 x i32> @pinsrd_1(i32 %s, <4 x i32> %tmp) nounwind {276 %tmp1 = insertelement <4 x i32>; %tmp, i32 %s, i32 1277 ret <4 x i32> %tmp1278 ; X32: pinsrd_1:279 ; X32: pinsrd $1, 4(%esp), %xmm0280 281 ; X64: pinsrd_1:282 ; X64: pinsrd $1, %edi, %xmm0283 }284 285In this case, we're testing that we get the expected code generation with286both 32-bit and 64-bit code generation.287 288The "COM:" directive289~~~~~~~~~~~~~~~~~~~~290 291Sometimes you want to disable a FileCheck directive without removing it292entirely, or you want to write comments that mention a directive by name. The293"``COM:``" directive makes it easy to do this. For example, you might have:294 295.. code-block:: llvm296 297 ; X32: pinsrd_1:298 ; X32: pinsrd $1, 4(%esp), %xmm0299 300 ; COM: FIXME: X64 isn't working correctly yet for this part of codegen, but301 ; COM: X64 will have something similar to X32:302 ; COM:303 ; COM: X64: pinsrd_1:304 ; COM: X64: pinsrd $1, %edi, %xmm0305 306Without "``COM:``", you would need to use some combination of rewording and307directive syntax mangling to prevent FileCheck from recognizing the commented308occurrences of "``X32:``" and "``X64:``" above as directives. Moreover,309FileCheck diagnostics have been proposed that might complain about the above310occurrences of "``X64``" that don't have the trailing "``:``" because they look311like directive typos. Dodging all these problems can be tedious for a test312author, and directive syntax mangling can make the purpose of test code unclear.313"``COM:``" avoids all these problems.314 315A few important usage notes:316 317* "``COM:``" within another directive's pattern does *not* comment out the318 remainder of the pattern. For example:319 320 .. code-block:: llvm321 322 ; X32: pinsrd $1, 4(%esp), %xmm0 COM: This is part of the X32 pattern!323 324 If you need to temporarily comment out part of a directive's pattern, move it325 to another line. The reason is that FileCheck parses "``COM:``" in the same326 manner as any other directive: only the first directive on the line is327 recognized as a directive.328 329* For the sake of LIT, FileCheck treats "``RUN:``" just like "``COM:``". If this330 is not suitable for your test environment, see :option:`--comment-prefixes`.331 332* FileCheck does not recognize "``COM``", "``RUN``", or any user-defined comment333 prefix as a comment directive if it's combined with one of the usual check334 directive suffixes, such as "``-NEXT:``" or "``-NOT:``", discussed below.335 FileCheck treats such a combination as plain text instead. If it needs to act336 as a comment directive for your test environment, define it as such with337 :option:`--comment-prefixes`.338 339The "CHECK-NEXT:" directive340~~~~~~~~~~~~~~~~~~~~~~~~~~~341 342Sometimes you want to match lines and would like to verify that matches343happen on exactly consecutive lines with no other lines in between them. In344this case, you can use "``CHECK:``" and "``CHECK-NEXT:``" directives to specify345this. If you specified a custom check prefix, just use "``<PREFIX>-NEXT:``".346For example, something like this works as you'd expect:347 348.. code-block:: llvm349 350 define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) {351 %tmp3 = load <2 x double>* %A, align 16352 %tmp7 = insertelement <2 x double> undef, double %B, i32 0353 %tmp9 = shufflevector <2 x double> %tmp3,354 <2 x double> %tmp7,355 <2 x i32> < i32 0, i32 2 >356 store <2 x double> %tmp9, <2 x double>* %r, align 16357 ret void358 359 ; CHECK: t2:360 ; CHECK: movl 8(%esp), %eax361 ; CHECK-NEXT: movapd (%eax), %xmm0362 ; CHECK-NEXT: movhpd 12(%esp), %xmm0363 ; CHECK-NEXT: movl 4(%esp), %eax364 ; CHECK-NEXT: movapd %xmm0, (%eax)365 ; CHECK-NEXT: ret366 }367 368"``CHECK-NEXT:``" directives reject the input unless there is exactly one369newline between it and the previous directive. A "``CHECK-NEXT:``" cannot be370the first directive in a file.371 372The "CHECK-SAME:" directive373~~~~~~~~~~~~~~~~~~~~~~~~~~~374 375Sometimes you want to match lines and would like to verify that matches happen376on the same line as the previous match. In this case, you can use "``CHECK:``"377and "``CHECK-SAME:``" directives to specify this. If you specified a custom378check prefix, just use "``<PREFIX>-SAME:``".379 380"``CHECK-SAME:``" is particularly powerful in conjunction with "``CHECK-NOT:``"381(described below).382 383For example, the following works like you'd expect:384 385.. code-block:: llvm386 387 !0 = !DILocation(line: 5, scope: !1, inlinedAt: !2)388 389 ; CHECK: !DILocation(line: 5,390 ; CHECK-NOT: column:391 ; CHECK-SAME: scope: ![[SCOPE:[0-9]+]]392 393"``CHECK-SAME:``" directives reject the input if there are any newlines between394it and the previous directive.395 396"``CHECK-SAME:``" is also useful to avoid writing matchers for irrelevant397fields. For example, suppose you're writing a test which parses a tool that398generates output like this:399 400.. code-block:: text401 402 Name: foo403 Field1: ...404 Field2: ...405 Field3: ...406 Value: 1407 408 Name: bar409 Field1: ...410 Field2: ...411 Field3: ...412 Value: 2413 414 Name: baz415 Field1: ...416 Field2: ...417 Field3: ...418 Value: 1419 420To write a test that verifies ``foo`` has the value ``1``, you might first421write this:422 423.. code-block:: text424 425 CHECK: Name: foo426 CHECK: Value: 1{{$}}427 428However, this would be a bad test: if the value for ``foo`` changes, the test429would still pass because the "``CHECK: Value: 1``" line would match the value430from ``baz``. To fix this, you could add ``CHECK-NEXT`` matchers for every431``FieldN:`` line, but that would be verbose, and need to be updated when432``Field4`` is added. A more succinct way to write the test using the433"``CHECK-SAME:``" matcher would be as follows:434 435.. code-block:: text436 437 CHECK: Name: foo438 CHECK: Value:439 CHECK-SAME: {{ 1$}}440 441This verifies that the *next* time "``Value:``" appears in the output, it has442the value ``1``.443 444Note: a "``CHECK-SAME:``" cannot be the first directive in a file.445 446The "CHECK-EMPTY:" directive447~~~~~~~~~~~~~~~~~~~~~~~~~~~~448 449If you need to check that the next line has nothing on it, not even whitespace,450you can use the "``CHECK-EMPTY:``" directive.451 452.. code-block:: llvm453 454 declare void @foo()455 456 declare void @bar()457 ; CHECK: foo458 ; CHECK-EMPTY:459 ; CHECK-NEXT: bar460 461Just like "``CHECK-NEXT:``" the directive will fail if there is more than one462newline before it finds the next blank line, and it cannot be the first463directive in a file.464 465The "CHECK-NOT:" directive466~~~~~~~~~~~~~~~~~~~~~~~~~~467 468The "``CHECK-NOT:``" directive is used to verify that a string doesn't occur469between two matches (or before the first match, or after the last match). For470example, to verify that a load is removed by a transformation, a test like this471can be used:472 473.. code-block:: llvm474 475 define i8 @coerce_offset0(i32 %V, i32* %P) {476 store i32 %V, i32* %P477 478 %P2 = bitcast i32* %P to i8*479 %P3 = getelementptr i8* %P2, i32 2480 481 %A = load i8* %P3482 ret i8 %A483 ; CHECK: @coerce_offset0484 ; CHECK-NOT: load485 ; CHECK: ret i8486 }487 488The "CHECK-COUNT:" directive489~~~~~~~~~~~~~~~~~~~~~~~~~~~~490 491If you need to match multiple lines with the same pattern over and over again492you can repeat a plain ``CHECK:`` as many times as needed. If that looks too493boring you can instead use a counted check "``CHECK-COUNT-<num>:``", where494``<num>`` is a positive decimal number. It will match the pattern exactly495``<num>`` times, no more and no less. If you specified a custom check prefix,496just use "``<PREFIX>-COUNT-<num>:``" for the same effect.497Here is a simple example:498 499.. code-block:: text500 501 Loop at depth 1502 Loop at depth 1503 Loop at depth 1504 Loop at depth 1505 Loop at depth 2506 Loop at depth 3507 508 ; CHECK-COUNT-6: Loop at depth {{[0-9]+}}509 ; CHECK-NOT: Loop at depth {{[0-9]+}}510 511The "CHECK-DAG:" directive512~~~~~~~~~~~~~~~~~~~~~~~~~~513 514If it's necessary to match strings that don't occur in a strictly sequential515order, "``CHECK-DAG:``" could be used to verify them between two matches (or516before the first match, or after the last match). For example, clang emits517vtable globals in reverse order. Using ``CHECK-DAG:``, we can keep the checks518in the natural order:519 520.. code-block:: c++521 522 // RUN: %clang_cc1 %s -emit-llvm -o - | FileCheck %s523 524 struct Foo { virtual void method(); };525 Foo f; // emit vtable526 // CHECK-DAG: @_ZTV3Foo =527 528 struct Bar { virtual void method(); };529 Bar b;530 // CHECK-DAG: @_ZTV3Bar =531 532``CHECK-NOT:`` directives could be mixed with ``CHECK-DAG:`` directives to533exclude strings between the surrounding ``CHECK-DAG:`` directives. As a result,534the surrounding ``CHECK-DAG:`` directives cannot be reordered, i.e. all535occurrences matching ``CHECK-DAG:`` before ``CHECK-NOT:`` must not fall behind536occurrences matching ``CHECK-DAG:`` after ``CHECK-NOT:``. For example,537 538.. code-block:: llvm539 540 ; CHECK-DAG: BEFORE541 ; CHECK-NOT: NOT542 ; CHECK-DAG: AFTER543 544This case will reject input strings where ``BEFORE`` occurs after ``AFTER``.545 546With captured variables, ``CHECK-DAG:`` is able to match valid topological547orderings of a DAG with edges from the definition of a variable to its use.548It's useful, e.g., when your test cases need to match different output549sequences from the instruction scheduler. For example,550 551.. code-block:: llvm552 553 ; CHECK-DAG: add [[REG1:r[0-9]+]], r1, r2554 ; CHECK-DAG: add [[REG2:r[0-9]+]], r3, r4555 ; CHECK: mul r5, [[REG1]], [[REG2]]556 557In this case, any order of that two ``add`` instructions will be allowed.558 559If you are defining `and` using variables in the same ``CHECK-DAG:`` block,560be aware that the definition rule can match `after` its use.561 562So, for instance, the code below will pass:563 564.. code-block:: text565 566 ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]567 ; CHECK-DAG: vmov.32 [[REG2]][1]568 vmov.32 d0[1]569 vmov.32 d0[0]570 571While this other code, will not:572 573.. code-block:: text574 575 ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]576 ; CHECK-DAG: vmov.32 [[REG2]][1]577 vmov.32 d1[1]578 vmov.32 d0[0]579 580While this can be very useful, it's also dangerous, because in the case of581register sequence, you must have a strong order (read before write, copy before582use, etc). If the definition your test is looking for doesn't match (because583of a bug in the compiler), it may match further away from the use, and mask584real bugs away.585 586In those cases, to enforce the order, use a non-DAG directive between DAG-blocks.587 588A ``CHECK-DAG:`` directive skips matches that overlap the matches of any589preceding ``CHECK-DAG:`` directives in the same ``CHECK-DAG:`` block. Not only590is this non-overlapping behavior consistent with other directives, but it's591also necessary to handle sets of non-unique strings or patterns. For example,592the following directives look for unordered log entries for two tasks in a593parallel program, such as the OpenMP runtime:594 595.. code-block:: text596 597 // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin598 // CHECK-DAG: [[THREAD_ID]]: task_end599 //600 // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin601 // CHECK-DAG: [[THREAD_ID]]: task_end602 603The second pair of directives is guaranteed not to match the same log entries604as the first pair even though the patterns are identical and even if the text605of the log entries is identical because the thread ID manages to be reused.606 607The "CHECK-LABEL:" directive608~~~~~~~~~~~~~~~~~~~~~~~~~~~~609 610Sometimes in a file containing multiple tests divided into logical blocks, one611or more ``CHECK:`` directives may inadvertently succeed by matching lines in a612later block. While an error will usually eventually be generated, the check613flagged as causing the error may not actually bear any relationship to the614actual source of the problem.615 616In order to produce better error messages in these cases, the "``CHECK-LABEL:``"617directive can be used. It is treated identically to a normal ``CHECK``618directive except that FileCheck makes an additional assumption that a line619matched by the directive cannot also be matched by any other check present in620``match-filename``; this is intended to be used for lines containing labels or621other unique identifiers. Conceptually, the presence of ``CHECK-LABEL`` divides622the input stream into separate blocks, each of which is processed independently,623preventing a ``CHECK:`` directive in one block matching a line in another block.624If ``--enable-var-scope`` is in effect, all local variables are cleared at the625beginning of the block.626 627For example,628 629.. code-block:: llvm630 631 define %struct.C* @C_ctor_base(%struct.C* %this, i32 %x) {632 entry:633 ; CHECK-LABEL: C_ctor_base:634 ; CHECK: mov [[SAVETHIS:r[0-9]+]], r0635 ; CHECK: bl A_ctor_base636 ; CHECK: mov r0, [[SAVETHIS]]637 %0 = bitcast %struct.C* %this to %struct.A*638 %call = tail call %struct.A* @A_ctor_base(%struct.A* %0)639 %1 = bitcast %struct.C* %this to %struct.B*640 %call2 = tail call %struct.B* @B_ctor_base(%struct.B* %1, i32 %x)641 ret %struct.C* %this642 }643 644 define %struct.D* @D_ctor_base(%struct.D* %this, i32 %x) {645 entry:646 ; CHECK-LABEL: D_ctor_base:647 648The use of ``CHECK-LABEL:`` directives in this case ensures that the three649``CHECK:`` directives only accept lines corresponding to the body of the650``@C_ctor_base`` function, even if the patterns match lines found later in651the file. Furthermore, if one of these three ``CHECK:`` directives fail,652FileCheck will recover by continuing to the next block, allowing multiple test653failures to be detected in a single invocation.654 655There is no requirement that ``CHECK-LABEL:`` directives contain strings that656correspond to actual syntactic labels in a source or output language: they must657simply uniquely match a single line in the file being verified.658 659``CHECK-LABEL:`` directives cannot contain variable definitions or uses.660 661Directive modifiers662~~~~~~~~~~~~~~~~~~~663 664A directive modifier can be append to a directive by following the directive665with ``{<modifier>}`` where the only supported value for ``<modifier>`` is666``LITERAL``.667 668The ``LITERAL`` directive modifier can be used to perform a literal match. The669modifier results in the directive not recognizing any syntax to perform regex670matching, variable capture or any substitutions. This is useful when the text671to match would require excessive escaping otherwise. For example, the672following will perform literal matches rather than considering these as673regular expressions:674 675.. code-block:: text676 677 Input: [[[10, 20]], [[30, 40]]]678 Output %r10: [[10, 20]]679 Output %r10: [[30, 40]]680 681 ; CHECK{LITERAL}: [[[10, 20]], [[30, 40]]]682 ; CHECK-DAG{LITERAL}: [[30, 40]]683 ; CHECK-DAG{LITERAL}: [[10, 20]]684 685FileCheck Regex Matching Syntax686~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~687 688All FileCheck directives take a pattern to match.689For most uses of FileCheck, fixed string matching is perfectly sufficient. For690some things, a more flexible form of matching is desired. To support this,691FileCheck allows you to specify regular expressions in matching strings,692surrounded by double braces: ``{{yourregex}}``. FileCheck implements a POSIX693regular expression matcher; it supports Extended POSIX regular expressions694(ERE). Because we want to use fixed string matching for a majority of what we695do, FileCheck has been designed to support mixing and matching fixed string696matching with regular expressions. This allows you to write things like this:697 698.. code-block:: llvm699 700 ; CHECK: movhpd {{[0-9]+}}(%esp), {{%xmm[0-7]}}701 702In this case, any offset from the ESP register will be allowed, and any xmm703register will be allowed.704 705Because regular expressions are enclosed with double braces, they are706visually distinct, and you don't need to use escape characters within the double707braces like you would in C. In the rare case that you want to match double708braces explicitly from the input, you can use something ugly like709``{{[}][}]}}`` as your pattern. Or if you are using the repetition count710syntax, for example ``[[:xdigit:]]{8}`` to match exactly 8 hex digits, you711would need to add parentheses like this ``{{([[:xdigit:]]{8})}}`` to avoid712confusion with FileCheck's closing double-brace.713 714FileCheck String Substitution Blocks715~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~716 717It is often useful to match a pattern and then verify that it occurs again718later in the file. For codegen tests, this can be useful to allow any719register, but verify that that register is used consistently later. To do720this, :program:`FileCheck` supports string substitution blocks that allow721string variables to be defined and substituted into patterns. Here is a simple722example:723 724.. code-block:: llvm725 726 ; CHECK: test5:727 ; CHECK: notw [[REGISTER:%[a-z]+]]728 ; CHECK: andw {{.*}}[[REGISTER]]729 730The first check line matches a regex ``%[a-z]+`` and captures it into the731string variable ``REGISTER``. The second line verifies that whatever is in732``REGISTER`` occurs later in the file after an "``andw``". :program:`FileCheck`733string substitution blocks are always contained in ``[[ ]]`` pairs, and string734variable names can be formed with the regex ``\$[a-zA-Z_][a-zA-Z0-9_]*``. If a735colon follows the name, then it is a definition of the variable; otherwise, it736is a substitution.737 738:program:`FileCheck` variables can be defined multiple times, and substitutions739always get the latest value. Variables can also be substituted later on the740same line they were defined on. For example:741 742.. code-block:: llvm743 744 ; CHECK: op [[REG:r[0-9]+]], [[REG]]745 746Can be useful if you want the operands of ``op`` to be the same register,747and don't care exactly which register it is.748 749If ``--enable-var-scope`` is in effect, variables with names that750start with ``$`` are considered to be global. All others variables are751local. All local variables get undefined at the beginning of each752CHECK-LABEL block. Global variables are not affected by CHECK-LABEL.753This makes it easier to ensure that individual tests are not affected754by variables set in preceding tests.755 756FileCheck Numeric Substitution Blocks757~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~758 759:program:`FileCheck` also supports numeric substitution blocks that allow760defining numeric variables and checking for numeric values that satisfy a761numeric expression constraint based on those variables via a numeric762substitution. This allows ``CHECK:`` directives to verify a numeric relation763between two numbers, such as the need for consecutive registers to be used.764 765The syntax to capture a numeric value is766``[[#%<fmtspec>,<NUMVAR>:]]`` where:767 768* ``%<fmtspec>,`` is an optional format specifier to indicate what number769 format to match and the minimum number of digits to expect.770 771* ``<NUMVAR>:`` is an optional definition of variable ``<NUMVAR>`` from the772 captured value.773 774The syntax of ``<fmtspec>`` is: ``#.<precision><conversion specifier>`` where:775 776* ``#`` is an optional flag available for hex values (see777 ``<conversion specifier>`` below) which requires the value matched to be778 prefixed by ``0x``.779* ``.<precision>`` is an optional printf-style precision specifier in which780 ``<precision>`` indicates the minimum number of digits that the value matched781 must have, expecting leading zeros if needed.782 783* ``<conversion specifier>`` is an optional scanf-style conversion specifier784 to indicate what number format to match (e.g. hex number). Currently785 accepted format specifiers are ``%u``, ``%d``, ``%x`` and ``%X``. If absent,786 the format specifier defaults to ``%u``.787 788 789For example:790 791.. code-block:: llvm792 793 ; CHECK: mov r[[#REG:]], 0x[[#%.8X,ADDR:]]794 795would match ``mov r5, 0x0000FEFE`` and set ``REG`` to the value ``5`` and796``ADDR`` to the value ``0xFEFE``. Note that due to the precision it would fail797to match ``mov r5, 0xFEFE``.798 799As a result of the numeric variable definition being optional, it is possible800to only check that a numeric value is present in a given format. This can be801useful when the value itself is not useful, for instance:802 803.. code-block:: gas804 805 ; CHECK-NOT: mov r0, r[[#]]806 807to check that a value is synthesized rather than moved around.808 809 810The syntax of a numeric substitution is811``[[#%<fmtspec>, <constraint> <expr>]]`` where:812 813* ``<fmtspec>`` is the same format specifier as for defining a variable but814 in this context indicating how a numeric expression value should be matched815 against. If absent, both components of the format specifier are inferred from816 the matching format of the numeric variable(s) used by the expression817 constraint if any, and defaults to ``%u`` if no numeric variable is used,818 denoting that the value should be unsigned with no leading zeros. In case of819 conflict between format specifiers of several numeric variables, the820 conversion specifier becomes mandatory but the precision specifier remains821 optional.822 823* ``<constraint>`` is the constraint describing how the value to match must824 relate to the value of the numeric expression. The only currently accepted825 constraint is ``==`` for an exact match and is the default if826 ``<constraint>`` is not provided. No matching constraint must be specified827 when the ``<expr>`` is empty.828 829* ``<expr>`` is an expression. An expression is in turn recursively defined830 as:831 832 * a numeric operand, or833 * an expression followed by an operator and a numeric operand.834 835 A numeric operand is a previously defined numeric variable, an integer836 literal, or a function. Spaces are accepted before, after and between any of837 these elements. Numeric operands have 64-bit precision. Overflow and underflow838 are rejected. There is no support for operator precedence, but parentheses839 can be used to change the evaluation order.840 841The supported operators are:842 843 * ``+`` - Returns the sum of its two operands.844 * ``-`` - Returns the difference of its two operands.845 846The syntax of a function call is ``<name>(<arguments>)`` where:847 848* ``name`` is a predefined string literal. Accepted values are:849 850 * add - Returns the sum of its two operands.851 * div - Returns the quotient of its two operands.852 * max - Returns the largest of its two operands.853 * min - Returns the smallest of its two operands.854 * mul - Returns the product of its two operands.855 * sub - Returns the difference of its two operands.856 857* ``<arguments>`` is a comma separated list of expressions.858 859For example:860 861.. code-block:: llvm862 863 ; CHECK: load r[[#REG:]], [r0]864 ; CHECK: load r[[#REG+1]], [r1]865 ; CHECK: Loading from 0x[[#%x,ADDR:]]866 ; CHECK-SAME: to 0x[[#ADDR + 7]]867 868The above example would match the text:869 870.. code-block:: gas871 872 load r5, [r0]873 load r6, [r1]874 Loading from 0xa0463440 to 0xa0463447875 876but would not match the text:877 878.. code-block:: gas879 880 load r5, [r0]881 load r7, [r1]882 Loading from 0xa0463440 to 0xa0463443883 884Due to ``7`` being unequal to ``5 + 1`` and ``a0463443`` being unequal to885``a0463440 + 7``.886 887 888A numeric variable can also be defined to the result of a numeric expression,889in which case the numeric expression constraint is checked and if verified the890variable is assigned to the value. The unified syntax for both checking a891numeric expression and capturing its value into a numeric variable is thus892``[[#%<fmtspec>,<NUMVAR>: <constraint> <expr>]]`` with each element as893described previously. One can use this syntax to make a testcase more894self-describing by using variables instead of values:895 896.. code-block:: gas897 898 ; CHECK: mov r[[#REG_OFFSET:]], 0x[[#%X,FIELD_OFFSET:12]]899 ; CHECK-NEXT: load r[[#]], [r[[#REG_BASE:]], r[[#REG_OFFSET]]]900 901which would match:902 903.. code-block:: gas904 905 mov r4, 0xC906 load r6, [r5, r4]907 908The ``--enable-var-scope`` option has the same effect on numeric variables as909on string variables.910 911Important note: In its current implementation, an expression cannot use a912numeric variable defined earlier in the same CHECK directive.913 914FileCheck Pseudo Numeric Variables915~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~916 917Sometimes there's a need to verify output that contains line numbers of the918match file, e.g. when testing compiler diagnostics. This introduces a certain919fragility of the match file structure, as "``CHECK:``" lines contain absolute920line numbers in the same file, which have to be updated whenever line numbers921change due to text addition or deletion.922 923To support this case, FileCheck expressions understand the ``@LINE`` pseudo924numeric variable which evaluates to the line number of the CHECK pattern where925it is found.926 927This way match patterns can be put near the relevant test lines and include928relative line number references, for example:929 930.. code-block:: c++931 932 // CHECK: test.cpp:[[# @LINE + 4]]:6: error: expected ';' after top level declarator933 // CHECK-NEXT: {{^int a}}934 // CHECK-NEXT: {{^ \^}}935 // CHECK-NEXT: {{^ ;}}936 int a937 938To support legacy uses of ``@LINE`` as a special string variable,939:program:`FileCheck` also accepts the following uses of ``@LINE`` with string940substitution block syntax: ``[[@LINE]]``, ``[[@LINE+<offset>]]`` and941``[[@LINE-<offset>]]`` without any spaces inside the brackets and where942``offset`` is an integer.943 944Matching Newline Characters945~~~~~~~~~~~~~~~~~~~~~~~~~~~946 947To match newline characters in regular expressions the character class948``[[:space:]]`` can be used. For example, the following pattern:949 950.. code-block:: c++951 952 // CHECK: DW_AT_location [DW_FORM_sec_offset] ([[DLOC:0x[0-9a-f]+]]){{[[:space:]].*}}"intd"953 954matches output of the form (from llvm-dwarfdump):955 956.. code-block:: text957 958 DW_AT_location [DW_FORM_sec_offset] (0x00000233)959 DW_AT_name [DW_FORM_strp] ( .debug_str[0x000000c9] = "intd")960 961letting us set the :program:`FileCheck` variable ``DLOC`` to the desired value962``0x00000233``, extracted from the line immediately preceding "``intd``".963