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

EXIT STATUS

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

TUTORIAL

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

AUTHOR

870       Maintained by the LLVM Team (https://llvm.org/).
871
873       2003-2023, LLVM Project
874
875
876
877
87814                                2023-07-20                      FILECHECK(1)
Impressum