1FILECHECK(1) LLVM FILECHECK(1)
2
6 FileCheck - Flexible pattern matching file verifier
7
9 FileCheck match-filename [--check-prefix=XXX] [--strict-whitespace]
10
12 FileCheck reads two files (one from standard input, and one specified
13 on the command line) and uses one to verify the other. This behavior
14 is particularly useful for the testsuite, which wants to verify that
15 the output of some tool (e.g. llc) contains the expected information
16 (for example, a movsd from esp or whatever is interesting). This is
17 similar to using grep, but it is optimized for matching multiple dif‐
18 ferent inputs in one file in a specific order.
19 The match-filename file specifies the file that contains the patterns
21 to match. The file to verify is read from standard input unless the
22 --input-file option is used.
23
25 Options are parsed from the environment variable FILECHECK_OPTS and
26 from the command line.
27 -help Print a summary of command line options.
29 --check-prefix prefix
31 FileCheck searches the contents of match-filename for patterns
32 to match. By default, these patterns are prefixed with
33 "CHECK:". If you'd like to use a different prefix (e.g. because
34 the same input file is checking multiple different tool or
35 options), the --check-prefix argument allows you to specify
36 (without the trailing ":") one or more prefixes to match. Multi‐
37 ple prefixes are useful for tests which might change for differ‐
38 ent run options, but most lines remain the same.
39 FileCheck does not permit duplicate prefixes, even if one is a
41 check prefix and one is a comment prefix (see --comment-prefixes
42 below).
43 --check-prefixes prefix1,prefix2,...
45 An alias of --check-prefix that allows multiple prefixes to be
46 specified as a comma separated list.
47 --comment-prefixes prefix1,prefix2,...
49 By default, FileCheck ignores any occurrence in match-filename
50 of any check prefix if it is preceded on the same line by "COM:"
51 or "RUN:". See the section The "COM:" directive for usage
52 details.
53 These default comment prefixes can be overridden by
55 --comment-prefixes if they are not appropriate for your testing
56 environment. However, doing so is not recommended in LLVM's
57 LIT-based test suites, which should be easier to maintain if
58 they all follow a consistent comment style. In that case, con‐
59 sider proposing a change to the default comment prefixes
60 instead.
61 --input-file filename
63 File to check (defaults to stdin).
64 --match-full-lines
66 By default, FileCheck allows matches of anywhere on a line. This
67 option will require all positive matches to cover an entire
68 line. Leading and trailing whitespace is ignored, unless
69 --strict-whitespace is also specified. (Note: negative matches
70 from CHECK-NOT are not affected by this option!)
71 Passing this option is equivalent to inserting {{^ *}} or {{^}}
73 before, and {{ *$}} or {{$}} after every positive check pattern.
74 --strict-whitespace
76 By default, FileCheck canonicalizes input horizontal whitespace
77 (spaces and tabs) which causes it to ignore these differences (a
78 space will match a tab). The --strict-whitespace argument dis‐
79 ables this behavior. End-of-line sequences are canonicalized to
80 UNIX-style \n in all modes.
81 --ignore-case
83 By default, FileCheck uses case-sensitive matching. This option
84 causes FileCheck to use case-insensitive matching.
85 --implicit-check-not check-pattern
87 Adds implicit negative checks for the specified patterns between
88 positive checks. The option allows writing stricter tests with‐
89 out stuffing them with CHECK-NOTs.
90 For example, "--implicit-check-not warning:" can be useful when
92 testing diagnostic messages from tools that don't have an option
93 similar to clang -verify. With this option FileCheck will verify
94 that input does not contain warnings not covered by any CHECK:
95 patterns.
96 --dump-input <value>
98 Dump input to stderr, adding annotations representing currently
99 enabled diagnostics. When there are multiple occurrences of
100 this option, the <value> that appears earliest in the list below
101 has precedence. The default is fail.
102 · help - Explain input dump and quit
104 · always - Always dump input
106 · fail - Dump input on failure
108 · never - Never dump input
110 --dump-input-context <N>
112 In the dump requested by --dump-input, print <N> input lines
113 before and <N> input lines after any lines specified by
114 --dump-input-filter. When there are multiple occurrences of
115 this option, the largest specified <N> has precedence. The
116 default is 5.
117 --dump-input-filter <value>
119 In the dump requested by --dump-input, print only input lines of
120 kind <value> plus any context specified by --dump-input-context.
121 When there are multiple occurrences of this option, the <value>
122 that appears earliest in the list below has precedence. The
123 default is error when --dump-input=fail, and it's all when
124 --dump-input=always.
125 · all - All input lines
127 · annotation-full - Input lines with annotations
129 · annotation - Input lines with starting points of annota‐
131 tions
132 · error - Input lines with starting points of error
134 annotations
135 --enable-var-scope
137 Enables scope for regex variables.
138 Variables with names that start with $ are considered global and
140 remain set throughout the file.
141 All other variables get undefined after each encountered
143 CHECK-LABEL.
144 -D<VAR=VALUE>
146 Sets a filecheck pattern variable VAR with value VALUE that can
147 be used in CHECK: lines.
148 -D#<FMT>,<NUMVAR>=<NUMERIC EXPRESSION>
150 Sets a filecheck numeric variable NUMVAR of matching format FMT
151 to the result of evaluating <NUMERIC EXPRESSION> that can be
152 used in CHECK: lines. See section FileCheck Numeric Variables
153 and Expressions for details on supported numeric expressions.
154 -version
156 Show the version number of this program.
157 -v Print good directive pattern matches. However, if
159 -dump-input=fail or -dump-input=always, add those matches as
160 input annotations instead.
161 -vv Print information helpful in diagnosing internal FileCheck
163 issues, such as discarded overlapping CHECK-DAG: matches,
164 implicit EOF pattern matches, and CHECK-NOT: patterns that do
165 not have matches. Implies -v. However, if -dump-input=fail or
166 -dump-input=always, just add that information as input annota‐
167 tions instead.
168 --allow-deprecated-dag-overlap
170 Enable overlapping among matches in a group of consecutive
171 CHECK-DAG: directives. This option is deprecated and is only
172 provided for convenience as old tests are migrated to the new
173 non-overlapping CHECK-DAG: implementation.
174 --color
176 Use colors in output (autodetected by default).
177
179 If FileCheck verifies that the file matches the expected contents, it
180 exits with 0. Otherwise, if not, or if an error occurs, it will exit
181 with a non-zero value.
182
184 FileCheck is typically used from LLVM regression tests, being invoked
185 on the RUN line of the test. A simple example of using FileCheck from
186 a RUN line looks like this:
187 ; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s
189 This syntax says to pipe the current file ("%s") into llvm-as, pipe
191 that into llc, then pipe the output of llc into FileCheck. This means
192 that FileCheck will be verifying its standard input (the llc output)
193 against the filename argument specified (the original .ll file speci‐
194 fied by "%s"). To see how this works, let's look at the rest of the
195 .ll file (after the RUN line):
196 define void @sub1(i32* %p, i32 %v) {
198 entry:
199 ; CHECK: sub1:
200 ; CHECK: subl
201 %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v)
202 ret void
203 }
204 define void @inc4(i64* %p) {
206 entry:
207 ; CHECK: inc4:
208 ; CHECK: incq
209 %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1)
210 ret void
211 }
212 Here you can see some "CHECK:" lines specified in comments. Now you
214 can see how the file is piped into llvm-as, then llc, and the machine
215 code output is what we are verifying. FileCheck checks the machine
216 code output to verify that it matches what the "CHECK:" lines specify.
217 The syntax of the "CHECK:" lines is very simple: they are fixed strings
219 that must occur in order. FileCheck defaults to ignoring horizontal
220 whitespace differences (e.g. a space is allowed to match a tab) but
221 otherwise, the contents of the "CHECK:" line is required to match some
222 thing in the test file exactly.
223 One nice thing about FileCheck (compared to grep) is that it allows
225 merging test cases together into logical groups. For example, because
226 the test above is checking for the "sub1:" and "inc4:" labels, it will
227 not match unless there is a "subl" in between those labels. If it
228 existed somewhere else in the file, that would not count: "grep subl"
229 matches if "subl" exists anywhere in the file.
230 The FileCheck -check-prefix option
232 The FileCheck -check-prefix option allows multiple test configurations
233 to be driven from one .ll file. This is useful in many circumstances,
234 for example, testing different architectural variants with llc. Here's
235 a simple example:
236 ; 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 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 ; X64: pinsrd_1:
249 ; X64: pinsrd $1, %edi, %xmm0
250 }
251 In this case, we're testing that we get the expected code generation
253 with both 32-bit and 64-bit code generation.
254 The COM: directive
256 Sometimes you want to disable a FileCheck directive without removing it
257 entirely, or you want to write comments that mention a directive by
258 name. The "COM:" directive makes it easy to do this. For example, you
259 might have:
260 ; X32: pinsrd_1:
262 ; X32: pinsrd $1, 4(%esp), %xmm0
263 ; COM: FIXME: X64 isn't working correctly yet for this part of codegen, but
265 ; COM: X64 will have something similar to X32:
266 ; COM:
267 ; COM: X64: pinsrd_1:
268 ; COM: X64: pinsrd $1, %edi, %xmm0
269 Without "COM:", you would need to use some combination of rewording and
271 directive syntax mangling to prevent FileCheck from recognizing the
272 commented occurrences of "X32:" and "X64:" above as directives. More‐
273 over, FileCheck diagnostics have been proposed that might complain
274 about the above occurrences of "X64" that don't have the trailing ":"
275 because they look like directive typos. Dodging all these problems can
276 be tedious for a test author, and directive syntax mangling can make
277 the purpose of test code unclear. "COM:" avoids all these problems.
278 A few important usage notes:
280 · "COM:" within another directive's pattern does not comment out the
282 remainder of the pattern. For example:
283 ; X32: pinsrd $1, 4(%esp), %xmm0 COM: This is part of the X32 pattern!
285 If you need to temporarily comment out part of a directive's pattern,
287 move it to another line. The reason is that FileCheck parses "COM:"
288 in the same manner as any other directive: only the first directive
289 on the line is recognized as a directive.
290 · For the sake of LIT, FileCheck treats "RUN:" just like "COM:". If
292 this is not suitable for your test environment, see
293 --comment-prefixes.
294 · FileCheck does not recognize "COM", "RUN", or any user-defined com‐
296 ment prefix as a comment directive if it's combined with one of the
297 usual check directive suffixes, such as "-NEXT:" or "-NOT:", dis‐
298 cussed below. FileCheck treats such a combination as plain text
299 instead. If it needs to act as a comment directive for your test
300 environment, define it as such with --comment-prefixes.
301 The CHECK-NEXT: directive
303 Sometimes you want to match lines and would like to verify that matches
304 happen on exactly consecutive lines with no other lines in between
305 them. In this case, you can use "CHECK:" and "CHECK-NEXT:" directives
306 to specify this. If you specified a custom check prefix, just use
307 "<PREFIX>-NEXT:". For example, something like this works as you'd
308 expect:
309 define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) {
311 %tmp3 = load <2 x double>* %A, align 16
312 %tmp7 = insertelement <2 x double> undef, double %B, i32 0
313 %tmp9 = shufflevector <2 x double> %tmp3,
314 <2 x double> %tmp7,
315 <2 x i32> < i32 0, i32 2 >
316 store <2 x double> %tmp9, <2 x double>* %r, align 16
317 ret void
318 ; CHECK: t2:
320 ; CHECK: movl 8(%esp), %eax
321 ; CHECK-NEXT: movapd (%eax), %xmm0
322 ; CHECK-NEXT: movhpd 12(%esp), %xmm0
323 ; CHECK-NEXT: movl 4(%esp), %eax
324 ; CHECK-NEXT: movapd %xmm0, (%eax)
325 ; CHECK-NEXT: ret
326 }
327 "CHECK-NEXT:" directives reject the input unless there is exactly one
329 newline between it and the previous directive. A "CHECK-NEXT:" cannot
330 be the first directive in a file.
331 The CHECK-SAME: directive
333 Sometimes you want to match lines and would like to verify that matches
334 happen on the same line as the previous match. In this case, you can
335 use "CHECK:" and "CHECK-SAME:" directives to specify this. If you
336 specified a custom check prefix, just use "<PREFIX>-SAME:".
337 "CHECK-SAME:" is particularly powerful in conjunction with "CHECK-NOT:"
339 (described below).
340 For example, the following works like you'd expect:
342 !0 = !DILocation(line: 5, scope: !1, inlinedAt: !2)
344 ; CHECK: !DILocation(line: 5,
346 ; CHECK-NOT: column:
347 ; CHECK-SAME: scope: ![[SCOPE:[0-9]+]]
348 "CHECK-SAME:" directives reject the input if there are any newlines
350 between it and the previous directive. A "CHECK-SAME:" cannot be the
351 first directive in a file.
352 The CHECK-EMPTY: directive
354 If you need to check that the next line has nothing on it, not even
355 whitespace, you can use the "CHECK-EMPTY:" directive.
356 declare void @foo()
358 declare void @bar()
360 ; CHECK: foo
361 ; CHECK-EMPTY:
362 ; CHECK-NEXT: bar
363 Just like "CHECK-NEXT:" the directive will fail if there is more than
365 one newline before it finds the next blank line, and it cannot be the
366 first directive in a file.
367 The CHECK-NOT: directive
369 The "CHECK-NOT:" directive is used to verify that a string doesn't
370 occur between two matches (or before the first match, or after the last
371 match). For example, to verify that a load is removed by a transforma‐
372 tion, a test like this can be used:
373 define i8 @coerce_offset0(i32 %V, i32* %P) {
375 store i32 %V, i32* %P
376 %P2 = bitcast i32* %P to i8*
378 %P3 = getelementptr i8* %P2, i32 2
379 %A = load i8* %P3
381 ret i8 %A
382 ; CHECK: @coerce_offset0
383 ; CHECK-NOT: load
384 ; CHECK: ret i8
385 }
386 The CHECK-COUNT: directive
388 If you need to match multiple lines with the same pattern over and over
389 again you can repeat a plain CHECK: as many times as needed. If that
390 looks too boring you can instead use a counted check
391 "CHECK-COUNT-<num>:", where <num> is a positive decimal number. It will
392 match the pattern exactly <num> times, no more and no less. If you
393 specified a custom check prefix, just use "<PREFIX>-COUNT-<num>:" for
394 the same effect. Here is a simple example:
395 Loop at depth 1
397 Loop at depth 1
398 Loop at depth 1
399 Loop at depth 1
400 Loop at depth 2
401 Loop at depth 3
402 ; CHECK-COUNT-6: Loop at depth {{[0-9]+}}
404 ; CHECK-NOT: Loop at depth {{[0-9]+}}
405 The CHECK-DAG: directive
407 If it's necessary to match strings that don't occur in a strictly
408 sequential order, "CHECK-DAG:" could be used to verify them between two
409 matches (or before the first match, or after the last match). For exam‐
410 ple, clang emits vtable globals in reverse order. Using CHECK-DAG:, we
411 can keep the checks in the natural order:
412 // RUN: %clang_cc1 %s -emit-llvm -o - | FileCheck %s
414 struct Foo { virtual void method(); };
416 Foo f; // emit vtable
417 // CHECK-DAG: @_ZTV3Foo =
418 struct Bar { virtual void method(); };
420 Bar b;
421 // CHECK-DAG: @_ZTV3Bar =
422 CHECK-NOT: directives could be mixed with CHECK-DAG: directives to
424 exclude strings between the surrounding CHECK-DAG: directives. As a
425 result, the surrounding CHECK-DAG: directives cannot be reordered, i.e.
426 all occurrences matching CHECK-DAG: before CHECK-NOT: must not fall
427 behind occurrences matching CHECK-DAG: after CHECK-NOT:. For example,
428 ; CHECK-DAG: BEFORE
430 ; CHECK-NOT: NOT
431 ; CHECK-DAG: AFTER
432 This case will reject input strings where BEFORE occurs after AFTER.
434 With captured variables, CHECK-DAG: is able to match valid topological
436 orderings of a DAG with edges from the definition of a variable to its
437 use. It's useful, e.g., when your test cases need to match different
438 output sequences from the instruction scheduler. For example,
439 ; CHECK-DAG: add [[REG1:r[0-9]+]], r1, r2
441 ; CHECK-DAG: add [[REG2:r[0-9]+]], r3, r4
442 ; CHECK: mul r5, [[REG1]], [[REG2]]
443 In this case, any order of that two add instructions will be allowed.
445 If you are defining and using variables in the same CHECK-DAG: block,
447 be aware that the definition rule can match after its use.
448 So, for instance, the code below will pass:
450 ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]
452 ; CHECK-DAG: vmov.32 [[REG2]][1]
453 vmov.32 d0[1]
454 vmov.32 d0[0]
455 While this other code, will not:
457 ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]
459 ; CHECK-DAG: vmov.32 [[REG2]][1]
460 vmov.32 d1[1]
461 vmov.32 d0[0]
462 While this can be very useful, it's also dangerous, because in the case
464 of register sequence, you must have a strong order (read before write,
465 copy before use, etc). If the definition your test is looking for
466 doesn't match (because of a bug in the compiler), it may match further
467 away from the use, and mask real bugs away.
468 In those cases, to enforce the order, use a non-DAG directive between
470 DAG-blocks.
471 A CHECK-DAG: directive skips matches that overlap the matches of any
473 preceding CHECK-DAG: directives in the same CHECK-DAG: block. Not only
474 is this non-overlapping behavior consistent with other directives, but
475 it's also necessary to handle sets of non-unique strings or patterns.
476 For example, the following directives look for unordered log entries
477 for two tasks in a parallel program, such as the OpenMP runtime:
478 // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin
480 // CHECK-DAG: [[THREAD_ID]]: task_end
481 //
482 // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin
483 // CHECK-DAG: [[THREAD_ID]]: task_end
484 The second pair of directives is guaranteed not to match the same log
486 entries as the first pair even though the patterns are identical and
487 even if the text of the log entries is identical because the thread ID
488 manages to be reused.
489 The CHECK-LABEL: directive
491 Sometimes in a file containing multiple tests divided into logical
492 blocks, one or more CHECK: directives may inadvertently succeed by
493 matching lines in a later block. While an error will usually eventually
494 be generated, the check flagged as causing the error may not actually
495 bear any relationship to the actual source of the problem.
496 In order to produce better error messages in these cases, the
498 "CHECK-LABEL:" directive can be used. It is treated identically to a
499 normal CHECK directive except that FileCheck makes an additional
500 assumption that a line matched by the directive cannot also be matched
501 by any other check present in match-filename; this is intended to be
502 used for lines containing labels or other unique identifiers. Conceptu‐
503 ally, the presence of CHECK-LABEL divides the input stream into sepa‐
504 rate blocks, each of which is processed independently, preventing a
505 CHECK: directive in one block matching a line in another block. If
506 --enable-var-scope is in effect, all local variables are cleared at the
507 beginning of the block.
508 For example,
510 define %struct.C* @C_ctor_base(%struct.C* %this, i32 %x) {
512 entry:
513 ; CHECK-LABEL: C_ctor_base:
514 ; CHECK: mov [[SAVETHIS:r[0-9]+]], r0
515 ; CHECK: bl A_ctor_base
516 ; CHECK: mov r0, [[SAVETHIS]]
517 %0 = bitcast %struct.C* %this to %struct.A*
518 %call = tail call %struct.A* @A_ctor_base(%struct.A* %0)
519 %1 = bitcast %struct.C* %this to %struct.B*
520 %call2 = tail call %struct.B* @B_ctor_base(%struct.B* %1, i32 %x)
521 ret %struct.C* %this
522 }
523 define %struct.D* @D_ctor_base(%struct.D* %this, i32 %x) {
525 entry:
526 ; CHECK-LABEL: D_ctor_base:
527 The use of CHECK-LABEL: directives in this case ensures that the three
529 CHECK: directives only accept lines corresponding to the body of the
530 @C_ctor_base function, even if the patterns match lines found later in
531 the file. Furthermore, if one of these three CHECK: directives fail,
532 FileCheck will recover by continuing to the next block, allowing multi‐
533 ple test failures to be detected in a single invocation.
534 There is no requirement that CHECK-LABEL: directives contain strings
536 that correspond to actual syntactic labels in a source or output lan‐
537 guage: they must simply uniquely match a single line in the file being
538 verified.
539 CHECK-LABEL: directives cannot contain variable definitions or uses.
541 FileCheck Regex Matching Syntax
543 All FileCheck directives take a pattern to match. For most uses of
544 FileCheck, fixed string matching is perfectly sufficient. For some
545 things, a more flexible form of matching is desired. To support this,
546 FileCheck allows you to specify regular expressions in matching
547 strings, surrounded by double braces: {{yourregex}}. FileCheck imple‐
548 ments a POSIX regular expression matcher; it supports Extended POSIX
549 regular expressions (ERE). Because we want to use fixed string matching
550 for a majority of what we do, FileCheck has been designed to support
551 mixing and matching fixed string matching with regular expressions.
552 This allows you to write things like this:
553 ; CHECK: movhpd {{[0-9]+}}(%esp), {{%xmm[0-7]}}
555 In this case, any offset from the ESP register will be allowed, and any
557 xmm register will be allowed.
558 Because regular expressions are enclosed with double braces, they are
560 visually distinct, and you don't need to use escape characters within
561 the double braces like you would in C. In the rare case that you want
562 to match double braces explicitly from the input, you can use something
563 ugly like {{[}][}]}} as your pattern. Or if you are using the repeti‐
564 tion count syntax, for example [[:xdigit:]]{8} to match exactly 8 hex
565 digits, you would need to add parentheses like this
566 {{([[:xdigit:]]{8})}} to avoid confusion with FileCheck's closing dou‐
567 ble-brace.
568 FileCheck String Substitution Blocks
570 It is often useful to match a pattern and then verify that it occurs
571 again later in the file. For codegen tests, this can be useful to
572 allow any register, but verify that that register is used consistently
573 later. To do this, FileCheck supports string substitution blocks that
574 allow string variables to be defined and substituted into patterns.
575 Here is a simple example:
576 ; CHECK: test5:
578 ; CHECK: notw [[REGISTER:%[a-z]+]]
579 ; CHECK: andw {{.*}}[[REGISTER]]
580 The first check line matches a regex %[a-z]+ and captures it into the
582 string variable REGISTER. The second line verifies that whatever is in
583 REGISTER occurs later in the file after an "andw". FileCheck string
584 substitution blocks are always contained in [[ ]] pairs, and string
585 variable names can be formed with the regex [a-zA-Z_][a-zA-Z0-9_]*. If
586 a colon follows the name, then it is a definition of the variable; oth‐
587 erwise, it is a substitution.
588 FileCheck variables can be defined multiple times, and substitutions
590 always get the latest value. Variables can also be substituted later
591 on the same line they were defined on. For example:
592 ; CHECK: op [[REG:r[0-9]+]], [[REG]]
594 Can be useful if you want the operands of op to be the same register,
596 and don't care exactly which register it is.
597 If --enable-var-scope is in effect, variables with names that start
599 with $ are considered to be global. All others variables are local.
600 All local variables get undefined at the beginning of each CHECK-LABEL
601 block. Global variables are not affected by CHECK-LABEL. This makes it
602 easier to ensure that individual tests are not affected by variables
603 set in preceding tests.
604 FileCheck Numeric Substitution Blocks
606 FileCheck also supports numeric substitution blocks that allow defining
607 numeric variables and checking for numeric values that satisfy a
608 numeric expression constraint based on those variables via a numeric
609 substitution. This allows CHECK: directives to verify a numeric rela‐
610 tion between two numbers, such as the need for consecutive registers to
611 be used.
612 The syntax to define a numeric variable is [[#%<fmtspec>,<NUMVAR>:]]
614 where:
615 · %<fmtspec> is an optional scanf-style matching format specifier to
617 indicate what number format to match (e.g. hex number). Currently
618 accepted format specifiers are %u, %d, %x and %X. If absent, the
619 format specifier defaults to %u.
620 · <NUMVAR> is the name of the numeric variable to define to the match‐
622 ing value.
623 For example:
625 ; CHECK: mov r[[#REG:]], 0x[[#%X,IMM:]]
627 would match mov r5, 0xF0F0 and set REG to the value 5 and IMM to the
629 value 0xF0F0.
630 The syntax of a numeric substitution is [[#%<fmtspec>: <constraint>
632 <expr>]] where:
633 · %<fmtspec> is the same matching format specifier as for defining
635 numeric variables but acting as a printf-style format to indicate how
636 a numeric expression value should be matched against. If absent, the
637 format specifier is inferred from the matching format of the numeric
638 variable(s) used by the expression constraint if any, and defaults to
639 %u if no numeric variable is used. In case of conflict between
640 matching formats of several numeric variables the format specifier is
641 mandatory.
642 · <constraint> is the constraint describing how the value to match must
644 relate to the value of the numeric expression. The only currently
645 accepted constraint is == for an exact match and is the default if
646 <constraint> is not provided. No matching constraint must be speci‐
647 fied when the <expr> is empty.
648 · <expr> is an expression. An expression is in turn recursively defined
650 as:
651 · a numeric operand, or
653 · an expression followed by an operator and a numeric operand.
655 A numeric operand is a previously defined numeric variable, an inte‐
657 ger literal, or a function. Spaces are accepted before, after and
658 between any of these elements. Numeric operands have 64-bit preci‐
659 sion. Overflow and underflow are rejected. There is no support for
660 operator precedence, but parentheses can be used to change the evalu‐
661 ation order.
662 The supported operators are:
664 · + - Returns the sum of its two operands.
666 · - - Returns the difference of its two operands.
668 The syntax of a function call is <name>(<arguments>) where:
670 · name is a predefined string literal. Accepted values are:
672 · add - Returns the sum of its two operands.
674 · div - Returns the quotient of its two operands.
676 · max - Returns the largest of its two operands.
678 · min - Returns the smallest of its two operands.
680 · mul - Returns the product of its two operands.
682 · sub - Returns the difference of its two operands.
684 · <arguments> is a comma separated list of expressions.
686 For example:
688 ; CHECK: load r[[#REG:]], [r0]
690 ; CHECK: load r[[#REG+1]], [r1]
691 ; CHECK: Loading from 0x[[#%x,ADDR:]]
692 ; CHECK-SAME: to 0x[[#ADDR + 7]]
693 The above example would match the text:
695 load r5, [r0]
697 load r6, [r1]
698 Loading from 0xa0463440 to 0xa0463447
699 but would not match the text:
701 load r5, [r0]
703 load r7, [r1]
704 Loading from 0xa0463440 to 0xa0463443
705 Due to 7 being unequal to 5 + 1 and a0463443 being unequal to a0463440
707 + 7.
708 The syntax also supports an empty expression, equivalent to writing
710 {{[0-9]+}}, for cases where the input must contain a numeric value but
711 the value itself does not matter:
712 ; CHECK-NOT: mov r0, r[[#]]
714 to check that a value is synthesized rather than moved around.
716 A numeric variable can also be defined to the result of a numeric
718 expression, in which case the numeric expression constraint is checked
719 and if verified the variable is assigned to the value. The unified syn‐
720 tax for both defining numeric variables and checking a numeric expres‐
721 sion is thus [[#%<fmtspec>,<NUMVAR>: <constraint> <expr>]] with each
722 element as described previously. One can use this syntax to make a
723 testcase more self-describing by using variables instead of values:
724 ; CHECK: mov r[[#REG_OFFSET:]], 0x[[#%X,FIELD_OFFSET:12]]
726 ; CHECK-NEXT: load r[[#]], [r[[#REG_BASE:]], r[[#REG_OFFSET]]]
727 which would match:
729 mov r4, 0xC
731 load r6, [r5, r4]
732 The --enable-var-scope option has the same effect on numeric variables
734 as on string variables.
735 Important note: In its current implementation, an expression cannot use
737 a numeric variable defined earlier in the same CHECK directive.
738 FileCheck Pseudo Numeric Variables
740 Sometimes there's a need to verify output that contains line numbers of
741 the match file, e.g. when testing compiler diagnostics. This intro‐
742 duces a certain fragility of the match file structure, as "CHECK:"
743 lines contain absolute line numbers in the same file, which have to be
744 updated whenever line numbers change due to text addition or deletion.
745 To support this case, FileCheck expressions understand the @LINE pseudo
747 numeric variable which evaluates to the line number of the CHECK pat‐
748 tern where it is found.
749 This way match patterns can be put near the relevant test lines and
751 include relative line number references, for example:
752 // CHECK: test.cpp:[[# @LINE + 4]]:6: error: expected ';' after top level declarator
754 // CHECK-NEXT: {{^int a}}
755 // CHECK-NEXT: {{^ \^}}
756 // CHECK-NEXT: {{^ ;}}
757 int a
758 To support legacy uses of @LINE as a special string variable, FileCheck
760 also accepts the following uses of @LINE with string substitution block
761 syntax: [[@LINE]], [[@LINE+<offset>]] and [[@LINE-<offset>]] without
762 any spaces inside the brackets and where offset is an integer.
763 Matching Newline Characters
765 To match newline characters in regular expressions the character class
766 [[:space:]] can be used. For example, the following pattern:
767 // CHECK: DW_AT_location [DW_FORM_sec_offset] ([[DLOC:0x[0-9a-f]+]]){{[[:space:]].*}}"intd"
769 matches output of the form (from llvm-dwarfdump):
771 DW_AT_location [DW_FORM_sec_offset] (0x00000233)
773 DW_AT_name [DW_FORM_strp] ( .debug_str[0x000000c9] = "intd")
774 letting us set the FileCheck variable DLOC to the desired value
776 0x00000233, extracted from the line immediately preceding "intd".
777
779 Maintained by the LLVM Team (https://llvm.org/).
780
782 2003-2020, LLVM Project
78311 2020-10-15 FILECHECK(1)