1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>FileCheck - Flexible pattern matching file verifier — LLVM 13 documentation</title>
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="tblgen - Description to C++ Code" href="tblgen.html" />
<link rel="prev" title="llvm-bcanalyzer - LLVM bitcode analyzer" href="llvm-bcanalyzer.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head><body>
<div class="logo">
<a href="../index.html">
<img src="../_static/logo.png"
alt="LLVM Logo" width="250" height="88"/></a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="tblgen.html" title="tblgen - Description to C++ Code"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="llvm-bcanalyzer.html" title="llvm-bcanalyzer - LLVM bitcode analyzer"
accesskey="P">previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="../index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="../Reference.html" >Reference</a> »</li>
<li class="nav-item nav-item-2"><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
<li class="nav-item nav-item-this"><a href="">FileCheck - Flexible pattern matching file verifier</a></li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3>Documentation</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/GettingStartedTutorials.html">Getting Started/Tutorials</a></li>
<li><a href="https://llvm.org/docs/UserGuides.html">User Guides</a></li>
<li><a href="https://llvm.org/docs/Reference.html">Reference</a></li>
</ul>
<h3>Getting Involved</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/Contributing.html">Contributing to LLVM</a></li>
<li><a href="https://llvm.org/docs/HowToSubmitABug.html">Submitting Bug Reports</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#mailing-lists">Mailing Lists</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#irc">IRC</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#meetups-and-social-events">Meetups and Social Events</a></li>
</ul>
<h3>Additional Links</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/FAQ.html">FAQ</a></li>
<li><a href="https://llvm.org/docs/Lexicon.html">Glossary</a></li>
<li><a href="https://llvm.org/pubs">Publications</a></li>
<li><a href="https://github.com/llvm/llvm-project//">Github Repository</a></li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/CommandGuide/FileCheck.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="filecheck-flexible-pattern-matching-file-verifier">
<h1>FileCheck - Flexible pattern matching file verifier<a class="headerlink" href="#filecheck-flexible-pattern-matching-file-verifier" title="Permalink to this headline">¶</a></h1>
<div class="section" id="synopsis">
<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
<p><strong class="program">FileCheck</strong> <em>match-filename</em> [<em>–check-prefix=XXX</em>] [<em>–strict-whitespace</em>]</p>
</div>
<div class="section" id="description">
<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p><strong class="program">FileCheck</strong> reads two files (one from standard input, and one
specified on the command line) and uses one to verify the other. This
behavior is particularly useful for the testsuite, which wants to verify that
the output of some tool (e.g. <strong class="program">llc</strong>) contains the expected information
(for example, a movsd from esp or whatever is interesting). This is similar to
using <strong class="program">grep</strong>, but it is optimized for matching multiple different
inputs in one file in a specific order.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">match-filename</span></code> file specifies the file that contains the patterns to
match. The file to verify is read from standard input unless the
<a class="reference internal" href="#cmdoption-FileCheck-input-file"><code class="xref std std-option docutils literal notranslate"><span class="pre">--input-file</span></code></a> option is used.</p>
</div>
<div class="section" id="options">
<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
<p>Options are parsed from the environment variable <code class="docutils literal notranslate"><span class="pre">FILECHECK_OPTS</span></code>
and from the command line.</p>
<dl class="std option">
<dt id="cmdoption-FileCheck-help">
<span id="cmdoption-filecheck-help"></span><code class="sig-name descname"><span class="pre">-help</span></code><code class="sig-prename descclassname"></code><a class="headerlink" href="#cmdoption-FileCheck-help" title="Permalink to this definition">¶</a></dt>
<dd><p>Print a summary of command line options.</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-check-prefix">
<span id="cmdoption-filecheck-check-prefix"></span><code class="sig-name descname"><span class="pre">--check-prefix</span></code><code class="sig-prename descclassname"> <span class="pre">prefix</span></code><a class="headerlink" href="#cmdoption-FileCheck-check-prefix" title="Permalink to this definition">¶</a></dt>
<dd><p>FileCheck searches the contents of <code class="docutils literal notranslate"><span class="pre">match-filename</span></code> for patterns to
match. By default, these patterns are prefixed with “<code class="docutils literal notranslate"><span class="pre">CHECK:</span></code>”.
If you’d like to use a different prefix (e.g. because the same input
file is checking multiple different tool or options), the
<a class="reference internal" href="#cmdoption-FileCheck-check-prefix"><code class="xref std std-option docutils literal notranslate"><span class="pre">--check-prefix</span></code></a> argument allows you to specify (without the trailing
“<code class="docutils literal notranslate"><span class="pre">:</span></code>”) one or more prefixes to match. Multiple prefixes are useful for tests
which might change for different run options, but most lines remain the same.</p>
<p>FileCheck does not permit duplicate prefixes, even if one is a check prefix
and one is a comment prefix (see <a class="reference internal" href="#cmdoption-FileCheck-comment-prefixes"><code class="xref std std-option docutils literal notranslate"><span class="pre">--comment-prefixes</span></code></a> below).</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-check-prefixes">
<span id="cmdoption-filecheck-check-prefixes"></span><code class="sig-name descname"><span class="pre">--check-prefixes</span></code><code class="sig-prename descclassname"> <span class="pre">prefix1,prefix2,...</span></code><a class="headerlink" href="#cmdoption-FileCheck-check-prefixes" title="Permalink to this definition">¶</a></dt>
<dd><p>An alias of <a class="reference internal" href="#cmdoption-FileCheck-check-prefix"><code class="xref std std-option docutils literal notranslate"><span class="pre">--check-prefix</span></code></a> that allows multiple prefixes to be
specified as a comma separated list.</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-comment-prefixes">
<span id="cmdoption-filecheck-comment-prefixes"></span><code class="sig-name descname"><span class="pre">--comment-prefixes</span></code><code class="sig-prename descclassname"> <span class="pre">prefix1,prefix2,...</span></code><a class="headerlink" href="#cmdoption-FileCheck-comment-prefixes" title="Permalink to this definition">¶</a></dt>
<dd><p>By default, FileCheck ignores any occurrence in <code class="docutils literal notranslate"><span class="pre">match-filename</span></code> of any check
prefix if it is preceded on the same line by “<code class="docutils literal notranslate"><span class="pre">COM:</span></code>” or “<code class="docutils literal notranslate"><span class="pre">RUN:</span></code>”. See the
section <a class="reference internal" href="#the-com-directive">The “COM:” directive</a> for usage details.</p>
<p>These default comment prefixes can be overridden by
<a class="reference internal" href="#cmdoption-FileCheck-comment-prefixes"><code class="xref std std-option docutils literal notranslate"><span class="pre">--comment-prefixes</span></code></a> if they are not appropriate for your testing
environment. However, doing so is not recommended in LLVM’s LIT-based test
suites, which should be easier to maintain if they all follow a consistent
comment style. In that case, consider proposing a change to the default
comment prefixes instead.</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-allow-unused-prefixes">
<span id="cmdoption-filecheck-allow-unused-prefixes"></span><code class="sig-name descname"><span class="pre">--allow-unused-prefixes</span></code><code class="sig-prename descclassname"></code><a class="headerlink" href="#cmdoption-FileCheck-allow-unused-prefixes" title="Permalink to this definition">¶</a></dt>
<dd><p>This option controls the behavior when using more than one prefix as specified
by <a class="reference internal" href="#cmdoption-FileCheck-check-prefix"><code class="xref std std-option docutils literal notranslate"><span class="pre">--check-prefix</span></code></a> or <a class="reference internal" href="#cmdoption-FileCheck-check-prefixes"><code class="xref std std-option docutils literal notranslate"><span class="pre">--check-prefixes</span></code></a>, and some of these
prefixes are missing in the test file. If true, this is allowed, if false,
FileCheck will report an error, listing the missing prefixes.</p>
<p>It is currently, temporarily, true by default, and will be subsequently
switched to false.</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-input-file">
<span id="cmdoption-filecheck-input-file"></span><code class="sig-name descname"><span class="pre">--input-file</span></code><code class="sig-prename descclassname"> <span class="pre">filename</span></code><a class="headerlink" href="#cmdoption-FileCheck-input-file" title="Permalink to this definition">¶</a></dt>
<dd><p>File to check (defaults to stdin).</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-match-full-lines">
<span id="cmdoption-filecheck-match-full-lines"></span><code class="sig-name descname"><span class="pre">--match-full-lines</span></code><code class="sig-prename descclassname"></code><a class="headerlink" href="#cmdoption-FileCheck-match-full-lines" title="Permalink to this definition">¶</a></dt>
<dd><p>By default, FileCheck allows matches of anywhere on a line. This
option will require all positive matches to cover an entire
line. Leading and trailing whitespace is ignored, unless
<a class="reference internal" href="#cmdoption-FileCheck-strict-whitespace"><code class="xref std std-option docutils literal notranslate"><span class="pre">--strict-whitespace</span></code></a> is also specified. (Note: negative
matches from <code class="docutils literal notranslate"><span class="pre">CHECK-NOT</span></code> are not affected by this option!)</p>
<p>Passing this option is equivalent to inserting <code class="docutils literal notranslate"><span class="pre">{{^</span> <span class="pre">*}}</span></code> or
<code class="docutils literal notranslate"><span class="pre">{{^}}</span></code> before, and <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">*$}}</span></code> or <code class="docutils literal notranslate"><span class="pre">{{$}}</span></code> after every positive
check pattern.</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-strict-whitespace">
<span id="cmdoption-filecheck-strict-whitespace"></span><code class="sig-name descname"><span class="pre">--strict-whitespace</span></code><code class="sig-prename descclassname"></code><a class="headerlink" href="#cmdoption-FileCheck-strict-whitespace" title="Permalink to this definition">¶</a></dt>
<dd><p>By default, FileCheck canonicalizes input horizontal whitespace (spaces and
tabs) which causes it to ignore these differences (a space will match a tab).
The <a class="reference internal" href="#cmdoption-FileCheck-strict-whitespace"><code class="xref std std-option docutils literal notranslate"><span class="pre">--strict-whitespace</span></code></a> argument disables this behavior. End-of-line
sequences are canonicalized to UNIX-style <code class="docutils literal notranslate"><span class="pre">\n</span></code> in all modes.</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-ignore-case">
<span id="cmdoption-filecheck-ignore-case"></span><code class="sig-name descname"><span class="pre">--ignore-case</span></code><code class="sig-prename descclassname"></code><a class="headerlink" href="#cmdoption-FileCheck-ignore-case" title="Permalink to this definition">¶</a></dt>
<dd><p>By default, FileCheck uses case-sensitive matching. This option causes
FileCheck to use case-insensitive matching.</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-implicit-check-not">
<span id="cmdoption-filecheck-implicit-check-not"></span><code class="sig-name descname"><span class="pre">--implicit-check-not</span></code><code class="sig-prename descclassname"> <span class="pre">check-pattern</span></code><a class="headerlink" href="#cmdoption-FileCheck-implicit-check-not" title="Permalink to this definition">¶</a></dt>
<dd><p>Adds implicit negative checks for the specified patterns between positive
checks. The option allows writing stricter tests without stuffing them with
<code class="docutils literal notranslate"><span class="pre">CHECK-NOT</span></code>s.</p>
<p>For example, “<code class="docutils literal notranslate"><span class="pre">--implicit-check-not</span> <span class="pre">warning:</span></code>” can be useful when testing
diagnostic messages from tools that don’t have an option similar to <code class="docutils literal notranslate"><span class="pre">clang</span>
<span class="pre">-verify</span></code>. With this option FileCheck will verify that input does not contain
warnings not covered by any <code class="docutils literal notranslate"><span class="pre">CHECK:</span></code> patterns.</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-dump-input">
<span id="cmdoption-filecheck-dump-input"></span><code class="sig-name descname"><span class="pre">--dump-input</span></code><code class="sig-prename descclassname"> <span class="pre"><value></span></code><a class="headerlink" href="#cmdoption-FileCheck-dump-input" title="Permalink to this definition">¶</a></dt>
<dd><p>Dump input to stderr, adding annotations representing currently enabled
diagnostics. When there are multiple occurrences of this option, the
<code class="docutils literal notranslate"><span class="pre"><value></span></code> that appears earliest in the list below has precedence. The
default is <code class="docutils literal notranslate"><span class="pre">fail</span></code>.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">help</span></code> - Explain input dump and quit</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">always</span></code> - Always dump input</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fail</span></code> - Dump input on failure</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">never</span></code> - Never dump input</p></li>
</ul>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-dump-input-context">
<span id="cmdoption-filecheck-dump-input-context"></span><code class="sig-name descname"><span class="pre">--dump-input-context</span></code><code class="sig-prename descclassname"> <span class="pre"><N></span></code><a class="headerlink" href="#cmdoption-FileCheck-dump-input-context" title="Permalink to this definition">¶</a></dt>
<dd><p>In the dump requested by <code class="docutils literal notranslate"><span class="pre">--dump-input</span></code>, print <code class="docutils literal notranslate"><span class="pre"><N></span></code> input lines before
and <code class="docutils literal notranslate"><span class="pre"><N></span></code> input lines after any lines specified by <code class="docutils literal notranslate"><span class="pre">--dump-input-filter</span></code>.
When there are multiple occurrences of this option, the largest specified
<code class="docutils literal notranslate"><span class="pre"><N></span></code> has precedence. The default is 5.</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-dump-input-filter">
<span id="cmdoption-filecheck-dump-input-filter"></span><code class="sig-name descname"><span class="pre">--dump-input-filter</span></code><code class="sig-prename descclassname"> <span class="pre"><value></span></code><a class="headerlink" href="#cmdoption-FileCheck-dump-input-filter" title="Permalink to this definition">¶</a></dt>
<dd><p>In the dump requested by <code class="docutils literal notranslate"><span class="pre">--dump-input</span></code>, print only input lines of kind
<code class="docutils literal notranslate"><span class="pre"><value></span></code> plus any context specified by <code class="docutils literal notranslate"><span class="pre">--dump-input-context</span></code>. When
there are multiple occurrences of this option, the <code class="docutils literal notranslate"><span class="pre"><value></span></code> that appears
earliest in the list below has precedence. The default is <code class="docutils literal notranslate"><span class="pre">error</span></code> when
<code class="docutils literal notranslate"><span class="pre">--dump-input=fail</span></code>, and it’s <code class="docutils literal notranslate"><span class="pre">all</span></code> when <code class="docutils literal notranslate"><span class="pre">--dump-input=always</span></code>.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">all</span></code> - All input lines</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">annotation-full</span></code> - Input lines with annotations</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">annotation</span></code> - Input lines with starting points of annotations</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">error</span></code> - Input lines with starting points of error annotations</p></li>
</ul>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-enable-var-scope">
<span id="cmdoption-filecheck-enable-var-scope"></span><code class="sig-name descname"><span class="pre">--enable-var-scope</span></code><code class="sig-prename descclassname"></code><a class="headerlink" href="#cmdoption-FileCheck-enable-var-scope" title="Permalink to this definition">¶</a></dt>
<dd><p>Enables scope for regex variables.</p>
<p>Variables with names that start with <code class="docutils literal notranslate"><span class="pre">$</span></code> are considered global and
remain set throughout the file.</p>
<p>All other variables get undefined after each encountered <code class="docutils literal notranslate"><span class="pre">CHECK-LABEL</span></code>.</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-D-VAR">
<span id="cmdoption-filecheck-d-var"></span><code class="sig-name descname"><span class="pre">-D<VAR</span></code><code class="sig-prename descclassname"><span class="pre">=VALUE></span></code><a class="headerlink" href="#cmdoption-FileCheck-D-VAR" title="Permalink to this definition">¶</a></dt>
<dd><p>Sets a filecheck pattern variable <code class="docutils literal notranslate"><span class="pre">VAR</span></code> with value <code class="docutils literal notranslate"><span class="pre">VALUE</span></code> that can be
used in <code class="docutils literal notranslate"><span class="pre">CHECK:</span></code> lines.</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-D-FMT-NUMVAR">
<span id="cmdoption-filecheck-d-fmt-numvar"></span><code class="sig-name descname"><span class="pre">-D#<FMT>,<NUMVAR></span></code><code class="sig-prename descclassname"><span class="pre">=<NUMERIC</span> <span class="pre">EXPRESSION></span></code><a class="headerlink" href="#cmdoption-FileCheck-D-FMT-NUMVAR" title="Permalink to this definition">¶</a></dt>
<dd><p>Sets a filecheck numeric variable <code class="docutils literal notranslate"><span class="pre">NUMVAR</span></code> of matching format <code class="docutils literal notranslate"><span class="pre">FMT</span></code> to
the result of evaluating <code class="docutils literal notranslate"><span class="pre"><NUMERIC</span> <span class="pre">EXPRESSION></span></code> that can be used in
<code class="docutils literal notranslate"><span class="pre">CHECK:</span></code> lines. See section
<code class="docutils literal notranslate"><span class="pre">FileCheck</span> <span class="pre">Numeric</span> <span class="pre">Variables</span> <span class="pre">and</span> <span class="pre">Expressions</span></code> for details on supported
numeric expressions.</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-version">
<span id="cmdoption-filecheck-version"></span><code class="sig-name descname"><span class="pre">-version</span></code><code class="sig-prename descclassname"></code><a class="headerlink" href="#cmdoption-FileCheck-version" title="Permalink to this definition">¶</a></dt>
<dd><p>Show the version number of this program.</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-v">
<span id="cmdoption-filecheck-v"></span><code class="sig-name descname"><span class="pre">-v</span></code><code class="sig-prename descclassname"></code><a class="headerlink" href="#cmdoption-FileCheck-v" title="Permalink to this definition">¶</a></dt>
<dd><p>Print good directive pattern matches. However, if <code class="docutils literal notranslate"><span class="pre">-dump-input=fail</span></code> or
<code class="docutils literal notranslate"><span class="pre">-dump-input=always</span></code>, add those matches as input annotations instead.</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-vv">
<span id="cmdoption-filecheck-vv"></span><code class="sig-name descname"><span class="pre">-vv</span></code><code class="sig-prename descclassname"></code><a class="headerlink" href="#cmdoption-FileCheck-vv" title="Permalink to this definition">¶</a></dt>
<dd><p>Print information helpful in diagnosing internal FileCheck issues, such as
discarded overlapping <code class="docutils literal notranslate"><span class="pre">CHECK-DAG:</span></code> matches, implicit EOF pattern matches,
and <code class="docutils literal notranslate"><span class="pre">CHECK-NOT:</span></code> patterns that do not have matches. Implies <code class="docutils literal notranslate"><span class="pre">-v</span></code>.
However, if <code class="docutils literal notranslate"><span class="pre">-dump-input=fail</span></code> or <code class="docutils literal notranslate"><span class="pre">-dump-input=always</span></code>, just add that
information as input annotations instead.</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-allow-deprecated-dag-overlap">
<span id="cmdoption-filecheck-allow-deprecated-dag-overlap"></span><code class="sig-name descname"><span class="pre">--allow-deprecated-dag-overlap</span></code><code class="sig-prename descclassname"></code><a class="headerlink" href="#cmdoption-FileCheck-allow-deprecated-dag-overlap" title="Permalink to this definition">¶</a></dt>
<dd><p>Enable overlapping among matches in a group of consecutive <code class="docutils literal notranslate"><span class="pre">CHECK-DAG:</span></code>
directives. This option is deprecated and is only provided for convenience
as old tests are migrated to the new non-overlapping <code class="docutils literal notranslate"><span class="pre">CHECK-DAG:</span></code>
implementation.</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-allow-empty">
<span id="cmdoption-filecheck-allow-empty"></span><code class="sig-name descname"><span class="pre">--allow-empty</span></code><code class="sig-prename descclassname"></code><a class="headerlink" href="#cmdoption-FileCheck-allow-empty" title="Permalink to this definition">¶</a></dt>
<dd><p>Allow checking empty input. By default, empty input is rejected.</p>
</dd></dl>
<dl class="std option">
<dt id="cmdoption-FileCheck-color">
<span id="cmdoption-filecheck-color"></span><code class="sig-name descname"><span class="pre">--color</span></code><code class="sig-prename descclassname"></code><a class="headerlink" href="#cmdoption-FileCheck-color" title="Permalink to this definition">¶</a></dt>
<dd><p>Use colors in output (autodetected by default).</p>
</dd></dl>
</div>
<div class="section" id="exit-status">
<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
<p>If <strong class="program">FileCheck</strong> verifies that the file matches the expected contents,
it exits with 0. Otherwise, if not, or if an error occurs, it will exit with a
non-zero value.</p>
</div>
<div class="section" id="tutorial">
<h2>TUTORIAL<a class="headerlink" href="#tutorial" title="Permalink to this headline">¶</a></h2>
<p>FileCheck is typically used from LLVM regression tests, being invoked on the RUN
line of the test. A simple example of using FileCheck from a RUN line looks
like this:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="c">; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s</span>
</pre></div>
</div>
<p>This syntax says to pipe the current file (“<code class="docutils literal notranslate"><span class="pre">%s</span></code>”) into <code class="docutils literal notranslate"><span class="pre">llvm-as</span></code>, pipe
that into <code class="docutils literal notranslate"><span class="pre">llc</span></code>, then pipe the output of <code class="docutils literal notranslate"><span class="pre">llc</span></code> into <code class="docutils literal notranslate"><span class="pre">FileCheck</span></code>. This
means that FileCheck will be verifying its standard input (the llc output)
against the filename argument specified (the original <code class="docutils literal notranslate"><span class="pre">.ll</span></code> file specified by
“<code class="docutils literal notranslate"><span class="pre">%s</span></code>”). To see how this works, let’s look at the rest of the <code class="docutils literal notranslate"><span class="pre">.ll</span></code> file
(after the RUN line):</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">void</span> <span class="vg">@sub1</span><span class="p">(</span><span class="k">i32</span><span class="p">*</span> <span class="nv">%p</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%v</span><span class="p">)</span> <span class="p">{</span>
<span class="nl">entry:</span>
<span class="c">; CHECK: sub1:</span>
<span class="c">; CHECK: subl</span>
<span class="nv nv-Anonymous">%0</span> <span class="p">=</span> <span class="k">tail</span> <span class="k">call</span> <span class="k">i32</span> <span class="vg">@llvm.atomic.load.sub.i32.p0i32</span><span class="p">(</span><span class="k">i32</span><span class="p">*</span> <span class="nv">%p</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%v</span><span class="p">)</span>
<span class="k">ret</span> <span class="k">void</span>
<span class="p">}</span>
<span class="k">define</span> <span class="k">void</span> <span class="vg">@inc4</span><span class="p">(</span><span class="k">i64</span><span class="p">*</span> <span class="nv">%p</span><span class="p">)</span> <span class="p">{</span>
<span class="nl">entry:</span>
<span class="c">; CHECK: inc4:</span>
<span class="c">; CHECK: incq</span>
<span class="nv nv-Anonymous">%0</span> <span class="p">=</span> <span class="k">tail</span> <span class="k">call</span> <span class="k">i64</span> <span class="vg">@llvm.atomic.load.add.i64.p0i64</span><span class="p">(</span><span class="k">i64</span><span class="p">*</span> <span class="nv">%p</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span><span class="p">)</span>
<span class="k">ret</span> <span class="k">void</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Here you can see some “<code class="docutils literal notranslate"><span class="pre">CHECK:</span></code>” lines specified in comments. Now you can
see how the file is piped into <code class="docutils literal notranslate"><span class="pre">llvm-as</span></code>, then <code class="docutils literal notranslate"><span class="pre">llc</span></code>, and the machine code
output is what we are verifying. FileCheck checks the machine code output to
verify that it matches what the “<code class="docutils literal notranslate"><span class="pre">CHECK:</span></code>” lines specify.</p>
<p>The syntax of the “<code class="docutils literal notranslate"><span class="pre">CHECK:</span></code>” lines is very simple: they are fixed strings that
must occur in order. FileCheck defaults to ignoring horizontal whitespace
differences (e.g. a space is allowed to match a tab) but otherwise, the contents
of the “<code class="docutils literal notranslate"><span class="pre">CHECK:</span></code>” line is required to match some thing in the test file exactly.</p>
<p>One nice thing about FileCheck (compared to grep) is that it allows merging
test cases together into logical groups. For example, because the test above
is checking for the “<code class="docutils literal notranslate"><span class="pre">sub1:</span></code>” and “<code class="docutils literal notranslate"><span class="pre">inc4:</span></code>” labels, it will not match
unless there is a “<code class="docutils literal notranslate"><span class="pre">subl</span></code>” in between those labels. If it existed somewhere
else in the file, that would not count: “<code class="docutils literal notranslate"><span class="pre">grep</span> <span class="pre">subl</span></code>” matches if “<code class="docutils literal notranslate"><span class="pre">subl</span></code>”
exists anywhere in the file.</p>
<div class="section" id="the-filecheck-check-prefix-option">
<h3>The FileCheck -check-prefix option<a class="headerlink" href="#the-filecheck-check-prefix-option" title="Permalink to this headline">¶</a></h3>
<p>The FileCheck <cite>-check-prefix</cite> option allows multiple test
configurations to be driven from one <cite>.ll</cite> file. This is useful in many
circumstances, for example, testing different architectural variants with
<strong class="program">llc</strong>. Here’s a simple example:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="c">; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \</span>
<span class="c">; RUN: | FileCheck %s -check-prefix=X32</span>
<span class="c">; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \</span>
<span class="c">; RUN: | FileCheck %s -check-prefix=X64</span>
<span class="k">define</span> <span class="p"><</span><span class="m">4</span> <span class="k">x</span> <span class="k">i32</span><span class="p">></span> <span class="vg">@pinsrd_1</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%s</span><span class="p">,</span> <span class="p"><</span><span class="m">4</span> <span class="k">x</span> <span class="k">i32</span><span class="p">></span> <span class="nv">%tmp</span><span class="p">)</span> <span class="k">nounwind</span> <span class="p">{</span>
<span class="nv">%tmp1</span> <span class="p">=</span> <span class="k">insertelement</span> <span class="p"><</span><span class="m">4</span> <span class="k">x</span> <span class="k">i32</span><span class="p">></span><span class="c">; %tmp, i32 %s, i32 1</span>
<span class="k">ret</span> <span class="p"><</span><span class="m">4</span> <span class="k">x</span> <span class="k">i32</span><span class="p">></span> <span class="nv">%tmp1</span>
<span class="c">; X32: pinsrd_1:</span>
<span class="c">; X32: pinsrd $1, 4(%esp), %xmm0</span>
<span class="c">; X64: pinsrd_1:</span>
<span class="c">; X64: pinsrd $1, %edi, %xmm0</span>
<span class="p">}</span>
</pre></div>
</div>
<p>In this case, we’re testing that we get the expected code generation with
both 32-bit and 64-bit code generation.</p>
</div>
<div class="section" id="the-com-directive">
<h3>The “COM:” directive<a class="headerlink" href="#the-com-directive" title="Permalink to this headline">¶</a></h3>
<p>Sometimes you want to disable a FileCheck directive without removing it
entirely, or you want to write comments that mention a directive by name. The
“<code class="docutils literal notranslate"><span class="pre">COM:</span></code>” directive makes it easy to do this. For example, you might have:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="c">; X32: pinsrd_1:</span>
<span class="c">; X32: pinsrd $1, 4(%esp), %xmm0</span>
<span class="c">; COM: FIXME: X64 isn't working correctly yet for this part of codegen, but</span>
<span class="c">; COM: X64 will have something similar to X32:</span>
<span class="c">; COM:</span>
<span class="c">; COM: X64: pinsrd_1:</span>
<span class="c">; COM: X64: pinsrd $1, %edi, %xmm0</span>
</pre></div>
</div>
<p>Without “<code class="docutils literal notranslate"><span class="pre">COM:</span></code>”, you would need to use some combination of rewording and
directive syntax mangling to prevent FileCheck from recognizing the commented
occurrences of “<code class="docutils literal notranslate"><span class="pre">X32:</span></code>” and “<code class="docutils literal notranslate"><span class="pre">X64:</span></code>” above as directives. Moreover,
FileCheck diagnostics have been proposed that might complain about the above
occurrences of “<code class="docutils literal notranslate"><span class="pre">X64</span></code>” that don’t have the trailing “<code class="docutils literal notranslate"><span class="pre">:</span></code>” because they look
like directive typos. Dodging all these problems can be tedious for a test
author, and directive syntax mangling can make the purpose of test code unclear.
“<code class="docutils literal notranslate"><span class="pre">COM:</span></code>” avoids all these problems.</p>
<p>A few important usage notes:</p>
<ul>
<li><p>“<code class="docutils literal notranslate"><span class="pre">COM:</span></code>” within another directive’s pattern does <em>not</em> comment out the
remainder of the pattern. For example:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="c">; X32: pinsrd $1, 4(%esp), %xmm0 COM: This is part of the X32 pattern!</span>
</pre></div>
</div>
<p>If you need to temporarily comment out part of a directive’s pattern, move it
to another line. The reason is that FileCheck parses “<code class="docutils literal notranslate"><span class="pre">COM:</span></code>” in the same
manner as any other directive: only the first directive on the line is
recognized as a directive.</p>
</li>
<li><p>For the sake of LIT, FileCheck treats “<code class="docutils literal notranslate"><span class="pre">RUN:</span></code>” just like “<code class="docutils literal notranslate"><span class="pre">COM:</span></code>”. If this
is not suitable for your test environment, see <a class="reference internal" href="#cmdoption-FileCheck-comment-prefixes"><code class="xref std std-option docutils literal notranslate"><span class="pre">--comment-prefixes</span></code></a>.</p></li>
<li><p>FileCheck does not recognize “<code class="docutils literal notranslate"><span class="pre">COM</span></code>”, “<code class="docutils literal notranslate"><span class="pre">RUN</span></code>”, or any user-defined comment
prefix as a comment directive if it’s combined with one of the usual check
directive suffixes, such as “<code class="docutils literal notranslate"><span class="pre">-NEXT:</span></code>” or “<code class="docutils literal notranslate"><span class="pre">-NOT:</span></code>”, discussed below.
FileCheck treats such a combination as plain text instead. If it needs to act
as a comment directive for your test environment, define it as such with
<a class="reference internal" href="#cmdoption-FileCheck-comment-prefixes"><code class="xref std std-option docutils literal notranslate"><span class="pre">--comment-prefixes</span></code></a>.</p></li>
</ul>
</div>
<div class="section" id="the-check-next-directive">
<h3>The “CHECK-NEXT:” directive<a class="headerlink" href="#the-check-next-directive" title="Permalink to this headline">¶</a></h3>
<p>Sometimes you want to match lines and would like to verify that matches
happen on exactly consecutive lines with no other lines in between them. In
this case, you can use “<code class="docutils literal notranslate"><span class="pre">CHECK:</span></code>” and “<code class="docutils literal notranslate"><span class="pre">CHECK-NEXT:</span></code>” directives to specify
this. If you specified a custom check prefix, just use “<code class="docutils literal notranslate"><span class="pre"><PREFIX>-NEXT:</span></code>”.
For example, something like this works as you’d expect:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">void</span> <span class="vg">@t2</span><span class="p">(<</span><span class="m">2</span> <span class="k">x</span> <span class="k">double</span><span class="p">>*</span> <span class="nv">%r</span><span class="p">,</span> <span class="p"><</span><span class="m">2</span> <span class="k">x</span> <span class="k">double</span><span class="p">>*</span> <span class="nv">%A</span><span class="p">,</span> <span class="k">double</span> <span class="nv">%B</span><span class="p">)</span> <span class="p">{</span>
<span class="nv">%tmp3</span> <span class="p">=</span> <span class="k">load</span> <span class="p"><</span><span class="m">2</span> <span class="k">x</span> <span class="k">double</span><span class="p">>*</span> <span class="nv">%A</span><span class="p">,</span> <span class="k">align</span> <span class="m">16</span>
<span class="nv">%tmp7</span> <span class="p">=</span> <span class="k">insertelement</span> <span class="p"><</span><span class="m">2</span> <span class="k">x</span> <span class="k">double</span><span class="p">></span> <span class="k">undef</span><span class="p">,</span> <span class="k">double</span> <span class="nv">%B</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span>
<span class="nv">%tmp9</span> <span class="p">=</span> <span class="k">shufflevector</span> <span class="p"><</span><span class="m">2</span> <span class="k">x</span> <span class="k">double</span><span class="p">></span> <span class="nv">%tmp3</span><span class="p">,</span>
<span class="p"><</span><span class="m">2</span> <span class="k">x</span> <span class="k">double</span><span class="p">></span> <span class="nv">%tmp7</span><span class="p">,</span>
<span class="p"><</span><span class="m">2</span> <span class="k">x</span> <span class="k">i32</span><span class="p">></span> <span class="p"><</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">2</span> <span class="p">></span>
<span class="k">store</span> <span class="p"><</span><span class="m">2</span> <span class="k">x</span> <span class="k">double</span><span class="p">></span> <span class="nv">%tmp9</span><span class="p">,</span> <span class="p"><</span><span class="m">2</span> <span class="k">x</span> <span class="k">double</span><span class="p">>*</span> <span class="nv">%r</span><span class="p">,</span> <span class="k">align</span> <span class="m">16</span>
<span class="k">ret</span> <span class="k">void</span>
<span class="c">; CHECK: t2:</span>
<span class="c">; CHECK: movl 8(%esp), %eax</span>
<span class="c">; CHECK-NEXT: movapd (%eax), %xmm0</span>
<span class="c">; CHECK-NEXT: movhpd 12(%esp), %xmm0</span>
<span class="c">; CHECK-NEXT: movl 4(%esp), %eax</span>
<span class="c">; CHECK-NEXT: movapd %xmm0, (%eax)</span>
<span class="c">; CHECK-NEXT: ret</span>
<span class="p">}</span>
</pre></div>
</div>
<p>“<code class="docutils literal notranslate"><span class="pre">CHECK-NEXT:</span></code>” directives reject the input unless there is exactly one
newline between it and the previous directive. A “<code class="docutils literal notranslate"><span class="pre">CHECK-NEXT:</span></code>” cannot be
the first directive in a file.</p>
</div>
<div class="section" id="the-check-same-directive">
<h3>The “CHECK-SAME:” directive<a class="headerlink" href="#the-check-same-directive" title="Permalink to this headline">¶</a></h3>
<p>Sometimes you want to match lines and would like to verify that matches happen
on the same line as the previous match. In this case, you can use “<code class="docutils literal notranslate"><span class="pre">CHECK:</span></code>”
and “<code class="docutils literal notranslate"><span class="pre">CHECK-SAME:</span></code>” directives to specify this. If you specified a custom
check prefix, just use “<code class="docutils literal notranslate"><span class="pre"><PREFIX>-SAME:</span></code>”.</p>
<p>“<code class="docutils literal notranslate"><span class="pre">CHECK-SAME:</span></code>” is particularly powerful in conjunction with “<code class="docutils literal notranslate"><span class="pre">CHECK-NOT:</span></code>”
(described below).</p>
<p>For example, the following works like you’d expect:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="nv nv-Anonymous">!0</span> <span class="p">=</span> <span class="nv">!DILocation</span><span class="p">(</span><span class="nl">line:</span> <span class="m">5</span><span class="p">,</span> <span class="nl">scope:</span> <span class="nv nv-Anonymous">!1</span><span class="p">,</span> <span class="nl">inlinedAt:</span> <span class="nv nv-Anonymous">!2</span><span class="p">)</span>
<span class="c">; CHECK: !DILocation(line: 5,</span>
<span class="c">; CHECK-NOT: column:</span>
<span class="c">; CHECK-SAME: scope: ![[SCOPE:[0-9]+]]</span>
</pre></div>
</div>
<p>“<code class="docutils literal notranslate"><span class="pre">CHECK-SAME:</span></code>” directives reject the input if there are any newlines between
it and the previous directive.</p>
<p>“<code class="docutils literal notranslate"><span class="pre">CHECK-SAME:</span></code>” is also useful to avoid writing matchers for irrelevant
fields. For example, suppose you’re writing a test which parses a tool that
generates output like this:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Name: foo
Field1: ...
Field2: ...
Field3: ...
Value: 1
Name: bar
Field1: ...
Field2: ...
Field3: ...
Value: 2
Name: baz
Field1: ...
Field2: ...
Field3: ...
Value: 1
</pre></div>
</div>
<p>To write a test that verifies <code class="docutils literal notranslate"><span class="pre">foo</span></code> has the value <code class="docutils literal notranslate"><span class="pre">1</span></code>, you might first
write this:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>CHECK: Name: foo
CHECK: Value: 1{{$}}
</pre></div>
</div>
<p>However, this would be a bad test: if the value for <code class="docutils literal notranslate"><span class="pre">foo</span></code> changes, the test
would still pass because the “<code class="docutils literal notranslate"><span class="pre">CHECK:</span> <span class="pre">Value:</span> <span class="pre">1</span></code>” line would match the value
from <code class="docutils literal notranslate"><span class="pre">baz</span></code>. To fix this, you could add <code class="docutils literal notranslate"><span class="pre">CHECK-NEXT</span></code> matchers for every
<code class="docutils literal notranslate"><span class="pre">FieldN:</span></code> line, but that would be verbose, and need to be updated when
<code class="docutils literal notranslate"><span class="pre">Field4</span></code> is added. A more succinct way to write the test using the
“<code class="docutils literal notranslate"><span class="pre">CHECK-SAME:</span></code>” matcher would be as follows:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>CHECK: Name: foo
CHECK: Value:
CHECK-SAME: {{ 1$}}
</pre></div>
</div>
<p>This verifies that the <em>next</em> time “<code class="docutils literal notranslate"><span class="pre">Value:</span></code>” appears in the output, it has
the value <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p>
<p>Note: a “<code class="docutils literal notranslate"><span class="pre">CHECK-SAME:</span></code>” cannot be the first directive in a file.</p>
</div>
<div class="section" id="the-check-empty-directive">
<h3>The “CHECK-EMPTY:” directive<a class="headerlink" href="#the-check-empty-directive" title="Permalink to this headline">¶</a></h3>
<p>If you need to check that the next line has nothing on it, not even whitespace,
you can use the “<code class="docutils literal notranslate"><span class="pre">CHECK-EMPTY:</span></code>” directive.</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">declare</span> <span class="k">void</span> <span class="vg">@foo</span><span class="p">()</span>
<span class="k">declare</span> <span class="k">void</span> <span class="vg">@bar</span><span class="p">()</span>
<span class="c">; CHECK: foo</span>
<span class="c">; CHECK-EMPTY:</span>
<span class="c">; CHECK-NEXT: bar</span>
</pre></div>
</div>
<p>Just like “<code class="docutils literal notranslate"><span class="pre">CHECK-NEXT:</span></code>” the directive will fail if there is more than one
newline before it finds the next blank line, and it cannot be the first
directive in a file.</p>
</div>
<div class="section" id="the-check-not-directive">
<h3>The “CHECK-NOT:” directive<a class="headerlink" href="#the-check-not-directive" title="Permalink to this headline">¶</a></h3>
<p>The “<code class="docutils literal notranslate"><span class="pre">CHECK-NOT:</span></code>” directive is used to verify that a string doesn’t occur
between two matches (or before the first match, or after the last match). For
example, to verify that a load is removed by a transformation, a test like this
can be used:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">i8</span> <span class="vg">@coerce_offset0</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%V</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%P</span><span class="p">)</span> <span class="p">{</span>
<span class="k">store</span> <span class="k">i32</span> <span class="nv">%V</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%P</span>
<span class="nv">%P2</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%P</span> <span class="k">to</span> <span class="k">i8</span><span class="p">*</span>
<span class="nv">%P3</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%P2</span><span class="p">,</span> <span class="k">i32</span> <span class="m">2</span>
<span class="nv">%A</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%P3</span>
<span class="k">ret</span> <span class="k">i8</span> <span class="nv">%A</span>
<span class="c">; CHECK: @coerce_offset0</span>
<span class="c">; CHECK-NOT: load</span>
<span class="c">; CHECK: ret i8</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="the-check-count-directive">
<h3>The “CHECK-COUNT:” directive<a class="headerlink" href="#the-check-count-directive" title="Permalink to this headline">¶</a></h3>
<p>If you need to match multiple lines with the same pattern over and over again
you can repeat a plain <code class="docutils literal notranslate"><span class="pre">CHECK:</span></code> as many times as needed. If that looks too
boring you can instead use a counted check “<code class="docutils literal notranslate"><span class="pre">CHECK-COUNT-<num>:</span></code>”, where
<code class="docutils literal notranslate"><span class="pre"><num></span></code> is a positive decimal number. It will match the pattern exactly
<code class="docutils literal notranslate"><span class="pre"><num></span></code> times, no more and no less. If you specified a custom check prefix,
just use “<code class="docutils literal notranslate"><span class="pre"><PREFIX>-COUNT-<num>:</span></code>” for the same effect.
Here is a simple example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Loop at depth 1
Loop at depth 1
Loop at depth 1
Loop at depth 1
Loop at depth 2
Loop at depth 3
; CHECK-COUNT-6: Loop at depth {{[0-9]+}}
; CHECK-NOT: Loop at depth {{[0-9]+}}
</pre></div>
</div>
</div>
<div class="section" id="the-check-dag-directive">
<h3>The “CHECK-DAG:” directive<a class="headerlink" href="#the-check-dag-directive" title="Permalink to this headline">¶</a></h3>
<p>If it’s necessary to match strings that don’t occur in a strictly sequential
order, “<code class="docutils literal notranslate"><span class="pre">CHECK-DAG:</span></code>” could be used to verify them between two matches (or
before the first match, or after the last match). For example, clang emits
vtable globals in reverse order. Using <code class="docutils literal notranslate"><span class="pre">CHECK-DAG:</span></code>, we can keep the checks
in the natural order:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// RUN: %clang_cc1 %s -emit-llvm -o - | FileCheck %s</span>
<span class="k">struct</span> <span class="nc">Foo</span> <span class="p">{</span> <span class="k">virtual</span> <span class="kt">void</span> <span class="n">method</span><span class="p">();</span> <span class="p">};</span>
<span class="n">Foo</span> <span class="n">f</span><span class="p">;</span> <span class="c1">// emit vtable</span>
<span class="c1">// CHECK-DAG: @_ZTV3Foo =</span>
<span class="k">struct</span> <span class="nc">Bar</span> <span class="p">{</span> <span class="k">virtual</span> <span class="kt">void</span> <span class="n">method</span><span class="p">();</span> <span class="p">};</span>
<span class="n">Bar</span> <span class="n">b</span><span class="p">;</span>
<span class="c1">// CHECK-DAG: @_ZTV3Bar =</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">CHECK-NOT:</span></code> directives could be mixed with <code class="docutils literal notranslate"><span class="pre">CHECK-DAG:</span></code> directives to
exclude strings between the surrounding <code class="docutils literal notranslate"><span class="pre">CHECK-DAG:</span></code> directives. As a result,
the surrounding <code class="docutils literal notranslate"><span class="pre">CHECK-DAG:</span></code> directives cannot be reordered, i.e. all
occurrences matching <code class="docutils literal notranslate"><span class="pre">CHECK-DAG:</span></code> before <code class="docutils literal notranslate"><span class="pre">CHECK-NOT:</span></code> must not fall behind
occurrences matching <code class="docutils literal notranslate"><span class="pre">CHECK-DAG:</span></code> after <code class="docutils literal notranslate"><span class="pre">CHECK-NOT:</span></code>. For example,</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="c">; CHECK-DAG: BEFORE</span>
<span class="c">; CHECK-NOT: NOT</span>
<span class="c">; CHECK-DAG: AFTER</span>
</pre></div>
</div>
<p>This case will reject input strings where <code class="docutils literal notranslate"><span class="pre">BEFORE</span></code> occurs after <code class="docutils literal notranslate"><span class="pre">AFTER</span></code>.</p>
<p>With captured variables, <code class="docutils literal notranslate"><span class="pre">CHECK-DAG:</span></code> is able to match valid topological
orderings of a DAG with edges from the definition of a variable to its use.
It’s useful, e.g., when your test cases need to match different output
sequences from the instruction scheduler. For example,</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="c">; CHECK-DAG: add [[REG1:r[0-9]+]], r1, r2</span>
<span class="c">; CHECK-DAG: add [[REG2:r[0-9]+]], r3, r4</span>
<span class="c">; CHECK: mul r5, [[REG1]], [[REG2]]</span>
</pre></div>
</div>
<p>In this case, any order of that two <code class="docutils literal notranslate"><span class="pre">add</span></code> instructions will be allowed.</p>
<p>If you are defining <cite>and</cite> using variables in the same <code class="docutils literal notranslate"><span class="pre">CHECK-DAG:</span></code> block,
be aware that the definition rule can match <cite>after</cite> its use.</p>
<p>So, for instance, the code below will pass:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]
; CHECK-DAG: vmov.32 [[REG2]][1]
vmov.32 d0[1]
vmov.32 d0[0]
</pre></div>
</div>
<p>While this other code, will not:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]
; CHECK-DAG: vmov.32 [[REG2]][1]
vmov.32 d1[1]
vmov.32 d0[0]
</pre></div>
</div>
<p>While this can be very useful, it’s also dangerous, because in the case of
register sequence, you must have a strong order (read before write, copy before
use, etc). If the definition your test is looking for doesn’t match (because
of a bug in the compiler), it may match further away from the use, and mask
real bugs away.</p>
<p>In those cases, to enforce the order, use a non-DAG directive between DAG-blocks.</p>
<p>A <code class="docutils literal notranslate"><span class="pre">CHECK-DAG:</span></code> directive skips matches that overlap the matches of any
preceding <code class="docutils literal notranslate"><span class="pre">CHECK-DAG:</span></code> directives in the same <code class="docutils literal notranslate"><span class="pre">CHECK-DAG:</span></code> block. Not only
is this non-overlapping behavior consistent with other directives, but it’s
also necessary to handle sets of non-unique strings or patterns. For example,
the following directives look for unordered log entries for two tasks in a
parallel program, such as the OpenMP runtime:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>// CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin
// CHECK-DAG: [[THREAD_ID]]: task_end
//
// CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin
// CHECK-DAG: [[THREAD_ID]]: task_end
</pre></div>
</div>
<p>The second pair of directives is guaranteed not to match the same log entries
as the first pair even though the patterns are identical and even if the text
of the log entries is identical because the thread ID manages to be reused.</p>
</div>
<div class="section" id="the-check-label-directive">
<h3>The “CHECK-LABEL:” directive<a class="headerlink" href="#the-check-label-directive" title="Permalink to this headline">¶</a></h3>
<p>Sometimes in a file containing multiple tests divided into logical blocks, one
or more <code class="docutils literal notranslate"><span class="pre">CHECK:</span></code> directives may inadvertently succeed by matching lines in a
later block. While an error will usually eventually be generated, the check
flagged as causing the error may not actually bear any relationship to the
actual source of the problem.</p>
<p>In order to produce better error messages in these cases, the “<code class="docutils literal notranslate"><span class="pre">CHECK-LABEL:</span></code>”
directive can be used. It is treated identically to a normal <code class="docutils literal notranslate"><span class="pre">CHECK</span></code>
directive except that FileCheck makes an additional assumption that a line
matched by the directive cannot also be matched by any other check present in
<code class="docutils literal notranslate"><span class="pre">match-filename</span></code>; this is intended to be used for lines containing labels or
other unique identifiers. Conceptually, the presence of <code class="docutils literal notranslate"><span class="pre">CHECK-LABEL</span></code> divides
the input stream into separate blocks, each of which is processed independently,
preventing a <code class="docutils literal notranslate"><span class="pre">CHECK:</span></code> directive in one block matching a line in another block.
If <code class="docutils literal notranslate"><span class="pre">--enable-var-scope</span></code> is in effect, all local variables are cleared at the
beginning of the block.</p>
<p>For example,</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="nv">%struct.C</span><span class="p">*</span> <span class="vg">@C_ctor_base</span><span class="p">(</span><span class="nv">%struct.C</span><span class="p">*</span> <span class="nv">%this</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%x</span><span class="p">)</span> <span class="p">{</span>
<span class="nl">entry:</span>
<span class="c">; CHECK-LABEL: C_ctor_base:</span>
<span class="c">; CHECK: mov [[SAVETHIS:r[0-9]+]], r0</span>
<span class="c">; CHECK: bl A_ctor_base</span>
<span class="c">; CHECK: mov r0, [[SAVETHIS]]</span>
<span class="nv nv-Anonymous">%0</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="nv">%struct.C</span><span class="p">*</span> <span class="nv">%this</span> <span class="k">to</span> <span class="nv">%struct.A</span><span class="p">*</span>
<span class="nv">%call</span> <span class="p">=</span> <span class="k">tail</span> <span class="k">call</span> <span class="nv">%struct.A</span><span class="p">*</span> <span class="vg">@A_ctor_base</span><span class="p">(</span><span class="nv">%struct.A</span><span class="p">*</span> <span class="nv nv-Anonymous">%0</span><span class="p">)</span>
<span class="nv nv-Anonymous">%1</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="nv">%struct.C</span><span class="p">*</span> <span class="nv">%this</span> <span class="k">to</span> <span class="nv">%struct.B</span><span class="p">*</span>
<span class="nv">%call2</span> <span class="p">=</span> <span class="k">tail</span> <span class="k">call</span> <span class="nv">%struct.B</span><span class="p">*</span> <span class="vg">@B_ctor_base</span><span class="p">(</span><span class="nv">%struct.B</span><span class="p">*</span> <span class="nv nv-Anonymous">%1</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%x</span><span class="p">)</span>
<span class="k">ret</span> <span class="nv">%struct.C</span><span class="p">*</span> <span class="nv">%this</span>
<span class="p">}</span>
<span class="k">define</span> <span class="nv">%struct.D</span><span class="p">*</span> <span class="vg">@D_ctor_base</span><span class="p">(</span><span class="nv">%struct.D</span><span class="p">*</span> <span class="nv">%this</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%x</span><span class="p">)</span> <span class="p">{</span>
<span class="nl">entry:</span>
<span class="c">; CHECK-LABEL: D_ctor_base:</span>
</pre></div>
</div>
<p>The use of <code class="docutils literal notranslate"><span class="pre">CHECK-LABEL:</span></code> directives in this case ensures that the three
<code class="docutils literal notranslate"><span class="pre">CHECK:</span></code> directives only accept lines corresponding to the body of the
<code class="docutils literal notranslate"><span class="pre">@C_ctor_base</span></code> function, even if the patterns match lines found later in
the file. Furthermore, if one of these three <code class="docutils literal notranslate"><span class="pre">CHECK:</span></code> directives fail,
FileCheck will recover by continuing to the next block, allowing multiple test
failures to be detected in a single invocation.</p>
<p>There is no requirement that <code class="docutils literal notranslate"><span class="pre">CHECK-LABEL:</span></code> directives contain strings that
correspond to actual syntactic labels in a source or output language: they must
simply uniquely match a single line in the file being verified.</p>
<p><code class="docutils literal notranslate"><span class="pre">CHECK-LABEL:</span></code> directives cannot contain variable definitions or uses.</p>
</div>
<div class="section" id="directive-modifiers">
<h3>Directive modifiers<a class="headerlink" href="#directive-modifiers" title="Permalink to this headline">¶</a></h3>
<p>A directive modifier can be append to a directive by following the directive
with <code class="docutils literal notranslate"><span class="pre">{<modifier>}</span></code> where the only supported value for <code class="docutils literal notranslate"><span class="pre"><modifier></span></code> is
<code class="docutils literal notranslate"><span class="pre">LITERAL</span></code>.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">LITERAL</span></code> directive modifier can be used to perform a literal match. The
modifier results in the directive not recognizing any syntax to perform regex
matching, variable capture or any substitutions. This is useful when the text
to match would require excessive escaping otherwise. For example, the
following will perform literal matches rather than considering these as
regular expressions:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Input: [[[10, 20]], [[30, 40]]]
Output %r10: [[10, 20]]
Output %r10: [[30, 40]]
; CHECK{LITERAL}: [[[10, 20]], [[30, 40]]]
; CHECK-DAG{LITERAL}: [[30, 40]]
; CHECK-DAG{LITERAL}: [[10, 20]]
</pre></div>
</div>
</div>
<div class="section" id="filecheck-regex-matching-syntax">
<h3>FileCheck Regex Matching Syntax<a class="headerlink" href="#filecheck-regex-matching-syntax" title="Permalink to this headline">¶</a></h3>
<p>All FileCheck directives take a pattern to match.
For most uses of FileCheck, fixed string matching is perfectly sufficient. For
some things, a more flexible form of matching is desired. To support this,
FileCheck allows you to specify regular expressions in matching strings,
surrounded by double braces: <code class="docutils literal notranslate"><span class="pre">{{yourregex}}</span></code>. FileCheck implements a POSIX
regular expression matcher; it supports Extended POSIX regular expressions
(ERE). Because we want to use fixed string matching for a majority of what we
do, FileCheck has been designed to support mixing and matching fixed string
matching with regular expressions. This allows you to write things like this:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="c">; CHECK: movhpd {{[0-9]+}}(%esp), {{%xmm[0-7]}}</span>
</pre></div>
</div>
<p>In this case, any offset from the ESP register will be allowed, and any xmm
register will be allowed.</p>
<p>Because regular expressions are enclosed with double braces, they are
visually distinct, and you don’t need to use escape characters within the double
braces like you would in C. In the rare case that you want to match double
braces explicitly from the input, you can use something ugly like
<code class="docutils literal notranslate"><span class="pre">{{[}][}]}}</span></code> as your pattern. Or if you are using the repetition count
syntax, for example <code class="docutils literal notranslate"><span class="pre">[[:xdigit:]]{8}</span></code> to match exactly 8 hex digits, you
would need to add parentheses like this <code class="docutils literal notranslate"><span class="pre">{{([[:xdigit:]]{8})}}</span></code> to avoid
confusion with FileCheck’s closing double-brace.</p>
</div>
<div class="section" id="filecheck-string-substitution-blocks">
<h3>FileCheck String Substitution Blocks<a class="headerlink" href="#filecheck-string-substitution-blocks" title="Permalink to this headline">¶</a></h3>
<p>It is often useful to match a pattern and then verify that it occurs again
later in the file. For codegen tests, this can be useful to allow any
register, but verify that that register is used consistently later. To do
this, <strong class="program">FileCheck</strong> supports string substitution blocks that allow
string variables to be defined and substituted into patterns. Here is a simple
example:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="c">; CHECK: test5:</span>
<span class="c">; CHECK: notw [[REGISTER:%[a-z]+]]</span>
<span class="c">; CHECK: andw {{.*}}[[REGISTER]]</span>
</pre></div>
</div>
<p>The first check line matches a regex <code class="docutils literal notranslate"><span class="pre">%[a-z]+</span></code> and captures it into the
string variable <code class="docutils literal notranslate"><span class="pre">REGISTER</span></code>. The second line verifies that whatever is in
<code class="docutils literal notranslate"><span class="pre">REGISTER</span></code> occurs later in the file after an “<code class="docutils literal notranslate"><span class="pre">andw</span></code>”. <strong class="program">FileCheck</strong>
string substitution blocks are always contained in <code class="docutils literal notranslate"><span class="pre">[[</span> <span class="pre">]]</span></code> pairs, and string
variable names can be formed with the regex <code class="docutils literal notranslate"><span class="pre">[a-zA-Z_][a-zA-Z0-9_]*</span></code>. If a
colon follows the name, then it is a definition of the variable; otherwise, it
is a substitution.</p>
<p><strong class="program">FileCheck</strong> variables can be defined multiple times, and substitutions
always get the latest value. Variables can also be substituted later on the
same line they were defined on. For example:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="c">; CHECK: op [[REG:r[0-9]+]], [[REG]]</span>
</pre></div>
</div>
<p>Can be useful if you want the operands of <code class="docutils literal notranslate"><span class="pre">op</span></code> to be the same register,
and don’t care exactly which register it is.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">--enable-var-scope</span></code> is in effect, variables with names that
start with <code class="docutils literal notranslate"><span class="pre">$</span></code> are considered to be global. All others variables are
local. All local variables get undefined at the beginning of each
CHECK-LABEL block. Global variables are not affected by CHECK-LABEL.
This makes it easier to ensure that individual tests are not affected
by variables set in preceding tests.</p>
</div>
<div class="section" id="filecheck-numeric-substitution-blocks">
<h3>FileCheck Numeric Substitution Blocks<a class="headerlink" href="#filecheck-numeric-substitution-blocks" title="Permalink to this headline">¶</a></h3>
<p><strong class="program">FileCheck</strong> also supports numeric substitution blocks that allow
defining numeric variables and checking for numeric values that satisfy a
numeric expression constraint based on those variables via a numeric
substitution. This allows <code class="docutils literal notranslate"><span class="pre">CHECK:</span></code> directives to verify a numeric relation
between two numbers, such as the need for consecutive registers to be used.</p>
<p>The syntax to capture a numeric value is
<code class="docutils literal notranslate"><span class="pre">[[#%<fmtspec>,<NUMVAR>:]]</span></code> where:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">%<fmtspec>,</span></code> is an optional format specifier to indicate what number
format to match and the minimum number of digits to expect.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre"><NUMVAR>:</span></code> is an optional definition of variable <code class="docutils literal notranslate"><span class="pre"><NUMVAR></span></code> from the
captured value.</p></li>
</ul>
<p>The syntax of <code class="docutils literal notranslate"><span class="pre"><fmtspec></span></code> is: <code class="docutils literal notranslate"><span class="pre">#.<precision><conversion</span> <span class="pre">specifier></span></code> where:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">#</span></code> is an optional flag available for hex values (see
<code class="docutils literal notranslate"><span class="pre"><conversion</span> <span class="pre">specifier></span></code> below) which requires the value matched to be
prefixed by <code class="docutils literal notranslate"><span class="pre">0x</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">.<precision></span></code> is an optional printf-style precision specifier in which
<code class="docutils literal notranslate"><span class="pre"><precision></span></code> indicates the minimum number of digits that the value matched
must have, expecting leading zeros if needed.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre"><conversion</span> <span class="pre">specifier></span></code> is an optional scanf-style conversion specifier
to indicate what number format to match (e.g. hex number). Currently
accepted format specifiers are <code class="docutils literal notranslate"><span class="pre">%u</span></code>, <code class="docutils literal notranslate"><span class="pre">%d</span></code>, <code class="docutils literal notranslate"><span class="pre">%x</span></code> and <code class="docutils literal notranslate"><span class="pre">%X</span></code>. If absent,
the format specifier defaults to <code class="docutils literal notranslate"><span class="pre">%u</span></code>.</p></li>
</ul>
<p>For example:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="c">; CHECK: mov r[[#REG:]], 0x[[#%.8X,ADDR:]]</span>
</pre></div>
</div>
<p>would match <code class="docutils literal notranslate"><span class="pre">mov</span> <span class="pre">r5,</span> <span class="pre">0x0000FEFE</span></code> and set <code class="docutils literal notranslate"><span class="pre">REG</span></code> to the value <code class="docutils literal notranslate"><span class="pre">5</span></code> and
<code class="docutils literal notranslate"><span class="pre">ADDR</span></code> to the value <code class="docutils literal notranslate"><span class="pre">0xFEFE</span></code>. Note that due to the precision it would fail
to match <code class="docutils literal notranslate"><span class="pre">mov</span> <span class="pre">r5,</span> <span class="pre">0xFEFE</span></code>.</p>
<p>As a result of the numeric variable definition being optional, it is possible
to only check that a numeric value is present in a given format. This can be
useful when the value itself is not useful, for instance:</p>
<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="c1">; CHECK-NOT: mov r0, r[[#]]</span>
</pre></div>
</div>
<p>to check that a value is synthesized rather than moved around.</p>
<p>The syntax of a numeric substitution is
<code class="docutils literal notranslate"><span class="pre">[[#%<fmtspec>,</span> <span class="pre"><constraint></span> <span class="pre"><expr>]]</span></code> where:</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre"><fmtspec></span></code> is the same format specifier as for defining a variable but
in this context indicating how a numeric expression value should be matched
against. If absent, both components of the format specifier are inferred from
the matching format of the numeric variable(s) used by the expression
constraint if any, and defaults to <code class="docutils literal notranslate"><span class="pre">%u</span></code> if no numeric variable is used,
denoting that the value should be unsigned with no leading zeros. In case of
conflict between format specifiers of several numeric variables, the
conversion specifier becomes mandatory but the precision specifier remains
optional.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre"><constraint></span></code> is the constraint describing how the value to match must
relate to the value of the numeric expression. The only currently accepted
constraint is <code class="docutils literal notranslate"><span class="pre">==</span></code> for an exact match and is the default if
<code class="docutils literal notranslate"><span class="pre"><constraint></span></code> is not provided. No matching constraint must be specified
when the <code class="docutils literal notranslate"><span class="pre"><expr></span></code> is empty.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre"><expr></span></code> is an expression. An expression is in turn recursively defined
as:</p>
<ul class="simple">
<li><p>a numeric operand, or</p></li>
<li><p>an expression followed by an operator and a numeric operand.</p></li>
</ul>
<p>A numeric operand is a previously defined numeric variable, an integer
literal, or a function. Spaces are accepted before, after and between any of
these elements. Numeric operands have 64-bit precision. Overflow and underflow
are rejected. There is no support for operator precedence, but parentheses
can be used to change the evaluation order.</p>
</li>
</ul>
<p>The supported operators are:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">+</span></code> - Returns the sum of its two operands.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-</span></code> - Returns the difference of its two operands.</p></li>
</ul>
</div></blockquote>
<p>The syntax of a function call is <code class="docutils literal notranslate"><span class="pre"><name>(<arguments>)</span></code> where:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">name</span></code> is a predefined string literal. Accepted values are:</p>
<ul>
<li><p>add - Returns the sum of its two operands.</p></li>
<li><p>div - Returns the quotient of its two operands.</p></li>
<li><p>max - Returns the largest of its two operands.</p></li>
<li><p>min - Returns the smallest of its two operands.</p></li>
<li><p>mul - Returns the product of its two operands.</p></li>
<li><p>sub - Returns the difference of its two operands.</p></li>
</ul>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre"><arguments></span></code> is a comma separated list of expressions.</p></li>
</ul>
<p>For example:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="c">; CHECK: load r[[#REG:]], [r0]</span>
<span class="c">; CHECK: load r[[#REG+1]], [r1]</span>
<span class="c">; CHECK: Loading from 0x[[#%x,ADDR:]]</span>
<span class="c">; CHECK-SAME: to 0x[[#ADDR + 7]]</span>
</pre></div>
</div>
<p>The above example would match the text:</p>
<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="nf">load</span> <span class="no">r5</span><span class="p">,</span> <span class="p">[</span><span class="no">r0</span><span class="p">]</span>
<span class="nf">load</span> <span class="no">r6</span><span class="p">,</span> <span class="p">[</span><span class="no">r1</span><span class="p">]</span>
<span class="nf">Loading</span> <span class="no">from</span> <span class="mi">0xa0463440</span> <span class="no">to</span> <span class="mi">0xa0463447</span>
</pre></div>
</div>
<p>but would not match the text:</p>
<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="nf">load</span> <span class="no">r5</span><span class="p">,</span> <span class="p">[</span><span class="no">r0</span><span class="p">]</span>
<span class="nf">load</span> <span class="no">r7</span><span class="p">,</span> <span class="p">[</span><span class="no">r1</span><span class="p">]</span>
<span class="nf">Loading</span> <span class="no">from</span> <span class="mi">0xa0463440</span> <span class="no">to</span> <span class="mi">0xa0463443</span>
</pre></div>
</div>
<p>Due to <code class="docutils literal notranslate"><span class="pre">7</span></code> being unequal to <code class="docutils literal notranslate"><span class="pre">5</span> <span class="pre">+</span> <span class="pre">1</span></code> and <code class="docutils literal notranslate"><span class="pre">a0463443</span></code> being unequal to
<code class="docutils literal notranslate"><span class="pre">a0463440</span> <span class="pre">+</span> <span class="pre">7</span></code>.</p>
<p>A numeric variable can also be defined to the result of a numeric expression,
in which case the numeric expression constraint is checked and if verified the
variable is assigned to the value. The unified syntax for both checking a
numeric expression and capturing its value into a numeric variable is thus
<code class="docutils literal notranslate"><span class="pre">[[#%<fmtspec>,<NUMVAR>:</span> <span class="pre"><constraint></span> <span class="pre"><expr>]]</span></code> with each element as
described previously. One can use this syntax to make a testcase more
self-describing by using variables instead of values:</p>
<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="c1">; CHECK: mov r[[#REG_OFFSET:]], 0x[[#%X,FIELD_OFFSET:12]]</span>
<span class="c1">; CHECK-NEXT: load r[[#]], [r[[#REG_BASE:]], r[[#REG_OFFSET]]]</span>
</pre></div>
</div>
<p>which would match:</p>
<div class="highlight-gas notranslate"><div class="highlight"><pre><span></span><span class="nf">mov</span> <span class="no">r4</span><span class="p">,</span> <span class="mi">0xC</span>
<span class="nf">load</span> <span class="no">r6</span><span class="p">,</span> <span class="p">[</span><span class="no">r5</span><span class="p">,</span> <span class="no">r4</span><span class="p">]</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">--enable-var-scope</span></code> option has the same effect on numeric variables as
on string variables.</p>
<p>Important note: In its current implementation, an expression cannot use a
numeric variable defined earlier in the same CHECK directive.</p>
</div>
<div class="section" id="filecheck-pseudo-numeric-variables">
<h3>FileCheck Pseudo Numeric Variables<a class="headerlink" href="#filecheck-pseudo-numeric-variables" title="Permalink to this headline">¶</a></h3>
<p>Sometimes there’s a need to verify output that contains line numbers of the
match file, e.g. when testing compiler diagnostics. This introduces a certain
fragility of the match file structure, as “<code class="docutils literal notranslate"><span class="pre">CHECK:</span></code>” lines contain absolute
line numbers in the same file, which have to be updated whenever line numbers
change due to text addition or deletion.</p>
<p>To support this case, FileCheck expressions understand the <code class="docutils literal notranslate"><span class="pre">@LINE</span></code> pseudo
numeric variable which evaluates to the line number of the CHECK pattern where
it is found.</p>
<p>This way match patterns can be put near the relevant test lines and include
relative line number references, for example:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// CHECK: test.cpp:[[# @LINE + 4]]:6: error: expected ';' after top level declarator</span>
<span class="c1">// CHECK-NEXT: {{^int a}}</span>
<span class="c1">// CHECK-NEXT: {{^ \^}}</span>
<span class="c1">// CHECK-NEXT: {{^ ;}}</span>
<span class="kt">int</span> <span class="n">a</span>
</pre></div>
</div>
<p>To support legacy uses of <code class="docutils literal notranslate"><span class="pre">@LINE</span></code> as a special string variable,
<strong class="program">FileCheck</strong> also accepts the following uses of <code class="docutils literal notranslate"><span class="pre">@LINE</span></code> with string
substitution block syntax: <code class="docutils literal notranslate"><span class="pre">[[@LINE]]</span></code>, <code class="docutils literal notranslate"><span class="pre">[[@LINE+<offset>]]</span></code> and
<code class="docutils literal notranslate"><span class="pre">[[@LINE-<offset>]]</span></code> without any spaces inside the brackets and where
<code class="docutils literal notranslate"><span class="pre">offset</span></code> is an integer.</p>
</div>
<div class="section" id="matching-newline-characters">
<h3>Matching Newline Characters<a class="headerlink" href="#matching-newline-characters" title="Permalink to this headline">¶</a></h3>
<p>To match newline characters in regular expressions the character class
<code class="docutils literal notranslate"><span class="pre">[[:space:]]</span></code> can be used. For example, the following pattern:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// CHECK: DW_AT_location [DW_FORM_sec_offset] ([[DLOC:0x[0-9a-f]+]]){{[[:space:]].*}}"intd"</span>
</pre></div>
</div>
<p>matches output of the form (from llvm-dwarfdump):</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>DW_AT_location [DW_FORM_sec_offset] (0x00000233)
DW_AT_name [DW_FORM_strp] ( .debug_str[0x000000c9] = "intd")
</pre></div>
</div>
<p>letting us set the <strong class="program">FileCheck</strong> variable <code class="docutils literal notranslate"><span class="pre">DLOC</span></code> to the desired value
<code class="docutils literal notranslate"><span class="pre">0x00000233</span></code>, extracted from the line immediately preceding “<code class="docutils literal notranslate"><span class="pre">intd</span></code>”.</p>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="tblgen.html" title="tblgen - Description to C++ Code"
>next</a> |</li>
<li class="right" >
<a href="llvm-bcanalyzer.html" title="llvm-bcanalyzer - LLVM bitcode analyzer"
>previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="../index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="../Reference.html" >Reference</a> »</li>
<li class="nav-item nav-item-2"><a href="index.html" >LLVM Command Guide</a> »</li>
<li class="nav-item nav-item-this"><a href="">FileCheck - Flexible pattern matching file verifier</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2003-2021, LLVM Project.
Last updated on 2021-09-18.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.5.4.
</div>
</body>
</html>
|
