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       --allow-unused-prefixes
63              This  option controls the behavior when using more than one pre‐
64              fix as specified by --check-prefix or --check-prefixes, and some
65              of these prefixes are missing in the test file. If true, this is
66              allowed, if false, FileCheck will report an error,  listing  the
67              missing prefixes. The default value is false.
68
69       --input-file filename
70              File to check (defaults to stdin).
71
72       --match-full-lines
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              --strict-whitespace is also specified. (Note:  negative  matches
77              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 check pattern.
81
82       --strict-whitespace
83              By default, FileCheck canonicalizes input horizontal  whitespace
84              (spaces and tabs) which causes it to ignore these differences (a
85              space will match a tab).  The --strict-whitespace argument  dis‐
86              ables  this behavior. End-of-line sequences are canonicalized to
87              UNIX-style \n in all modes.
88
89       --ignore-case
90              By default, FileCheck uses case-sensitive matching. This  option
91              causes FileCheck to use case-insensitive matching.
92
93       --implicit-check-not check-pattern
94              Adds implicit negative checks for the specified patterns between
95              positive checks. The option allows writing stricter tests  with‐
96              out stuffing them with CHECK-NOTs.
97
98              For  example, "--implicit-check-not warning:" can be useful when
99              testing diagnostic messages from tools that don't have an option
100              similar to clang -verify. With this option FileCheck will verify
101              that input does not contain warnings not covered by  any  CHECK:
102              patterns.
103
104       --dump-input <value>
105              Dump  input to stderr, adding annotations representing currently
106              enabled diagnostics.  When there  are  multiple  occurrences  of
107              this option, the <value> that appears earliest in the list below
108              has precedence.  The default is fail.
109
110help   - Explain input dump and quit
111
112always - Always dump input
113
114fail   - Dump input on failure
115
116never  - Never dump input
117
118       --dump-input-context <N>
119              In the dump requested by --dump-input, print <N> input lines be‐
120              fore and <N> input lines after any lines specified by --dump-in‐
121              put-filter.  When there are multiple occurrences of this option,
122              the largest specified <N> has precedence.  The default is 5.
123
124       --dump-input-filter <value>
125              In the dump requested by --dump-input, print only input lines of
126              kind <value> plus any context specified by --dump-input-context.
127              When  there are multiple occurrences of this option, the <value>
128              that appears earliest in the list below has precedence.  The de‐
129              fault  is  error  when  --dump-input=fail,  and  it's  all  when
130              --dump-input=always.
131
132all             - All input lines
133
134annotation-full - Input lines with annotations
135
136annotation      - Input lines with starting points of  annota‐
137                tions
138
139error            -  Input  lines with starting points of error
140                annotations
141
142       --enable-var-scope
143              Enables scope for regex variables.
144
145              Variables with names that start with $ are considered global and
146              remain set throughout the file.
147
148              All   other  variables  get  undefined  after  each  encountered
149              CHECK-LABEL.
150
151       -D<VAR=VALUE>
152              Sets a filecheck pattern variable VAR with value VALUE that  can
153              be used in CHECK: lines.
154
155       -D#<FMT>,<NUMVAR>=<NUMERIC EXPRESSION>
156              Sets  a filecheck numeric variable NUMVAR of matching format FMT
157              to the result of evaluating <NUMERIC  EXPRESSION>  that  can  be
158              used  in  CHECK: lines.  See section FileCheck Numeric Variables
159              and Expressions for details on supported numeric expressions.
160
161       -version
162              Show the version number of this program.
163
164       -v     Print good directive pattern  matches.   However,  if  -dump-in‐
165              put=fail or -dump-input=always, add those matches as input anno‐
166              tations instead.
167
168       -vv    Print information helpful in diagnosing internal  FileCheck  is‐
169              sues, such as discarded overlapping CHECK-DAG: matches, implicit
170              EOF pattern matches, and CHECK-NOT: patterns that  do  not  have
171              matches.  Implies -v.  However, if -dump-input=fail or -dump-in‐
172              put=always, just add that information as input  annotations  in‐
173              stead.
174
175       --allow-deprecated-dag-overlap
176              Enable  overlapping  among  matches  in  a  group of consecutive
177              CHECK-DAG: directives.  This option is deprecated  and  is  only
178              provided  for  convenience  as old tests are migrated to the new
179              non-overlapping CHECK-DAG: implementation.
180
181       --allow-empty
182              Allow checking empty input. By default, empty input is rejected.
183
184       --color
185              Use colors in output (autodetected by default).
186

EXIT STATUS

188       If FileCheck verifies that the file matches the expected  contents,  it
189       exits  with  0.  Otherwise, if not, or if an error occurs, it will exit
190       with a non-zero value.
191

TUTORIAL

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

AUTHOR

867       Maintained by the LLVM Team (https://llvm.org/).
868
870       2003-2023, LLVM Project
871
872
873
874
87515                                2023-07-20                      FILECHECK(1)
Impressum