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