6502/llvm-6502
1
0
Fork 0
mirror of https://github.com/c64scene-ar/llvm-6502.git synced 2025-05-01 13:37:55 +00:00
Code Issues Projects Releases Wiki Activity

Documentation for FileCheck: use 'option' and 'program' directives.

Browse Source 
This enables option cross-referencing and now '--' in option names are no more turned into en dashes.


git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@168926 91177308-0d34-0410-b5e6-96231b3b80d8
This commit is contained in:
Dmitri Gribenko 2012-11-29 19:21:02 +00:00
parent aa8cccf129
commit c8c3dbd911
1 changed files with 32 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
docs/CommandGuide/FileCheck.rst
View File

@ -4,57 +4,57 @@ FileCheck - Flexible pattern matching file verifier
SYNOPSIS SYNOPSIS
-------- --------
**FileCheck** *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*] :program:`FileCheck` *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*]
DESCRIPTION DESCRIPTION
----------- -----------
**FileCheck** reads two files (one from standard input, and one specified on the :program:`FileCheck` reads two files (one from standard input, and one
command line) and uses one to verify the other. This behavior is particularly specified on the command line) and uses one to verify the other. This
useful for the testsuite, which wants to verify that the output of some tool behavior is particularly useful for the testsuite, which wants to verify that
(e.g. llc) contains the expected information (for example, a movsd from esp or the output of some tool (e.g. :program:`llc`) contains the expected information
whatever is interesting). This is similar to using grep, but it is optimized (for example, a movsd from esp or whatever is interesting). This is similar to
for matching multiple different inputs in one file in a specific order. using :program:`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 The ``match-filename`` file specifies the file that contains the patterns to
match. The file to verify is always read from standard input. match. The file to verify is always read from standard input.
OPTIONS OPTIONS
------- -------
**-help** .. option:: -help
Print a summary of command line options. Print a summary of command line options.
**--check-prefix** *prefix* .. option:: --check-prefix prefix
FileCheck searches the contents of *match-filename* for patterns to match. By FileCheck searches the contents of ``match-filename`` for patterns to match.
default, these patterns are prefixed with "``CHECK:``". If you'd like to use a By default, these patterns are prefixed with "``CHECK:``". If you'd like to
different prefix (e.g. because the same input file is checking multiple use a different prefix (e.g. because the same input file is checking multiple
different tool or options), the **--check-prefix** argument allows you to specify different tool or options), the :option:`--check-prefix` argument allows you
a specific prefix to match. to specify a specific prefix to match.
**--input-file** *filename* .. option:: --input-file filename
File to check (defaults to stdin). File to check (defaults to stdin).
**--strict-whitespace** .. option:: --strict-whitespace
By default, FileCheck canonicalizes input horizontal whitespace (spaces and By default, FileCheck canonicalizes input horizontal whitespace (spaces and
tabs) which causes it to ignore these differences (a space will match a tab). tabs) which causes it to ignore these differences (a space will match a tab).
The **--strict-whitespace** argument disables this behavior. The :option:`--strict-whitespace` argument disables this behavior.
.. option:: -version
**-version**
Show the version number of this program. Show the version number of this program.
EXIT STATUS EXIT STATUS
----------- -----------
If **FileCheck** verifies that the file matches the expected contents, it exits If :program:`FileCheck` verifies that the file matches the expected contents,
with 0. Otherwise, if not, or if an error occurs, it will exit with a non-zero it exits with 0. Otherwise, if not, or if an error occurs, it will exit with a
value. non-zero value.
TUTORIAL TUTORIAL
-------- --------
@ -67,7 +67,6 @@ like this:
; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s ; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s
This syntax says to pipe the current file ("``%s``") into ``llvm-as``, pipe 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 that into ``llc``, then pipe the output of ``llc`` into ``FileCheck``. This
means that FileCheck will be verifying its standard input (the llc output) means that FileCheck will be verifying its standard input (the llc output)
@ -93,7 +92,6 @@ against the filename argument specified (the original ``.ll`` file specified by
ret void ret void
} }
Here you can see some "``CHECK:``" lines specified in comments. Now you can Here you can see some "``CHECK:``" lines specified in comments. Now you can
see how the file is piped into ``llvm-as``, then ``llc``, and the machine code see how the file is piped into ``llvm-as``, then ``llc``, and the machine code
output is what we are verifying. FileCheck checks the machine code output to output is what we are verifying. FileCheck checks the machine code output to
@ -114,9 +112,10 @@ exists anywhere in the file.
The FileCheck -check-prefix option The FileCheck -check-prefix option
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The FileCheck ``-check-prefix`` option allows multiple test configurations to be The FileCheck :option:`-check-prefix` option allows multiple test
driven from one .ll file. This is useful in many circumstances, for example, configurations to be driven from one `.ll` file. This is useful in many
testing different architectural variants with llc. Here's a simple example: circumstances, for example, testing different architectural variants with
:program:`llc`. Here's a simple example:
.. code-block:: llvm .. code-block:: llvm
@ -194,7 +193,6 @@ can be used:
; CHECK: ret i8 ; CHECK: ret i8
} }
FileCheck Pattern Matching Syntax FileCheck Pattern Matching Syntax
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -252,16 +250,14 @@ advantage of the fact that FileCheck is not actually line-oriented when it
matches, this allows you to define two separate "``CHECK``" lines that match on matches, this allows you to define two separate "``CHECK``" lines that match on
the same line. the same line.
FileCheck Expressions FileCheck Expressions
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
Sometimes there's a need to verify output which refers line numbers of the
Sometimes there's a need to verify output which refers line numbers of the match match file, e.g. when testing compiler diagnostics. This introduces a certain
file, e.g. when testing compiler diagnostics. This introduces a certain fragility of the match file structure, as "``CHECK:``" lines contain absolute
fragility of the match file structure, as CHECK: lines contain absolute line line numbers in the same file, which have to be updated whenever line numbers
numbers in the same file, which have to be updated whenever line numbers change change due to text addition or deletion.
due to text addition or deletion.
To support this case, FileCheck allows using ``[[@LINE]]``, To support this case, FileCheck allows using ``[[@LINE]]``,
``[[@LINE+<offset>]]``, ``[[@LINE-<offset>]]`` expressions in patterns. These ``[[@LINE+<offset>]]``, ``[[@LINE-<offset>]]`` expressions in patterns. These