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