1FILECHECK(1)                         LLVM                         FILECHECK(1)
2
3
4

NAME

6       FileCheck - Flexible pattern matching file verifier
7

SYNOPSIS

9       FileCheck match-filename [--check-prefix=XXX] [--strict-whitespace]
10

DESCRIPTION

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
20       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

OPTIONS

25       Options  are  parsed  from  the environment variable FILECHECK_OPTS and
26       from the command line.
27
28       -help  Print a summary of command line options.
29
30       --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 op‐
35              tions), the --check-prefix argument allows you to specify (with‐
36              out  the  trailing  ":") one or more prefixes to match. Multiple
37              prefixes are useful for tests which might change  for  different
38              run options, but most lines remain the same.
39
40              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
44       --check-prefixes prefix1,prefix2,...
45              An  alias  of --check-prefix that allows multiple prefixes to be
46              specified as a comma separated list.
47
48       --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  de‐
52              tails.
53
54              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  in‐
60              stead.
61
62       --input-file filename
63              File to check (defaults to stdin).
64
65       --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
72              Passing  this option is equivalent to inserting {{^ *}} or {{^}}
73              before, and {{ *$}} or {{$}} after every positive check pattern.
74
75       --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
82       --ignore-case
83              By default, FileCheck uses case-sensitive matching. This  option
84              causes FileCheck to use case-insensitive matching.
85
86       --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
91              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
97       --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
103help   - Explain input dump and quit
104
105always - Always dump input
106
107fail   - Dump input on failure
108
109never  - Never dump input
110
111       --dump-input-context <N>
112              In the dump requested by --dump-input, print <N> input lines be‐
113              fore and <N> input lines after any lines specified by --dump-in‐
114              put-filter.  When there are multiple occurrences of this option,
115              the largest specified <N> has precedence.  The default is 5.
116
117       --dump-input-filter <value>
118              In the dump requested by --dump-input, print only input lines of
119              kind <value> plus any context specified by --dump-input-context.
120              When  there are multiple occurrences of this option, the <value>
121              that appears earliest in the list below has precedence.  The de‐
122              fault  is  error  when  --dump-input=fail,  and  it's  all  when
123              --dump-input=always.
124
125all             - All input lines
126
127annotation-full - Input lines with annotations
128
129annotation      - Input lines with starting points of  annota‐
130                tions
131
132error            -  Input  lines with starting points of error
133                annotations
134
135       --enable-var-scope
136              Enables scope for regex variables.
137
138              Variables with names that start with $ are considered global and
139              remain set throughout the file.
140
141              All   other  variables  get  undefined  after  each  encountered
142              CHECK-LABEL.
143
144       -D<VAR=VALUE>
145              Sets a filecheck pattern variable VAR with value VALUE that  can
146              be used in CHECK: lines.
147
148       -D#<FMT>,<NUMVAR>=<NUMERIC EXPRESSION>
149              Sets  a filecheck numeric variable NUMVAR of matching format FMT
150              to the result of evaluating <NUMERIC  EXPRESSION>  that  can  be
151              used  in  CHECK: lines.  See section FileCheck Numeric Variables
152              and Expressions for details on supported numeric expressions.
153
154       -version
155              Show the version number of this program.
156
157       -v     Print good directive pattern  matches.   However,  if  -dump-in‐
158              put=fail or -dump-input=always, add those matches as input anno‐
159              tations instead.
160
161       -vv    Print information helpful in diagnosing internal  FileCheck  is‐
162              sues, such as discarded overlapping CHECK-DAG: matches, implicit
163              EOF pattern matches, and CHECK-NOT: patterns that  do  not  have
164              matches.  Implies -v.  However, if -dump-input=fail or -dump-in‐
165              put=always, just add that information as input  annotations  in‐
166              stead.
167
168       --allow-deprecated-dag-overlap
169              Enable  overlapping  among  matches  in  a  group of consecutive
170              CHECK-DAG: directives.  This option is deprecated  and  is  only
171              provided  for  convenience  as old tests are migrated to the new
172              non-overlapping CHECK-DAG: implementation.
173
174       --color
175              Use colors in output (autodetected by default).
176

EXIT STATUS

178       If FileCheck verifies that the file matches the expected  contents,  it
179       exits  with  0.  Otherwise, if not, or if an error occurs, it will exit
180       with a non-zero value.
181

TUTORIAL

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

AUTHOR

778       Maintained by the LLVM Team (https://llvm.org/).
779
781       2003-2023, LLVM Project
782
783
784
785
78611                                2023-07-20                      FILECHECK(1)
Impressum