Tutorial: Hello World

This tutorial assumes that you have filecheck installed and have it available in your PATH:

$ filecheck
/usr/local/bin/filecheck
<check-file> not specified

FileCheck can be seen as an improved version of grep that makes automated testing of the command-line tools easier. FileCheck reads an input and scans it against a number of checks which can be substring or regex matches. If all check matches are found, FileCheck exits with an exit code 0. When a check without a match found, the FileCheck prints an error message and exits with an exit code 1.

The FileCheck program expects a path to a check file and a number of optional option arguments:

$ filecheck <check-file> [<options>]

Matching strings

Create new file hello-world.check with the following contents:

CHECK: Hello world

Now we can provide a valid input to filecheck which will match it against the check file:

$ echo "Hello world" | filecheck hello-world.check
/usr/local/bin/filecheck
$ echo $?
0

Note: By convention, original LLVM’s FileCheck always prints a full path to its executable and FileCheck.py follows this convention.

If we provide an invalid output we will see an error message:

$ echo "What is FileCheck" | filecheck hello-world.check
/usr/local/bin/filecheck
examples/hello-world.check:1:8: error: CHECK: expected string not found in input
CHECK: Hello world
       ^
<stdin>:1:1: note: scanning from here
What is FileCheck
^
$ echo $?
1

It is as easy as that!

Matching regular expressions

FileCheck also supports regex matching using special {{ }} syntax:

Create a new file hello-world-regex.check with the following contents:

CHECK: {{^Hello world$}}

Let’s run it with a valid input:

echo "Hello world" | filecheck examples/hello-world-regex.check
/usr/local/bin/filecheck
$ echo $?
0

With invalid input:

$ echo "Hello world Hello world" | filecheck examples/hello-world-regex.check
/usr/local/bin/filecheck
examples/hello-world-regex.check:1:8: error: CHECK: expected string not found in input
CHECK: {{^Hello world$}}
       ^
<stdin>:1:1: note: scanning from here
Hello world Hello world
^
$ echo $?
1

What’s next?

FileCheck is rarely used alone. The main use case for FileCheck is to serve as an string matching tool when it is used in a combination with LIT (LLVM Integrated Tester) and this is what our next tutorial is about. Don’t stop here and check it out right away: Tutorial: LIT and FileCheck.