1FileCheck - Flexible pattern matching file verifier 2=================================================== 3 4.. program:: FileCheck 5 6SYNOPSIS 7-------- 8 9:program:`FileCheck` *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*] 10 11DESCRIPTION 12----------- 13 14:program:`FileCheck` reads two files (one from standard input, and one 15specified on the command line) and uses one to verify the other. This 16behavior is particularly useful for the testsuite, which wants to verify that 17the output of some tool (e.g. :program:`llc`) contains the expected information 18(for example, a movsd from esp or whatever is interesting). This is similar to 19using :program:`grep`, but it is optimized for matching multiple different 20inputs in one file in a specific order. 21 22The ``match-filename`` file specifies the file that contains the patterns to 23match. The file to verify is read from standard input unless the 24:option:`--input-file` option is used. 25 26OPTIONS 27------- 28 29Options are parsed from the environment variable ``FILECHECK_OPTS`` 30and from the command line. 31 32.. option:: -help 33 34 Print a summary of command line options. 35 36.. option:: --check-prefix prefix 37 38 FileCheck searches the contents of ``match-filename`` for patterns to 39 match. By default, these patterns are prefixed with "``CHECK:``". 40 If you'd like to use a different prefix (e.g. because the same input 41 file is checking multiple different tool or options), the 42 :option:`--check-prefix` argument allows you to specify one or more 43 prefixes to match. Multiple prefixes are useful for tests which might 44 change for different run options, but most lines remain the same. 45 46.. option:: --check-prefixes prefix1,prefix2,... 47 48 An alias of :option:`--check-prefix` that allows multiple prefixes to be 49 specified as a comma separated list. 50 51.. option:: --input-file filename 52 53 File to check (defaults to stdin). 54 55.. option:: --match-full-lines 56 57 By default, FileCheck allows matches of anywhere on a line. This 58 option will require all positive matches to cover an entire 59 line. Leading and trailing whitespace is ignored, unless 60 :option:`--strict-whitespace` is also specified. (Note: negative 61 matches from ``CHECK-NOT`` are not affected by this option!) 62 63 Passing this option is equivalent to inserting ``{{^ *}}`` or 64 ``{{^}}`` before, and ``{{ *$}}`` or ``{{$}}`` after every positive 65 check pattern. 66 67.. option:: --strict-whitespace 68 69 By default, FileCheck canonicalizes input horizontal whitespace (spaces and 70 tabs) which causes it to ignore these differences (a space will match a tab). 71 The :option:`--strict-whitespace` argument disables this behavior. End-of-line 72 sequences are canonicalized to UNIX-style ``\n`` in all modes. 73 74.. option:: --ignore-case 75 76 By default, FileCheck uses case-sensitive matching. This option causes 77 FileCheck to use case-insensitive matching. 78 79.. option:: --implicit-check-not check-pattern 80 81 Adds implicit negative checks for the specified patterns between positive 82 checks. The option allows writing stricter tests without stuffing them with 83 ``CHECK-NOT``\ s. 84 85 For example, "``--implicit-check-not warning:``" can be useful when testing 86 diagnostic messages from tools that don't have an option similar to ``clang 87 -verify``. With this option FileCheck will verify that input does not contain 88 warnings not covered by any ``CHECK:`` patterns. 89 90.. option:: --dump-input <mode> 91 92 Dump input to stderr, adding annotations representing currently enabled 93 diagnostics. Do this either 'always', on 'fail', or 'never'. Specify 'help' 94 to explain the dump format and quit. 95 96.. option:: --dump-input-on-failure 97 98 When the check fails, dump all of the original input. This option is 99 deprecated in favor of `--dump-input=fail`. 100 101.. option:: --enable-var-scope 102 103 Enables scope for regex variables. 104 105 Variables with names that start with ``$`` are considered global and 106 remain set throughout the file. 107 108 All other variables get undefined after each encountered ``CHECK-LABEL``. 109 110.. option:: -D<VAR=VALUE> 111 112 Sets a filecheck pattern variable ``VAR`` with value ``VALUE`` that can be 113 used in ``CHECK:`` lines. 114 115.. option:: -D#<FMT>,<NUMVAR>=<NUMERIC EXPRESSION> 116 117 Sets a filecheck numeric variable ``NUMVAR`` of matching format ``FMT`` to 118 the result of evaluating ``<NUMERIC EXPRESSION>`` that can be used in 119 ``CHECK:`` lines. See section 120 ``FileCheck Numeric Variables and Expressions`` for details on supported 121 numeric expressions. 122 123.. option:: -version 124 125 Show the version number of this program. 126 127.. option:: -v 128 129 Print good directive pattern matches. However, if ``-input-dump=fail`` or 130 ``-input-dump=always``, add those matches as input annotations instead. 131 132.. option:: -vv 133 134 Print information helpful in diagnosing internal FileCheck issues, such as 135 discarded overlapping ``CHECK-DAG:`` matches, implicit EOF pattern matches, 136 and ``CHECK-NOT:`` patterns that do not have matches. Implies ``-v``. 137 However, if ``-input-dump=fail`` or ``-input-dump=always``, just add that 138 information as input annotations instead. 139 140.. option:: --allow-deprecated-dag-overlap 141 142 Enable overlapping among matches in a group of consecutive ``CHECK-DAG:`` 143 directives. This option is deprecated and is only provided for convenience 144 as old tests are migrated to the new non-overlapping ``CHECK-DAG:`` 145 implementation. 146 147.. option:: --color 148 149 Use colors in output (autodetected by default). 150 151EXIT STATUS 152----------- 153 154If :program:`FileCheck` verifies that the file matches the expected contents, 155it exits with 0. Otherwise, if not, or if an error occurs, it will exit with a 156non-zero value. 157 158TUTORIAL 159-------- 160 161FileCheck is typically used from LLVM regression tests, being invoked on the RUN 162line of the test. A simple example of using FileCheck from a RUN line looks 163like this: 164 165.. code-block:: llvm 166 167 ; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s 168 169This syntax says to pipe the current file ("``%s``") into ``llvm-as``, pipe 170that into ``llc``, then pipe the output of ``llc`` into ``FileCheck``. This 171means that FileCheck will be verifying its standard input (the llc output) 172against the filename argument specified (the original ``.ll`` file specified by 173"``%s``"). To see how this works, let's look at the rest of the ``.ll`` file 174(after the RUN line): 175 176.. code-block:: llvm 177 178 define void @sub1(i32* %p, i32 %v) { 179 entry: 180 ; CHECK: sub1: 181 ; CHECK: subl 182 %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v) 183 ret void 184 } 185 186 define void @inc4(i64* %p) { 187 entry: 188 ; CHECK: inc4: 189 ; CHECK: incq 190 %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1) 191 ret void 192 } 193 194Here you can see some "``CHECK:``" lines specified in comments. Now you can 195see how the file is piped into ``llvm-as``, then ``llc``, and the machine code 196output is what we are verifying. FileCheck checks the machine code output to 197verify that it matches what the "``CHECK:``" lines specify. 198 199The syntax of the "``CHECK:``" lines is very simple: they are fixed strings that 200must occur in order. FileCheck defaults to ignoring horizontal whitespace 201differences (e.g. a space is allowed to match a tab) but otherwise, the contents 202of the "``CHECK:``" line is required to match some thing in the test file exactly. 203 204One nice thing about FileCheck (compared to grep) is that it allows merging 205test cases together into logical groups. For example, because the test above 206is checking for the "``sub1:``" and "``inc4:``" labels, it will not match 207unless there is a "``subl``" in between those labels. If it existed somewhere 208else in the file, that would not count: "``grep subl``" matches if "``subl``" 209exists anywhere in the file. 210 211The FileCheck -check-prefix option 212~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 213 214The FileCheck `-check-prefix` option allows multiple test 215configurations to be driven from one `.ll` file. This is useful in many 216circumstances, for example, testing different architectural variants with 217:program:`llc`. Here's a simple example: 218 219.. code-block:: llvm 220 221 ; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \ 222 ; RUN: | FileCheck %s -check-prefix=X32 223 ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \ 224 ; RUN: | FileCheck %s -check-prefix=X64 225 226 define <4 x i32> @pinsrd_1(i32 %s, <4 x i32> %tmp) nounwind { 227 %tmp1 = insertelement <4 x i32>; %tmp, i32 %s, i32 1 228 ret <4 x i32> %tmp1 229 ; X32: pinsrd_1: 230 ; X32: pinsrd $1, 4(%esp), %xmm0 231 232 ; X64: pinsrd_1: 233 ; X64: pinsrd $1, %edi, %xmm0 234 } 235 236In this case, we're testing that we get the expected code generation with 237both 32-bit and 64-bit code generation. 238 239The "CHECK-NEXT:" directive 240~~~~~~~~~~~~~~~~~~~~~~~~~~~ 241 242Sometimes you want to match lines and would like to verify that matches 243happen on exactly consecutive lines with no other lines in between them. In 244this case, you can use "``CHECK:``" and "``CHECK-NEXT:``" directives to specify 245this. If you specified a custom check prefix, just use "``<PREFIX>-NEXT:``". 246For example, something like this works as you'd expect: 247 248.. code-block:: llvm 249 250 define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) { 251 %tmp3 = load <2 x double>* %A, align 16 252 %tmp7 = insertelement <2 x double> undef, double %B, i32 0 253 %tmp9 = shufflevector <2 x double> %tmp3, 254 <2 x double> %tmp7, 255 <2 x i32> < i32 0, i32 2 > 256 store <2 x double> %tmp9, <2 x double>* %r, align 16 257 ret void 258 259 ; CHECK: t2: 260 ; CHECK: movl 8(%esp), %eax 261 ; CHECK-NEXT: movapd (%eax), %xmm0 262 ; CHECK-NEXT: movhpd 12(%esp), %xmm0 263 ; CHECK-NEXT: movl 4(%esp), %eax 264 ; CHECK-NEXT: movapd %xmm0, (%eax) 265 ; CHECK-NEXT: ret 266 } 267 268"``CHECK-NEXT:``" directives reject the input unless there is exactly one 269newline between it and the previous directive. A "``CHECK-NEXT:``" cannot be 270the first directive in a file. 271 272The "CHECK-SAME:" directive 273~~~~~~~~~~~~~~~~~~~~~~~~~~~ 274 275Sometimes you want to match lines and would like to verify that matches happen 276on the same line as the previous match. In this case, you can use "``CHECK:``" 277and "``CHECK-SAME:``" directives to specify this. If you specified a custom 278check prefix, just use "``<PREFIX>-SAME:``". 279 280"``CHECK-SAME:``" is particularly powerful in conjunction with "``CHECK-NOT:``" 281(described below). 282 283For example, the following works like you'd expect: 284 285.. code-block:: llvm 286 287 !0 = !DILocation(line: 5, scope: !1, inlinedAt: !2) 288 289 ; CHECK: !DILocation(line: 5, 290 ; CHECK-NOT: column: 291 ; CHECK-SAME: scope: ![[SCOPE:[0-9]+]] 292 293"``CHECK-SAME:``" directives reject the input if there are any newlines between 294it and the previous directive. A "``CHECK-SAME:``" cannot be the first 295directive in a file. 296 297The "CHECK-EMPTY:" directive 298~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 299 300If you need to check that the next line has nothing on it, not even whitespace, 301you can use the "``CHECK-EMPTY:``" directive. 302 303.. code-block:: llvm 304 305 declare void @foo() 306 307 declare void @bar() 308 ; CHECK: foo 309 ; CHECK-EMPTY: 310 ; CHECK-NEXT: bar 311 312Just like "``CHECK-NEXT:``" the directive will fail if there is more than one 313newline before it finds the next blank line, and it cannot be the first 314directive in a file. 315 316The "CHECK-NOT:" directive 317~~~~~~~~~~~~~~~~~~~~~~~~~~ 318 319The "``CHECK-NOT:``" directive is used to verify that a string doesn't occur 320between two matches (or before the first match, or after the last match). For 321example, to verify that a load is removed by a transformation, a test like this 322can be used: 323 324.. code-block:: llvm 325 326 define i8 @coerce_offset0(i32 %V, i32* %P) { 327 store i32 %V, i32* %P 328 329 %P2 = bitcast i32* %P to i8* 330 %P3 = getelementptr i8* %P2, i32 2 331 332 %A = load i8* %P3 333 ret i8 %A 334 ; CHECK: @coerce_offset0 335 ; CHECK-NOT: load 336 ; CHECK: ret i8 337 } 338 339The "CHECK-COUNT:" directive 340~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 341 342If you need to match multiple lines with the same pattern over and over again 343you can repeat a plain ``CHECK:`` as many times as needed. If that looks too 344boring you can instead use a counted check "``CHECK-COUNT-<num>:``", where 345``<num>`` is a positive decimal number. It will match the pattern exactly 346``<num>`` times, no more and no less. If you specified a custom check prefix, 347just use "``<PREFIX>-COUNT-<num>:``" for the same effect. 348Here is a simple example: 349 350.. code-block:: text 351 352 Loop at depth 1 353 Loop at depth 1 354 Loop at depth 1 355 Loop at depth 1 356 Loop at depth 2 357 Loop at depth 3 358 359 ; CHECK-COUNT-6: Loop at depth {{[0-9]+}} 360 ; CHECK-NOT: Loop at depth {{[0-9]+}} 361 362The "CHECK-DAG:" directive 363~~~~~~~~~~~~~~~~~~~~~~~~~~ 364 365If it's necessary to match strings that don't occur in a strictly sequential 366order, "``CHECK-DAG:``" could be used to verify them between two matches (or 367before the first match, or after the last match). For example, clang emits 368vtable globals in reverse order. Using ``CHECK-DAG:``, we can keep the checks 369in the natural order: 370 371.. code-block:: c++ 372 373 // RUN: %clang_cc1 %s -emit-llvm -o - | FileCheck %s 374 375 struct Foo { virtual void method(); }; 376 Foo f; // emit vtable 377 // CHECK-DAG: @_ZTV3Foo = 378 379 struct Bar { virtual void method(); }; 380 Bar b; 381 // CHECK-DAG: @_ZTV3Bar = 382 383``CHECK-NOT:`` directives could be mixed with ``CHECK-DAG:`` directives to 384exclude strings between the surrounding ``CHECK-DAG:`` directives. As a result, 385the surrounding ``CHECK-DAG:`` directives cannot be reordered, i.e. all 386occurrences matching ``CHECK-DAG:`` before ``CHECK-NOT:`` must not fall behind 387occurrences matching ``CHECK-DAG:`` after ``CHECK-NOT:``. For example, 388 389.. code-block:: llvm 390 391 ; CHECK-DAG: BEFORE 392 ; CHECK-NOT: NOT 393 ; CHECK-DAG: AFTER 394 395This case will reject input strings where ``BEFORE`` occurs after ``AFTER``. 396 397With captured variables, ``CHECK-DAG:`` is able to match valid topological 398orderings of a DAG with edges from the definition of a variable to its use. 399It's useful, e.g., when your test cases need to match different output 400sequences from the instruction scheduler. For example, 401 402.. code-block:: llvm 403 404 ; CHECK-DAG: add [[REG1:r[0-9]+]], r1, r2 405 ; CHECK-DAG: add [[REG2:r[0-9]+]], r3, r4 406 ; CHECK: mul r5, [[REG1]], [[REG2]] 407 408In this case, any order of that two ``add`` instructions will be allowed. 409 410If you are defining `and` using variables in the same ``CHECK-DAG:`` block, 411be aware that the definition rule can match `after` its use. 412 413So, for instance, the code below will pass: 414 415.. code-block:: text 416 417 ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0] 418 ; CHECK-DAG: vmov.32 [[REG2]][1] 419 vmov.32 d0[1] 420 vmov.32 d0[0] 421 422While this other code, will not: 423 424.. code-block:: text 425 426 ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0] 427 ; CHECK-DAG: vmov.32 [[REG2]][1] 428 vmov.32 d1[1] 429 vmov.32 d0[0] 430 431While this can be very useful, it's also dangerous, because in the case of 432register sequence, you must have a strong order (read before write, copy before 433use, etc). If the definition your test is looking for doesn't match (because 434of a bug in the compiler), it may match further away from the use, and mask 435real bugs away. 436 437In those cases, to enforce the order, use a non-DAG directive between DAG-blocks. 438 439A ``CHECK-DAG:`` directive skips matches that overlap the matches of any 440preceding ``CHECK-DAG:`` directives in the same ``CHECK-DAG:`` block. Not only 441is this non-overlapping behavior consistent with other directives, but it's 442also necessary to handle sets of non-unique strings or patterns. For example, 443the following directives look for unordered log entries for two tasks in a 444parallel program, such as the OpenMP runtime: 445 446.. code-block:: text 447 448 // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin 449 // CHECK-DAG: [[THREAD_ID]]: task_end 450 // 451 // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin 452 // CHECK-DAG: [[THREAD_ID]]: task_end 453 454The second pair of directives is guaranteed not to match the same log entries 455as the first pair even though the patterns are identical and even if the text 456of the log entries is identical because the thread ID manages to be reused. 457 458The "CHECK-LABEL:" directive 459~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 460 461Sometimes in a file containing multiple tests divided into logical blocks, one 462or more ``CHECK:`` directives may inadvertently succeed by matching lines in a 463later block. While an error will usually eventually be generated, the check 464flagged as causing the error may not actually bear any relationship to the 465actual source of the problem. 466 467In order to produce better error messages in these cases, the "``CHECK-LABEL:``" 468directive can be used. It is treated identically to a normal ``CHECK`` 469directive except that FileCheck makes an additional assumption that a line 470matched by the directive cannot also be matched by any other check present in 471``match-filename``; this is intended to be used for lines containing labels or 472other unique identifiers. Conceptually, the presence of ``CHECK-LABEL`` divides 473the input stream into separate blocks, each of which is processed independently, 474preventing a ``CHECK:`` directive in one block matching a line in another block. 475If ``--enable-var-scope`` is in effect, all local variables are cleared at the 476beginning of the block. 477 478For example, 479 480.. code-block:: llvm 481 482 define %struct.C* @C_ctor_base(%struct.C* %this, i32 %x) { 483 entry: 484 ; CHECK-LABEL: C_ctor_base: 485 ; CHECK: mov [[SAVETHIS:r[0-9]+]], r0 486 ; CHECK: bl A_ctor_base 487 ; CHECK: mov r0, [[SAVETHIS]] 488 %0 = bitcast %struct.C* %this to %struct.A* 489 %call = tail call %struct.A* @A_ctor_base(%struct.A* %0) 490 %1 = bitcast %struct.C* %this to %struct.B* 491 %call2 = tail call %struct.B* @B_ctor_base(%struct.B* %1, i32 %x) 492 ret %struct.C* %this 493 } 494 495 define %struct.D* @D_ctor_base(%struct.D* %this, i32 %x) { 496 entry: 497 ; CHECK-LABEL: D_ctor_base: 498 499The use of ``CHECK-LABEL:`` directives in this case ensures that the three 500``CHECK:`` directives only accept lines corresponding to the body of the 501``@C_ctor_base`` function, even if the patterns match lines found later in 502the file. Furthermore, if one of these three ``CHECK:`` directives fail, 503FileCheck will recover by continuing to the next block, allowing multiple test 504failures to be detected in a single invocation. 505 506There is no requirement that ``CHECK-LABEL:`` directives contain strings that 507correspond to actual syntactic labels in a source or output language: they must 508simply uniquely match a single line in the file being verified. 509 510``CHECK-LABEL:`` directives cannot contain variable definitions or uses. 511 512FileCheck Regex Matching Syntax 513~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 514 515All FileCheck directives take a pattern to match. 516For most uses of FileCheck, fixed string matching is perfectly sufficient. For 517some things, a more flexible form of matching is desired. To support this, 518FileCheck allows you to specify regular expressions in matching strings, 519surrounded by double braces: ``{{yourregex}}``. FileCheck implements a POSIX 520regular expression matcher; it supports Extended POSIX regular expressions 521(ERE). Because we want to use fixed string matching for a majority of what we 522do, FileCheck has been designed to support mixing and matching fixed string 523matching with regular expressions. This allows you to write things like this: 524 525.. code-block:: llvm 526 527 ; CHECK: movhpd {{[0-9]+}}(%esp), {{%xmm[0-7]}} 528 529In this case, any offset from the ESP register will be allowed, and any xmm 530register will be allowed. 531 532Because regular expressions are enclosed with double braces, they are 533visually distinct, and you don't need to use escape characters within the double 534braces like you would in C. In the rare case that you want to match double 535braces explicitly from the input, you can use something ugly like 536``{{[}][}]}}`` as your pattern. Or if you are using the repetition count 537syntax, for example ``[[:xdigit:]]{8}`` to match exactly 8 hex digits, you 538would need to add parentheses like this ``{{([[:xdigit:]]{8})}}`` to avoid 539confusion with FileCheck's closing double-brace. 540 541FileCheck String Substitution Blocks 542~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 543 544It is often useful to match a pattern and then verify that it occurs again 545later in the file. For codegen tests, this can be useful to allow any 546register, but verify that that register is used consistently later. To do 547this, :program:`FileCheck` supports string substitution blocks that allow 548string variables to be defined and substituted into patterns. Here is a simple 549example: 550 551.. code-block:: llvm 552 553 ; CHECK: test5: 554 ; CHECK: notw [[REGISTER:%[a-z]+]] 555 ; CHECK: andw {{.*}}[[REGISTER]] 556 557The first check line matches a regex ``%[a-z]+`` and captures it into the 558string variable ``REGISTER``. The second line verifies that whatever is in 559``REGISTER`` occurs later in the file after an "``andw``". :program:`FileCheck` 560string substitution blocks are always contained in ``[[ ]]`` pairs, and string 561variable names can be formed with the regex ``[a-zA-Z_][a-zA-Z0-9_]*``. If a 562colon follows the name, then it is a definition of the variable; otherwise, it 563is a substitution. 564 565:program:`FileCheck` variables can be defined multiple times, and substitutions 566always get the latest value. Variables can also be substituted later on the 567same line they were defined on. For example: 568 569.. code-block:: llvm 570 571 ; CHECK: op [[REG:r[0-9]+]], [[REG]] 572 573Can be useful if you want the operands of ``op`` to be the same register, 574and don't care exactly which register it is. 575 576If ``--enable-var-scope`` is in effect, variables with names that 577start with ``$`` are considered to be global. All others variables are 578local. All local variables get undefined at the beginning of each 579CHECK-LABEL block. Global variables are not affected by CHECK-LABEL. 580This makes it easier to ensure that individual tests are not affected 581by variables set in preceding tests. 582 583FileCheck Numeric Substitution Blocks 584~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 585 586:program:`FileCheck` also supports numeric substitution blocks that allow 587defining numeric variables and checking for numeric values that satisfy a 588numeric expression constraint based on those variables via a numeric 589substitution. This allows ``CHECK:`` directives to verify a numeric relation 590between two numbers, such as the need for consecutive registers to be used. 591 592The syntax to define a numeric variable is ``[[#%<fmtspec>,<NUMVAR>:]]`` where: 593 594* ``%<fmtspec>`` is an optional scanf-style matching format specifier to 595 indicate what number format to match (e.g. hex number). Currently accepted 596 format specifiers are ``%u``, ``%x`` and ``%X``. If absent, the format 597 specifier defaults to ``%u``. 598 599* ``<NUMVAR>`` is the name of the numeric variable to define to the matching 600 value. 601 602For example: 603 604.. code-block:: llvm 605 606 ; CHECK: mov r[[#REG:]], 0x[[#%X,IMM:]] 607 608would match ``mov r5, 0xF0F0`` and set ``REG`` to the value ``5`` and ``IMM`` 609to the value ``0xF0F0``. 610 611The syntax of a numeric substitution is ``[[#%<fmtspec>,<expr>]]`` where: 612 613* ``%<fmtspec>`` is the same matching format specifier as for defining numeric 614 variables but acting as a printf-style format to indicate how a numeric 615 expression value should be matched against. If absent, the format specifier 616 is inferred from the matching format of the numeric variable(s) used by the 617 expression constraint if any, and defaults to ``%u`` if no numeric variable 618 is used. In case of conflict between matching formats of several numeric 619 variables the format specifier is mandatory. 620 621* ``<expr>`` is an expression. An expression is in turn recursively defined 622 as: 623 624 * a numeric operand, or 625 * an expression followed by an operator and a numeric operand. 626 627 A numeric operand is a previously defined numeric variable, or an integer 628 literal. The supported operators are ``+`` and ``-``. Spaces are accepted 629 before, after and between any of these elements. 630 631For example: 632 633.. code-block:: llvm 634 635 ; CHECK: load r[[#REG:]], [r0] 636 ; CHECK: load r[[#REG+1]], [r1] 637 ; CHECK: Loading from 0x[[#%x,ADDR:]] 638 ; CHECK-SAME: to 0x[[#ADDR + 7]] 639 640The above example would match the text: 641 642.. code-block:: gas 643 644 load r5, [r0] 645 load r6, [r1] 646 Loading from 0xa0463440 to 0xa0463447 647 648but would not match the text: 649 650.. code-block:: gas 651 652 load r5, [r0] 653 load r7, [r1] 654 Loading from 0xa0463440 to 0xa0463443 655 656Due to ``7`` being unequal to ``5 + 1`` and ``a0463443`` being unequal to 657``a0463440 + 7``. 658 659The syntax also supports an empty expression, equivalent to writing {{[0-9]+}}, 660for cases where the input must contain a numeric value but the value itself 661does not matter: 662 663.. code-block:: gas 664 665 ; CHECK-NOT: mov r0, r[[#]] 666 667to check that a value is synthesized rather than moved around. 668 669A numeric variable can also be defined to the result of a numeric expression, 670in which case the numeric expression is checked and if verified the variable is 671assigned to the value. The unified syntax for both defining numeric variables 672and checking a numeric expression is thus ``[[#%<fmtspec>,<NUMVAR>: <expr>]]`` 673with each element as described previously. One can use this syntax to make a 674testcase more self-describing by using variables instead of values: 675 676.. code-block:: gas 677 678 ; CHECK: mov r[[#REG_OFFSET:]], 0x[[#%X,FIELD_OFFSET:12]] 679 ; CHECK-NEXT: load r[[#]], [r[[#REG_BASE:]], r[[#REG_OFFSET]]] 680 681which would match: 682 683.. code-block:: gas 684 685 mov r4, 0xC 686 load r6, [r5, r4] 687 688The ``--enable-var-scope`` option has the same effect on numeric variables as 689on string variables. 690 691Important note: In its current implementation, an expression cannot use a 692numeric variable defined earlier in the same CHECK directive. 693 694FileCheck Pseudo Numeric Variables 695~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 696 697Sometimes there's a need to verify output that contains line numbers of the 698match file, e.g. when testing compiler diagnostics. This introduces a certain 699fragility of the match file structure, as "``CHECK:``" lines contain absolute 700line numbers in the same file, which have to be updated whenever line numbers 701change due to text addition or deletion. 702 703To support this case, FileCheck expressions understand the ``@LINE`` pseudo 704numeric variable which evaluates to the line number of the CHECK pattern where 705it is found. 706 707This way match patterns can be put near the relevant test lines and include 708relative line number references, for example: 709 710.. code-block:: c++ 711 712 // CHECK: test.cpp:[[# @LINE + 4]]:6: error: expected ';' after top level declarator 713 // CHECK-NEXT: {{^int a}} 714 // CHECK-NEXT: {{^ \^}} 715 // CHECK-NEXT: {{^ ;}} 716 int a 717 718To support legacy uses of ``@LINE`` as a special string variable, 719:program:`FileCheck` also accepts the following uses of ``@LINE`` with string 720substitution block syntax: ``[[@LINE]]``, ``[[@LINE+<offset>]]`` and 721``[[@LINE-<offset>]]`` without any spaces inside the brackets and where 722``offset`` is an integer. 723 724Matching Newline Characters 725~~~~~~~~~~~~~~~~~~~~~~~~~~~ 726 727To match newline characters in regular expressions the character class 728``[[:space:]]`` can be used. For example, the following pattern: 729 730.. code-block:: c++ 731 732 // CHECK: DW_AT_location [DW_FORM_sec_offset] ([[DLOC:0x[0-9a-f]+]]){{[[:space:]].*}}"intd" 733 734matches output of the form (from llvm-dwarfdump): 735 736.. code-block:: text 737 738 DW_AT_location [DW_FORM_sec_offset] (0x00000233) 739 DW_AT_name [DW_FORM_strp] ( .debug_str[0x000000c9] = "intd") 740 741letting us set the :program:`FileCheck` variable ``DLOC`` to the desired value 742``0x00000233``, extracted from the line immediately preceding "``intd``". 743