Clang] Fix expansion of response files in -Wp after integrated-cc1 change
[llvm-project.git] / llvm / docs / CommandGuide / FileCheck.rst
blob0072c9c0347217e6820790a54552c6083b873ff7
1 FileCheck - Flexible pattern matching file verifier
2 ===================================================
4 .. program:: FileCheck
6 SYNOPSIS
7 --------
9 :program:`FileCheck` *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*]
11 DESCRIPTION
12 -----------
14 :program:`FileCheck` reads two files (one from standard input, and one
15 specified on the command line) and uses one to verify the other.  This
16 behavior is particularly useful for the testsuite, which wants to verify that
17 the output of some tool (e.g. :program:`llc`) contains the expected information
18 (for example, a movsd from esp or whatever is interesting).  This is similar to
19 using :program:`grep`, but it is optimized for matching multiple different
20 inputs in one file in a specific order.
22 The ``match-filename`` file specifies the file that contains the patterns to
23 match.  The file to verify is read from standard input unless the
24 :option:`--input-file` option is used.
26 OPTIONS
27 -------
29 Options are parsed from the environment variable ``FILECHECK_OPTS``
30 and from the command line.
32 .. option:: -help
34  Print a summary of command line options.
36 .. option:: --check-prefix prefix
38  FileCheck searches the contents of ``match-filename`` for patterns to
39  match.  By default, these patterns are prefixed with "``CHECK:``".
40  If you'd like to use a different prefix (e.g. because the same input
41  file is checking multiple different tool or options), the
42  :option:`--check-prefix` argument allows you to specify one or more
43  prefixes to match. Multiple prefixes are useful for tests which might
44  change for different run options, but most lines remain the same.
46 .. option:: --check-prefixes prefix1,prefix2,...
48  An alias of :option:`--check-prefix` that allows multiple prefixes to be
49  specified as a comma separated list.
51 .. option:: --input-file filename
53   File to check (defaults to stdin).
55 .. option:: --match-full-lines
57  By default, FileCheck allows matches of anywhere on a line. This
58  option will require all positive matches to cover an entire
59  line. Leading and trailing whitespace is ignored, unless
60  :option:`--strict-whitespace` is also specified. (Note: negative
61  matches from ``CHECK-NOT`` are not affected by this option!)
63  Passing this option is equivalent to inserting ``{{^ *}}`` or
64  ``{{^}}`` before, and ``{{ *$}}`` or ``{{$}}`` after every positive
65  check pattern.
67 .. option:: --strict-whitespace
69  By default, FileCheck canonicalizes input horizontal whitespace (spaces and
70  tabs) which causes it to ignore these differences (a space will match a tab).
71  The :option:`--strict-whitespace` argument disables this behavior. End-of-line
72  sequences are canonicalized to UNIX-style ``\n`` in all modes.
74 .. option:: --ignore-case
76   By default, FileCheck uses case-sensitive matching. This option causes
77   FileCheck to use case-insensitive matching.
79 .. option:: --implicit-check-not check-pattern
81   Adds implicit negative checks for the specified patterns between positive
82   checks. The option allows writing stricter tests without stuffing them with
83   ``CHECK-NOT``\ s.
85   For example, "``--implicit-check-not warning:``" can be useful when testing
86   diagnostic messages from tools that don't have an option similar to ``clang
87   -verify``. With this option FileCheck will verify that input does not contain
88   warnings not covered by any ``CHECK:`` patterns.
90 .. option:: --dump-input <mode>
92   Dump input to stderr, adding annotations representing currently enabled
93   diagnostics.  Do this either 'always', on 'fail', or 'never'.  Specify 'help'
94   to explain the dump format and quit.
96 .. option:: --dump-input-on-failure
98   When the check fails, dump all of the original input.  This option is
99   deprecated in favor of `--dump-input=fail`.
101 .. option:: --enable-var-scope
103   Enables scope for regex variables.
105   Variables with names that start with ``$`` are considered global and
106   remain set throughout the file.
108   All other variables get undefined after each encountered ``CHECK-LABEL``.
110 .. option:: -D<VAR=VALUE>
112   Sets a filecheck pattern variable ``VAR`` with value ``VALUE`` that can be
113   used in ``CHECK:`` lines.
115 .. option:: -D#<NUMVAR>=<NUMERIC EXPRESSION>
117   Sets a filecheck numeric variable ``NUMVAR`` to the result of evaluating
118   ``<NUMERIC EXPRESSION>`` that can be used in ``CHECK:`` lines. See section
119   ``FileCheck Numeric Variables and Expressions`` for details on supported
120   numeric expressions.
122 .. option:: -version
124  Show the version number of this program.
126 .. option:: -v
128   Print good directive pattern matches.  However, if ``-input-dump=fail`` or
129   ``-input-dump=always``, add those matches as input annotations instead.
131 .. option:: -vv
133   Print information helpful in diagnosing internal FileCheck issues, such as
134   discarded overlapping ``CHECK-DAG:`` matches, implicit EOF pattern matches,
135   and ``CHECK-NOT:`` patterns that do not have matches.  Implies ``-v``.
136   However, if ``-input-dump=fail`` or ``-input-dump=always``, just add that
137   information as input annotations instead.
139 .. option:: --allow-deprecated-dag-overlap
141   Enable overlapping among matches in a group of consecutive ``CHECK-DAG:``
142   directives.  This option is deprecated and is only provided for convenience
143   as old tests are migrated to the new non-overlapping ``CHECK-DAG:``
144   implementation.
146 .. option:: --color
148   Use colors in output (autodetected by default).
150 EXIT STATUS
151 -----------
153 If :program:`FileCheck` verifies that the file matches the expected contents,
154 it exits with 0.  Otherwise, if not, or if an error occurs, it will exit with a
155 non-zero value.
157 TUTORIAL
158 --------
160 FileCheck is typically used from LLVM regression tests, being invoked on the RUN
161 line of the test.  A simple example of using FileCheck from a RUN line looks
162 like this:
164 .. code-block:: llvm
166    ; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s
168 This syntax says to pipe the current file ("``%s``") into ``llvm-as``, pipe
169 that into ``llc``, then pipe the output of ``llc`` into ``FileCheck``.  This
170 means that FileCheck will be verifying its standard input (the llc output)
171 against the filename argument specified (the original ``.ll`` file specified by
172 "``%s``").  To see how this works, let's look at the rest of the ``.ll`` file
173 (after the RUN line):
175 .. code-block:: llvm
177    define void @sub1(i32* %p, i32 %v) {
178    entry:
179    ; CHECK: sub1:
180    ; CHECK: subl
181            %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v)
182            ret void
183    }
185    define void @inc4(i64* %p) {
186    entry:
187    ; CHECK: inc4:
188    ; CHECK: incq
189            %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1)
190            ret void
191    }
193 Here you can see some "``CHECK:``" lines specified in comments.  Now you can
194 see how the file is piped into ``llvm-as``, then ``llc``, and the machine code
195 output is what we are verifying.  FileCheck checks the machine code output to
196 verify that it matches what the "``CHECK:``" lines specify.
198 The syntax of the "``CHECK:``" lines is very simple: they are fixed strings that
199 must occur in order.  FileCheck defaults to ignoring horizontal whitespace
200 differences (e.g. a space is allowed to match a tab) but otherwise, the contents
201 of the "``CHECK:``" line is required to match some thing in the test file exactly.
203 One nice thing about FileCheck (compared to grep) is that it allows merging
204 test cases together into logical groups.  For example, because the test above
205 is checking for the "``sub1:``" and "``inc4:``" labels, it will not match
206 unless there is a "``subl``" in between those labels.  If it existed somewhere
207 else in the file, that would not count: "``grep subl``" matches if "``subl``"
208 exists anywhere in the file.
210 The FileCheck -check-prefix option
211 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
213 The FileCheck `-check-prefix` option allows multiple test
214 configurations to be driven from one `.ll` file.  This is useful in many
215 circumstances, for example, testing different architectural variants with
216 :program:`llc`.  Here's a simple example:
218 .. code-block:: llvm
220    ; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \
221    ; RUN:              | FileCheck %s -check-prefix=X32
222    ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \
223    ; RUN:              | FileCheck %s -check-prefix=X64
225    define <4 x i32> @pinsrd_1(i32 %s, <4 x i32> %tmp) nounwind {
226            %tmp1 = insertelement <4 x i32>; %tmp, i32 %s, i32 1
227            ret <4 x i32> %tmp1
228    ; X32: pinsrd_1:
229    ; X32:    pinsrd $1, 4(%esp), %xmm0
231    ; X64: pinsrd_1:
232    ; X64:    pinsrd $1, %edi, %xmm0
233    }
235 In this case, we're testing that we get the expected code generation with
236 both 32-bit and 64-bit code generation.
238 The "CHECK-NEXT:" directive
239 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
241 Sometimes you want to match lines and would like to verify that matches
242 happen on exactly consecutive lines with no other lines in between them.  In
243 this case, you can use "``CHECK:``" and "``CHECK-NEXT:``" directives to specify
244 this.  If you specified a custom check prefix, just use "``<PREFIX>-NEXT:``".
245 For example, something like this works as you'd expect:
247 .. code-block:: llvm
249    define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) {
250         %tmp3 = load <2 x double>* %A, align 16
251         %tmp7 = insertelement <2 x double> undef, double %B, i32 0
252         %tmp9 = shufflevector <2 x double> %tmp3,
253                                <2 x double> %tmp7,
254                                <2 x i32> < i32 0, i32 2 >
255         store <2 x double> %tmp9, <2 x double>* %r, align 16
256         ret void
258    ; CHECK:          t2:
259    ; CHECK:             movl    8(%esp), %eax
260    ; CHECK-NEXT:        movapd  (%eax), %xmm0
261    ; CHECK-NEXT:        movhpd  12(%esp), %xmm0
262    ; CHECK-NEXT:        movl    4(%esp), %eax
263    ; CHECK-NEXT:        movapd  %xmm0, (%eax)
264    ; CHECK-NEXT:        ret
265    }
267 "``CHECK-NEXT:``" directives reject the input unless there is exactly one
268 newline between it and the previous directive.  A "``CHECK-NEXT:``" cannot be
269 the first directive in a file.
271 The "CHECK-SAME:" directive
272 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
274 Sometimes you want to match lines and would like to verify that matches happen
275 on the same line as the previous match.  In this case, you can use "``CHECK:``"
276 and "``CHECK-SAME:``" directives to specify this.  If you specified a custom
277 check prefix, just use "``<PREFIX>-SAME:``".
279 "``CHECK-SAME:``" is particularly powerful in conjunction with "``CHECK-NOT:``"
280 (described below).
282 For example, the following works like you'd expect:
284 .. code-block:: llvm
286    !0 = !DILocation(line: 5, scope: !1, inlinedAt: !2)
288    ; CHECK:       !DILocation(line: 5,
289    ; CHECK-NOT:               column:
290    ; CHECK-SAME:              scope: ![[SCOPE:[0-9]+]]
292 "``CHECK-SAME:``" directives reject the input if there are any newlines between
293 it and the previous directive.  A "``CHECK-SAME:``" cannot be the first
294 directive in a file.
296 The "CHECK-EMPTY:" directive
297 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
299 If you need to check that the next line has nothing on it, not even whitespace,
300 you can use the "``CHECK-EMPTY:``" directive.
302 .. code-block:: llvm
304    declare void @foo()
306    declare void @bar()
307    ; CHECK: foo
308    ; CHECK-EMPTY:
309    ; CHECK-NEXT: bar
311 Just like "``CHECK-NEXT:``" the directive will fail if there is more than one
312 newline before it finds the next blank line, and it cannot be the first
313 directive in a file.
315 The "CHECK-NOT:" directive
316 ~~~~~~~~~~~~~~~~~~~~~~~~~~
318 The "``CHECK-NOT:``" directive is used to verify that a string doesn't occur
319 between two matches (or before the first match, or after the last match).  For
320 example, to verify that a load is removed by a transformation, a test like this
321 can be used:
323 .. code-block:: llvm
325    define i8 @coerce_offset0(i32 %V, i32* %P) {
326      store i32 %V, i32* %P
328      %P2 = bitcast i32* %P to i8*
329      %P3 = getelementptr i8* %P2, i32 2
331      %A = load i8* %P3
332      ret i8 %A
333    ; CHECK: @coerce_offset0
334    ; CHECK-NOT: load
335    ; CHECK: ret i8
336    }
338 The "CHECK-COUNT:" directive
339 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
341 If you need to match multiple lines with the same pattern over and over again
342 you can repeat a plain ``CHECK:`` as many times as needed. If that looks too
343 boring you can instead use a counted check "``CHECK-COUNT-<num>:``", where
344 ``<num>`` is a positive decimal number. It will match the pattern exactly
345 ``<num>`` times, no more and no less. If you specified a custom check prefix,
346 just use "``<PREFIX>-COUNT-<num>:``" for the same effect.
347 Here is a simple example:
349 .. code-block:: text
351    Loop at depth 1
352    Loop at depth 1
353    Loop at depth 1
354    Loop at depth 1
355      Loop at depth 2
356        Loop at depth 3
358    ; CHECK-COUNT-6: Loop at depth {{[0-9]+}}
359    ; CHECK-NOT:     Loop at depth {{[0-9]+}}
361 The "CHECK-DAG:" directive
362 ~~~~~~~~~~~~~~~~~~~~~~~~~~
364 If it's necessary to match strings that don't occur in a strictly sequential
365 order, "``CHECK-DAG:``" could be used to verify them between two matches (or
366 before the first match, or after the last match). For example, clang emits
367 vtable globals in reverse order. Using ``CHECK-DAG:``, we can keep the checks
368 in the natural order:
370 .. code-block:: c++
372     // RUN: %clang_cc1 %s -emit-llvm -o - | FileCheck %s
374     struct Foo { virtual void method(); };
375     Foo f;  // emit vtable
376     // CHECK-DAG: @_ZTV3Foo =
378     struct Bar { virtual void method(); };
379     Bar b;
380     // CHECK-DAG: @_ZTV3Bar =
382 ``CHECK-NOT:`` directives could be mixed with ``CHECK-DAG:`` directives to
383 exclude strings between the surrounding ``CHECK-DAG:`` directives. As a result,
384 the surrounding ``CHECK-DAG:`` directives cannot be reordered, i.e. all
385 occurrences matching ``CHECK-DAG:`` before ``CHECK-NOT:`` must not fall behind
386 occurrences matching ``CHECK-DAG:`` after ``CHECK-NOT:``. For example,
388 .. code-block:: llvm
390    ; CHECK-DAG: BEFORE
391    ; CHECK-NOT: NOT
392    ; CHECK-DAG: AFTER
394 This case will reject input strings where ``BEFORE`` occurs after ``AFTER``.
396 With captured variables, ``CHECK-DAG:`` is able to match valid topological
397 orderings of a DAG with edges from the definition of a variable to its use.
398 It's useful, e.g., when your test cases need to match different output
399 sequences from the instruction scheduler. For example,
401 .. code-block:: llvm
403    ; CHECK-DAG: add [[REG1:r[0-9]+]], r1, r2
404    ; CHECK-DAG: add [[REG2:r[0-9]+]], r3, r4
405    ; CHECK:     mul r5, [[REG1]], [[REG2]]
407 In this case, any order of that two ``add`` instructions will be allowed.
409 If you are defining `and` using variables in the same ``CHECK-DAG:`` block,
410 be aware that the definition rule can match `after` its use.
412 So, for instance, the code below will pass:
414 .. code-block:: text
416   ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]
417   ; CHECK-DAG: vmov.32 [[REG2]][1]
418   vmov.32 d0[1]
419   vmov.32 d0[0]
421 While this other code, will not:
423 .. code-block:: text
425   ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]
426   ; CHECK-DAG: vmov.32 [[REG2]][1]
427   vmov.32 d1[1]
428   vmov.32 d0[0]
430 While this can be very useful, it's also dangerous, because in the case of
431 register sequence, you must have a strong order (read before write, copy before
432 use, etc). If the definition your test is looking for doesn't match (because
433 of a bug in the compiler), it may match further away from the use, and mask
434 real bugs away.
436 In those cases, to enforce the order, use a non-DAG directive between DAG-blocks.
438 A ``CHECK-DAG:`` directive skips matches that overlap the matches of any
439 preceding ``CHECK-DAG:`` directives in the same ``CHECK-DAG:`` block.  Not only
440 is this non-overlapping behavior consistent with other directives, but it's
441 also necessary to handle sets of non-unique strings or patterns.  For example,
442 the following directives look for unordered log entries for two tasks in a
443 parallel program, such as the OpenMP runtime:
445 .. code-block:: text
447     // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin
448     // CHECK-DAG: [[THREAD_ID]]: task_end
449     //
450     // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin
451     // CHECK-DAG: [[THREAD_ID]]: task_end
453 The second pair of directives is guaranteed not to match the same log entries
454 as the first pair even though the patterns are identical and even if the text
455 of the log entries is identical because the thread ID manages to be reused.
457 The "CHECK-LABEL:" directive
458 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
460 Sometimes in a file containing multiple tests divided into logical blocks, one
461 or more ``CHECK:`` directives may inadvertently succeed by matching lines in a
462 later block. While an error will usually eventually be generated, the check
463 flagged as causing the error may not actually bear any relationship to the
464 actual source of the problem.
466 In order to produce better error messages in these cases, the "``CHECK-LABEL:``"
467 directive can be used. It is treated identically to a normal ``CHECK``
468 directive except that FileCheck makes an additional assumption that a line
469 matched by the directive cannot also be matched by any other check present in
470 ``match-filename``; this is intended to be used for lines containing labels or
471 other unique identifiers. Conceptually, the presence of ``CHECK-LABEL`` divides
472 the input stream into separate blocks, each of which is processed independently,
473 preventing a ``CHECK:`` directive in one block matching a line in another block.
474 If ``--enable-var-scope`` is in effect, all local variables are cleared at the
475 beginning of the block.
477 For example,
479 .. code-block:: llvm
481   define %struct.C* @C_ctor_base(%struct.C* %this, i32 %x) {
482   entry:
483   ; CHECK-LABEL: C_ctor_base:
484   ; CHECK: mov [[SAVETHIS:r[0-9]+]], r0
485   ; CHECK: bl A_ctor_base
486   ; CHECK: mov r0, [[SAVETHIS]]
487     %0 = bitcast %struct.C* %this to %struct.A*
488     %call = tail call %struct.A* @A_ctor_base(%struct.A* %0)
489     %1 = bitcast %struct.C* %this to %struct.B*
490     %call2 = tail call %struct.B* @B_ctor_base(%struct.B* %1, i32 %x)
491     ret %struct.C* %this
492   }
494   define %struct.D* @D_ctor_base(%struct.D* %this, i32 %x) {
495   entry:
496   ; CHECK-LABEL: D_ctor_base:
498 The use of ``CHECK-LABEL:`` directives in this case ensures that the three
499 ``CHECK:`` directives only accept lines corresponding to the body of the
500 ``@C_ctor_base`` function, even if the patterns match lines found later in
501 the file. Furthermore, if one of these three ``CHECK:`` directives fail,
502 FileCheck will recover by continuing to the next block, allowing multiple test
503 failures to be detected in a single invocation.
505 There is no requirement that ``CHECK-LABEL:`` directives contain strings that
506 correspond to actual syntactic labels in a source or output language: they must
507 simply uniquely match a single line in the file being verified.
509 ``CHECK-LABEL:`` directives cannot contain variable definitions or uses.
511 FileCheck Regex Matching Syntax
512 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
514 All FileCheck directives take a pattern to match.
515 For most uses of FileCheck, fixed string matching is perfectly sufficient.  For
516 some things, a more flexible form of matching is desired.  To support this,
517 FileCheck allows you to specify regular expressions in matching strings,
518 surrounded by double braces: ``{{yourregex}}``. FileCheck implements a POSIX
519 regular expression matcher; it supports Extended POSIX regular expressions
520 (ERE). Because we want to use fixed string matching for a majority of what we
521 do, FileCheck has been designed to support mixing and matching fixed string
522 matching with regular expressions.  This allows you to write things like this:
524 .. code-block:: llvm
526    ; CHECK: movhpd      {{[0-9]+}}(%esp), {{%xmm[0-7]}}
528 In this case, any offset from the ESP register will be allowed, and any xmm
529 register will be allowed.
531 Because regular expressions are enclosed with double braces, they are
532 visually distinct, and you don't need to use escape characters within the double
533 braces like you would in C.  In the rare case that you want to match double
534 braces explicitly from the input, you can use something ugly like
535 ``{{[}][}]}}`` as your pattern.  Or if you are using the repetition count
536 syntax, for example ``[[:xdigit:]]{8}`` to match exactly 8 hex digits, you
537 would need to add parentheses like this ``{{([[:xdigit:]]{8})}}`` to avoid
538 confusion with FileCheck's closing double-brace.
540 FileCheck String Substitution Blocks
541 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
543 It is often useful to match a pattern and then verify that it occurs again
544 later in the file.  For codegen tests, this can be useful to allow any
545 register, but verify that that register is used consistently later.  To do
546 this, :program:`FileCheck` supports string substitution blocks that allow
547 string variables to be defined and substituted into patterns.  Here is a simple
548 example:
550 .. code-block:: llvm
552    ; CHECK: test5:
553    ; CHECK:    notw     [[REGISTER:%[a-z]+]]
554    ; CHECK:    andw     {{.*}}[[REGISTER]]
556 The first check line matches a regex ``%[a-z]+`` and captures it into the
557 string variable ``REGISTER``.  The second line verifies that whatever is in
558 ``REGISTER`` occurs later in the file after an "``andw``". :program:`FileCheck`
559 string substitution blocks are always contained in ``[[ ]]`` pairs, and string
560 variable names can be formed with the regex ``[a-zA-Z_][a-zA-Z0-9_]*``.  If a
561 colon follows the name, then it is a definition of the variable; otherwise, it
562 is a substitution.
564 :program:`FileCheck` variables can be defined multiple times, and substitutions
565 always get the latest value.  Variables can also be substituted later on the
566 same line they were defined on. For example:
568 .. code-block:: llvm
570     ; CHECK: op [[REG:r[0-9]+]], [[REG]]
572 Can be useful if you want the operands of ``op`` to be the same register,
573 and don't care exactly which register it is.
575 If ``--enable-var-scope`` is in effect, variables with names that
576 start with ``$`` are considered to be global. All others variables are
577 local.  All local variables get undefined at the beginning of each
578 CHECK-LABEL block. Global variables are not affected by CHECK-LABEL.
579 This makes it easier to ensure that individual tests are not affected
580 by variables set in preceding tests.
582 FileCheck Numeric Substitution Blocks
583 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
585 :program:`FileCheck` also supports numeric substitution blocks that allow
586 defining numeric variables and checking for numeric values that satisfy a
587 numeric expression constraint based on those variables via a numeric
588 substitution. This allows ``CHECK:`` directives to verify a numeric relation
589 between two numbers, such as the need for consecutive registers to be used.
591 The syntax to define a numeric variable is ``[[#<NUMVAR>:]]`` where
592 ``<NUMVAR>`` is the name of the numeric variable to define to the matching
593 value.
595 For example:
597 .. code-block:: llvm
599     ; CHECK: mov r[[#REG:]], 42
601 would match ``mov r5, 42`` and set ``REG`` to the value ``5``.
603 The syntax of a numeric substitution is ``[[#<expr>]]`` where ``<expr>`` is an
604 expression. An expression is recursively defined as:
606 * a numeric operand, or
607 * an expression followed by an operator and a numeric operand.
609 A numeric operand is a previously defined numeric variable, or an integer
610 literal. The supported operators are ``+`` and ``-``. Spaces are accepted
611 before, after and between any of these elements.
613 For example:
615 .. code-block:: llvm
617     ; CHECK: load r[[#REG:]], [r0]
618     ; CHECK: load r[[#REG+1]], [r1]
620 The above example would match the text:
622 .. code-block:: gas
624     load r5, [r0]
625     load r6, [r1]
627 but would not match the text:
629 .. code-block:: gas
631     load r5, [r0]
632     load r7, [r1]
634 due to ``7`` being unequal to ``5 + 1``.
636 The syntax also supports an empty expression, equivalent to writing {{[0-9]+}},
637 for cases where the input must contain a numeric value but the value itself
638 does not matter:
640 .. code-block:: gas
642     ; CHECK-NOT: mov r0, r[[#]]
644 to check that a value is synthesized rather than moved around.
646 A numeric variable can also be defined to the result of a numeric expression,
647 in which case the numeric expression is checked and if verified the variable is
648 assigned to the value. The unified syntax for both defining numeric variables
649 and checking a numeric expression is thus ``[[#<NUMVAR>: <expr>]]`` with each
650 element as described previously.
652 The ``--enable-var-scope`` option has the same effect on numeric variables as
653 on string variables.
655 Important note: In its current implementation, an expression cannot use a
656 numeric variable defined earlier in the same CHECK directive.
658 FileCheck Pseudo Numeric Variables
659 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
661 Sometimes there's a need to verify output that contains line numbers of the
662 match file, e.g. when testing compiler diagnostics.  This introduces a certain
663 fragility of the match file structure, as "``CHECK:``" lines contain absolute
664 line numbers in the same file, which have to be updated whenever line numbers
665 change due to text addition or deletion.
667 To support this case, FileCheck expressions understand the ``@LINE`` pseudo
668 numeric variable which evaluates to the line number of the CHECK pattern where
669 it is found.
671 This way match patterns can be put near the relevant test lines and include
672 relative line number references, for example:
674 .. code-block:: c++
676    // CHECK: test.cpp:[[# @LINE + 4]]:6: error: expected ';' after top level declarator
677    // CHECK-NEXT: {{^int a}}
678    // CHECK-NEXT: {{^     \^}}
679    // CHECK-NEXT: {{^     ;}}
680    int a
682 To support legacy uses of ``@LINE`` as a special string variable,
683 :program:`FileCheck` also accepts the following uses of ``@LINE`` with string
684 substitution block syntax: ``[[@LINE]]``, ``[[@LINE+<offset>]]`` and
685 ``[[@LINE-<offset>]]`` without any spaces inside the brackets and where
686 ``offset`` is an integer.
688 Matching Newline Characters
689 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
691 To match newline characters in regular expressions the character class
692 ``[[:space:]]`` can be used. For example, the following pattern:
694 .. code-block:: c++
696    // CHECK: DW_AT_location [DW_FORM_sec_offset] ([[DLOC:0x[0-9a-f]+]]){{[[:space:]].*}}"intd"
698 matches output of the form (from llvm-dwarfdump):
700 .. code-block:: text
702        DW_AT_location [DW_FORM_sec_offset]   (0x00000233)
703        DW_AT_name [DW_FORM_strp]  ( .debug_str[0x000000c9] = "intd")
705 letting us set the :program:`FileCheck` variable ``DLOC`` to the desired value 
706 ``0x00000233``, extracted from the line immediately preceding "``intd``".