Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Documentation: remove a copy of the FileCheck man page from TestingGuide

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@168288 91177308-0d34-0410-b5e6-96231b3b80d8
  • Loading branch information...
commit 0aea24d21e1781eae1cf5e35ae8950799d70f2f2 1 parent a0aa479
Dmitri Gribenko gribozavr authored

Showing 1 changed file with 4 additions and 194 deletions. Show diff stats Hide diff stats

  1. +4 194 docs/TestingGuide.rst
198 docs/TestingGuide.rst
Source Rendered
@@ -335,200 +335,10 @@ to verify that the output of a tools contains a series of different
335 335 output in a specific order. The FileCheck tool was designed to help with
336 336 these problems.
337 337
338   -FileCheck (whose basic command line arguments are described in `the
339   -FileCheck man page <http://llvm.org/cmds/FileCheck.html>`_ is designed
340   -to read a file to check from standard input, and the set of things to
341   -verify from a file specified as a command line argument. A simple
342   -example of using FileCheck from a RUN line looks like this:
343   -
344   -.. code-block:: llvm
345   -
346   - ; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s
347   -
348   -This syntax says to pipe the current file ("%s") into llvm-as, pipe that
349   -into llc, then pipe the output of llc into FileCheck. This means that
350   -FileCheck will be verifying its standard input (the llc output) against
351   -the filename argument specified (the original .ll file specified by
352   -"%s"). To see how this works, let's look at the rest of the .ll file
353   -(after the RUN line):
354   -
355   -.. code-block:: llvm
356   -
357   - define void @sub1(i32* %p, i32 %v) {
358   - entry:
359   - ; CHECK: sub1:
360   - ; CHECK: subl
361   - %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v)
362   - ret void
363   - }
364   -
365   - define void @inc4(i64* %p) {
366   - entry:
367   - ; CHECK: inc4:
368   - ; CHECK: incq
369   - %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1)
370   - ret void
371   - }
372   -
373   -Here you can see some "CHECK:" lines specified in comments. Now you can
374   -see how the file is piped into llvm-as, then llc, and the machine code
375   -output is what we are verifying. FileCheck checks the machine code
376   -output to verify that it matches what the "CHECK:" lines specify.
377   -
378   -The syntax of the CHECK: lines is very simple: they are fixed strings
379   -that must occur in order. FileCheck defaults to ignoring horizontal
380   -whitespace differences (e.g. a space is allowed to match a tab) but
381   -otherwise, the contents of the CHECK: line is required to match some
382   -thing in the test file exactly.
383   -
384   -One nice thing about FileCheck (compared to grep) is that it allows
385   -merging test cases together into logical groups. For example, because
386   -the test above is checking for the "sub1:" and "inc4:" labels, it will
387   -not match unless there is a "subl" in between those labels. If it
388   -existed somewhere else in the file, that would not count: "grep subl"
389   -matches if subl exists anywhere in the file.
390   -
391   -The FileCheck -check-prefix option
392   -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
393   -
394   -The FileCheck -check-prefix option allows multiple test configurations
395   -to be driven from one .ll file. This is useful in many circumstances,
396   -for example, testing different architectural variants with llc. Here's a
397   -simple example:
398   -
399   -.. code-block:: llvm
400   -
401   - ; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \
402   - ; RUN: | FileCheck %s -check-prefix=X32
403   - ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \
404   - ; RUN: | FileCheck %s -check-prefix=X64
405   -
406   - define <4 x i32> @pinsrd_1(i32 %s, <4 x i32> %tmp) nounwind {
407   - %tmp1 = insertelement <4 x i32> %tmp, i32 %s, i32 1
408   - ret <4 x i32> %tmp1
409   - ; X32: pinsrd_1:
410   - ; X32: pinsrd $1, 4(%esp), %xmm0
411   -
412   - ; X64: pinsrd_1:
413   - ; X64: pinsrd $1, %edi, %xmm0
414   - }
415   -
416   -In this case, we're testing that we get the expected code generation
417   -with both 32-bit and 64-bit code generation.
418   -
419   -The "CHECK-NEXT:" directive
420   -^^^^^^^^^^^^^^^^^^^^^^^^^^^
421   -
422   -Sometimes you want to match lines and would like to verify that matches
423   -happen on exactly consecutive lines with no other lines in between them.
424   -In this case, you can use CHECK: and CHECK-NEXT: directives to specify
425   -this. If you specified a custom check prefix, just use "<PREFIX>-NEXT:".
426   -For example, something like this works as you'd expect:
427   -
428   -.. code-block:: llvm
429   -
430   - define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) {
431   - %tmp3 = load <2 x double>* %A, align 16
432   - %tmp7 = insertelement <2 x double> undef, double %B, i32 0
433   - %tmp9 = shufflevector <2 x double> %tmp3,
434   - <2 x double> %tmp7,
435   - <2 x i32> < i32 0, i32 2 >
436   - store <2 x double> %tmp9, <2 x double>* %r, align 16
437   - ret void
438   -
439   - ; CHECK: t2:
440   - ; CHECK: movl 8(%esp), %eax
441   - ; CHECK-NEXT: movapd (%eax), %xmm0
442   - ; CHECK-NEXT: movhpd 12(%esp), %xmm0
443   - ; CHECK-NEXT: movl 4(%esp), %eax
444   - ; CHECK-NEXT: movapd %xmm0, (%eax)
445   - ; CHECK-NEXT: ret
446   - }
447   -
448   -CHECK-NEXT: directives reject the input unless there is exactly one
449   -newline between it an the previous directive. A CHECK-NEXT cannot be the
450   -first directive in a file.
451   -
452   -The "CHECK-NOT:" directive
453   -^^^^^^^^^^^^^^^^^^^^^^^^^^
454   -
455   -The CHECK-NOT: directive is used to verify that a string doesn't occur
456   -between two matches (or the first match and the beginning of the file).
457   -For example, to verify that a load is removed by a transformation, a
458   -test like this can be used:
459   -
460   -.. code-block:: llvm
461   -
462   - define i8 @coerce_offset0(i32 %V, i32* %P) {
463   - store i32 %V, i32* %P
464   -
465   - %P2 = bitcast i32* %P to i8*
466   - %P3 = getelementptr i8* %P2, i32 2
467   -
468   - %A = load i8* %P3
469   - ret i8 %A
470   - ; CHECK: @coerce_offset0
471   - ; CHECK-NOT: load
472   - ; CHECK: ret i8
473   - }
474   -
475   -FileCheck Pattern Matching Syntax
476   -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
477   -
478   -The CHECK: and CHECK-NOT: directives both take a pattern to match. For
479   -most uses of FileCheck, fixed string matching is perfectly sufficient.
480   -For some things, a more flexible form of matching is desired. To support
481   -this, FileCheck allows you to specify regular expressions in matching
482   -strings, surrounded by double braces: ``{{yourregex}}``. Because we want
483   -to use fixed string matching for a majority of what we do, FileCheck has
484   -been designed to support mixing and matching fixed string matching with
485   -regular expressions. This allows you to write things like this:
486   -
487   -.. code-block:: llvm
488   -
489   - ; CHECK: movhpd {{[0-9]+}}(%esp), {{%xmm[0-7]}}
490   -
491   -In this case, any offset from the ESP register will be allowed, and any
492   -xmm register will be allowed.
493   -
494   -Because regular expressions are enclosed with double braces, they are
495   -visually distinct, and you don't need to use escape characters within
496   -the double braces like you would in C. In the rare case that you want to
497   -match double braces explicitly from the input, you can use something
498   -ugly like ``{{[{][{]}}`` as your pattern.
499   -
500   -FileCheck Variables
501   -^^^^^^^^^^^^^^^^^^^
502   -
503   -It is often useful to match a pattern and then verify that it occurs
504   -again later in the file. For codegen tests, this can be useful to allow
505   -any register, but verify that that register is used consistently later.
506   -To do this, FileCheck allows named variables to be defined and
507   -substituted into patterns. Here is a simple example:
508   -
509   -.. code-block:: llvm
510   -
511   - ; CHECK: test5:
512   - ; CHECK: notw [[REGISTER:%[a-z]+]]
513   - ; CHECK: andw {{.*}}[[REGISTER]]
514   -
515   -The first check line matches a regex (``%[a-z]+``) and captures it into
516   -the variables "REGISTER". The second line verifies that whatever is in
517   -REGISTER occurs later in the file after an "andw". FileCheck variable
518   -references are always contained in ``[[ ]]`` pairs, are named, and their
519   -names can be formed with the regex "``[a-zA-Z][a-zA-Z0-9]*``". If a
520   -colon follows the name, then it is a definition of the variable, if not,
521   -it is a use.
522   -
523   -FileCheck variables can be defined multiple times, and uses always get
524   -the latest value. Note that variables are all read at the start of a
525   -"CHECK" line and are all defined at the end. This means that if you have
526   -something like "``CHECK: [[XYZ:.*]]x[[XYZ]]``" that the check line will
527   -read the previous value of the XYZ variable and define a new one after
528   -the match is performed. If you need to do something like this you can
529   -probably take advantage of the fact that FileCheck is not actually
530   -line-oriented when it matches, this allows you to define two separate
531   -CHECK lines that match on the same line.
  338 +FileCheck is designed to read a file to check from standard input, and the set
  339 +of things to verify from a file specified as a command line argument.
  340 +FileCheck is described in :doc:`the FileCheck man page
  341 +<CommandGuide/FileCheck>`.
532 342
533 343 Variables and substitutions
534 344 ---------------------------

0 comments on commit 0aea24d

Please sign in to comment.
Something went wrong with that request. Please try again.