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