FileCheck - Flexible pattern matching file verifier#

SYNOPSIS#

FileCheck match-filename [–check-prefixes=XXX] [–strict-whitespace]

DESCRIPTION#

FileCheck 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. llc) contains the expected information (for example, a movsd from esp or whatever is interesting). This is similar to using grep, but it is optimized for matching multiple different inputs in one file in a specific order.

The match-filename file specifies the file that contains the patterns to match. The file to verify is read from standard input unless the --input-file option is used.

OPTIONS#

Options are parsed from the environment variable FILECHECK_OPTS and from the command line.

-help#

Print a summary of command line options.

--check-prefixes prefix1,prefix2,...#

FileCheck searches the contents of match-filename for patterns to match. By default, these patterns are prefixed with “CHECK:”. If you’d like to use a different prefix (e.g. because the same input file is checking multiple different tool or options), the --check-prefixes argument allows you to specify (without the trailing “:”) 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.

FileCheck does not permit duplicate prefixes, even if one is a check prefix and one is a comment prefix (see --comment-prefixes below).

--check-prefix prefix1,prefix2,...#

An alias of --check-prefixes.

--comment-prefixes prefix1,prefix2,...#

By default, FileCheck ignores any occurrence in match-filename of any check prefix if it is preceded on the same line by “COM:” or “RUN:”. See the section [The “COM:” directive] for usage details.

These default comment prefixes can be overridden by --comment-prefixes 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.

--allow-unused-prefixes#

This option controls the behavior when using more than one prefix as specified by --check-prefixes, 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. The default value is false.

--input-file filename#

File to check (defaults to stdin).

--match-full-lines#

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 --strict-whitespace is also specified. (Note: negative matches from CHECK-NOT are not affected by this option!)

Passing this option is equivalent to inserting {{^ *}} or {{^}} before, and {{ *$}} or {{$}} after every positive check pattern.

--strict-whitespace#

By default, FileCheck canonicalizes input horizontal whitespace (spaces and tabs) which causes it to ignore these differences (a space will match a tab). The --strict-whitespace argument disables this behavior. End-of-line sequences are canonicalized to UNIX-style \n in all modes.

--ignore-case#

By default, FileCheck uses case-sensitive matching. This option causes FileCheck to use case-insensitive matching.

--implicit-check-not check-pattern#

Adds implicit negative checks for the specified patterns between positive checks. The option allows writing stricter tests without stuffing them with CHECK-NOTs.

For example, “--implicit-check-not warning:” can be useful when testing diagnostic messages from tools that don’t have an option similar to clang -verify. With this option FileCheck will verify that input does not contain warnings not covered by any CHECK: patterns.

--dump-input <value>#

Dump input to stderr, adding annotations representing currently enabled diagnostics. When there are multiple occurrences of this option, the <value> that appears earliest in the list below has precedence. The default is fail.

  • help - Explain input dump and quit

  • always - Always dump input

  • fail - Dump input on failure

  • never - Never dump input

--dump-input-context <N>#

In the dump requested by --dump-input, print <N> input lines before and <N> input lines after any lines specified by --dump-input-filter. When there are multiple occurrences of this option, the largest specified <N> has precedence. The default is 5.

--dump-input-filter <value>#

In the dump requested by --dump-input, print only input lines of kind <value> plus any context specified by --dump-input-context. When there are multiple occurrences of this option, the <value> that appears earliest in the list below has precedence. The default is error when --dump-input=fail, and it’s all when --dump-input=always.

  • all - All input lines

  • annotation-full - Input lines with annotations

  • annotation - Input lines with starting points of annotations

  • error - Input lines with starting points of error annotations

--enable-var-scope#

Enables scope for regex variables.

Variables with names that start with $ are considered global and remain set throughout the file.

All other variables get undefined after each encountered CHECK-LABEL.

-D<VAR=VALUE>#

Sets a filecheck pattern variable VAR with value VALUE that can be used in CHECK: lines.

-D#<FMT>,<NUMVAR>=<NUMERIC EXPRESSION>#

Sets a filecheck numeric variable NUMVAR of matching format FMT to the result of evaluating <NUMERIC EXPRESSION> that can be used in CHECK: lines. See section FileCheck Numeric Variables and Expressions for details on supported numeric expressions.

-version#

Show the version number of this program.

-v#

Print good directive pattern matches. However, if -dump-input=fail or -dump-input=always, add those matches as input annotations instead.

-vv#

Print information helpful in diagnosing internal FileCheck issues, such as discarded overlapping CHECK-DAG: matches, implicit EOF pattern matches, and CHECK-NOT: patterns that do not have matches. Implies -v. However, if -dump-input=fail or -dump-input=always, just add that information as input annotations instead.

--allow-deprecated-dag-overlap#

Enable overlapping among matches in a group of consecutive CHECK-DAG: directives. This option is deprecated and is only provided for convenience as old tests are migrated to the new non-overlapping CHECK-DAG: implementation.

--allow-empty#

Allow checking empty input. By default, empty input is rejected.

--color#

Use colors in output (autodetected by default).

EXIT STATUS#

If FileCheck 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.

TUTORIAL#

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:

; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s

This syntax says to pipe the current file (”%s”) into llvm-as, pipe that into llc, then pipe the output of llc into FileCheck. This means that FileCheck will be verifying its standard input (the llc output) against the filename argument specified (the original .ll file specified by “%s”). To see how this works, let’s look at the rest of the .ll file (after the RUN line):

define void @sub1(i32* %p, i32 %v) {
entry:
; CHECK: sub1:
; CHECK: subl
        %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v)
        ret void
}

define void @inc4(i64* %p) {
entry: