--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/components/llvm/Solaris/man1/FileCheck.1 Thu Jul 28 16:25:34 2016 -0700
@@ -0,0 +1,555 @@
+.\" Man page generated from reStructuredText.
+.
+.TH "FILECHECK" "1" "2016-07-10" "3.8" "LLVM"
+.SH NAME
+FileCheck \- Flexible pattern matching file verifier
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.SH SYNOPSIS
+.sp
+\fBFileCheck\fP \fImatch\-filename\fP [\fI\-\-check\-prefix=XXX\fP] [\fI\-\-strict\-whitespace\fP]
+.SH DESCRIPTION
+.sp
+\fBFileCheck\fP 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. \fBllc\fP) contains the expected information
+(for example, a movsd from esp or whatever is interesting). This is similar to
+using \fBgrep\fP, but it is optimized for matching multiple different
+inputs in one file in a specific order.
+.sp
+The \fBmatch\-filename\fP file specifies the file that contains the patterns to
+match. The file to verify is read from standard input unless the
+\fI\%\-\-input\-file\fP option is used.
+.SH OPTIONS
+.INDENT 0.0
+.TP
+.B \-help
+Print a summary of command line options.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-check\-prefix prefix
+FileCheck searches the contents of \fBmatch\-filename\fP for patterns to
+match. By default, these patterns are prefixed with "\fBCHECK:\fP".
+If you\(aqd like to use a different prefix (e.g. because the same input
+file is checking multiple different tool or options), the
+\fI\%\-\-check\-prefix\fP argument allows you to specify 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.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-input\-file filename
+File to check (defaults to stdin).
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-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 \fI\%\-\-strict\-whitespace\fP argument disables this behavior. End\-of\-line
+sequences are canonicalized to UNIX\-style \fB\en\fP in all modes.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-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
+\fBCHECK\-NOT\fPs.
+.sp
+For example, "\fB\-\-implicit\-check\-not warning:\fP" can be useful when testing
+diagnostic messages from tools that don\(aqt have an option similar to \fBclang
+\-verify\fP\&. With this option FileCheck will verify that input does not contain
+warnings not covered by any \fBCHECK:\fP patterns.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-version
+Show the version number of this program.
+.UNINDENT
+.SH EXIT STATUS
+.sp
+If \fBFileCheck\fP 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.
+.SH TUTORIAL
+.sp
+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:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+; RUN: llvm\-as < %s | llc \-march=x86\-64 | FileCheck %s
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This syntax says to pipe the current file ("\fB%s\fP") into \fBllvm\-as\fP, pipe
+that into \fBllc\fP, then pipe the output of \fBllc\fP into \fBFileCheck\fP\&. This
+means that FileCheck will be verifying its standard input (the llc output)
+against the filename argument specified (the original \fB\&.ll\fP file specified by
+"\fB%s\fP"). To see how this works, let\(aqs look at the rest of the \fB\&.ll\fP file
+(after the RUN line):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+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:
+; CHECK: inc4:
+; CHECK: incq
+ %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1)
+ ret void
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Here you can see some "\fBCHECK:\fP" lines specified in comments. Now you can
+see how the file is piped into \fBllvm\-as\fP, then \fBllc\fP, and the machine code
+output is what we are verifying. FileCheck checks the machine code output to
+verify that it matches what the "\fBCHECK:\fP" lines specify.
+.sp
+The syntax of the "\fBCHECK:\fP" lines is very simple: they are fixed strings that
+must occur in order. FileCheck defaults to ignoring horizontal whitespace
+differences (e.g. a space is allowed to match a tab) but otherwise, the contents
+of the "\fBCHECK:\fP" line is required to match some thing in the test file exactly.
+.sp
+One nice thing about FileCheck (compared to grep) is that it allows merging
+test cases together into logical groups. For example, because the test above
+is checking for the "\fBsub1:\fP" and "\fBinc4:\fP" labels, it will not match
+unless there is a "\fBsubl\fP" in between those labels. If it existed somewhere
+else in the file, that would not count: "\fBgrep subl\fP" matches if "\fBsubl\fP"
+exists anywhere in the file.
+.SS The FileCheck \-check\-prefix option
+.sp
+The FileCheck \fB\-check\-prefix\fP option allows multiple test
+configurations to be driven from one \fI\&.ll\fP file. This is useful in many
+circumstances, for example, testing different architectural variants with
+\fBllc\fP\&. Here\(aqs a simple example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+; RUN: llvm\-as < %s | llc \-mtriple=i686\-apple\-darwin9 \-mattr=sse41 \e
+; RUN: | FileCheck %s \-check\-prefix=X32
+; RUN: llvm\-as < %s | llc \-mtriple=x86_64\-apple\-darwin9 \-mattr=sse41 \e
+; RUN: | FileCheck %s \-check\-prefix=X64
+
+define <4 x i32> @pinsrd_1(i32 %s, <4 x i32> %tmp) nounwind {
+ %tmp1 = insertelement <4 x i32>; %tmp, i32 %s, i32 1
+ ret <4 x i32> %tmp1
+; X32: pinsrd_1:
+; X32: pinsrd $1, 4(%esp), %xmm0
+
+; X64: pinsrd_1:
+; X64: pinsrd $1, %edi, %xmm0
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In this case, we\(aqre testing that we get the expected code generation with
+both 32\-bit and 64\-bit code generation.
+.SS The "CHECK\-NEXT:" directive
+.sp
+Sometimes you want to match lines and would like to verify that matches
+happen on exactly consecutive lines with no other lines in between them. In
+this case, you can use "\fBCHECK:\fP" and "\fBCHECK\-NEXT:\fP" directives to specify
+this. If you specified a custom check prefix, just use "\fB<PREFIX>\-NEXT:\fP".
+For example, something like this works as you\(aqd expect:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) {
+ %tmp3 = load <2 x double>* %A, align 16
+ %tmp7 = insertelement <2 x double> undef, double %B, i32 0
+ %tmp9 = shufflevector <2 x double> %tmp3,
+ <2 x double> %tmp7,
+ <2 x i32> < i32 0, i32 2 >
+ store <2 x double> %tmp9, <2 x double>* %r, align 16
+ ret void
+
+; CHECK: t2:
+; CHECK: movl 8(%esp), %eax
+; CHECK\-NEXT: movapd (%eax), %xmm0
+; CHECK\-NEXT: movhpd 12(%esp), %xmm0
+; CHECK\-NEXT: movl 4(%esp), %eax
+; CHECK\-NEXT: movapd %xmm0, (%eax)
+; CHECK\-NEXT: ret
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+"\fBCHECK\-NEXT:\fP" directives reject the input unless there is exactly one
+newline between it and the previous directive. A "\fBCHECK\-NEXT:\fP" cannot be
+the first directive in a file.
+.SS The "CHECK\-SAME:" directive
+.sp
+Sometimes you want to match lines and would like to verify that matches happen
+on the same line as the previous match. In this case, you can use "\fBCHECK:\fP"
+and "\fBCHECK\-SAME:\fP" directives to specify this. If you specified a custom
+check prefix, just use "\fB<PREFIX>\-SAME:\fP".
+.sp
+"\fBCHECK\-SAME:\fP" is particularly powerful in conjunction with "\fBCHECK\-NOT:\fP"
+(described below).
+.sp
+For example, the following works like you\(aqd expect:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+!0 = !DILocation(line: 5, scope: !1, inlinedAt: !2)
+
+; CHECK: !DILocation(line: 5,
+; CHECK\-NOT: column:
+; CHECK\-SAME: scope: ![[SCOPE:[0\-9]+]]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+"\fBCHECK\-SAME:\fP" directives reject the input if there are any newlines between
+it and the previous directive. A "\fBCHECK\-SAME:\fP" cannot be the first
+directive in a file.
+.SS The "CHECK\-NOT:" directive
+.sp
+The "\fBCHECK\-NOT:\fP" directive is used to verify that a string doesn\(aqt occur
+between two matches (or before the first match, or after the last match). For
+example, to verify that a load is removed by a transformation, a test like this
+can be used:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+define i8 @coerce_offset0(i32 %V, i32* %P) {
+ store i32 %V, i32* %P
+
+ %P2 = bitcast i32* %P to i8*
+ %P3 = getelementptr i8* %P2, i32 2
+
+ %A = load i8* %P3
+ ret i8 %A
+; CHECK: @coerce_offset0
+; CHECK\-NOT: load
+; CHECK: ret i8
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS The "CHECK\-DAG:" directive
+.sp
+If it\(aqs necessary to match strings that don\(aqt occur in a strictly sequential
+order, "\fBCHECK\-DAG:\fP" could be used to verify them between two matches (or
+before the first match, or after the last match). For example, clang emits
+vtable globals in reverse order. Using \fBCHECK\-DAG:\fP, we can keep the checks
+in the natural order:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+// RUN: %clang_cc1 %s \-emit\-llvm \-o \- | FileCheck %s
+
+struct Foo { virtual void method(); };
+Foo f; // emit vtable
+// CHECK\-DAG: @_ZTV3Foo =
+
+struct Bar { virtual void method(); };
+Bar b;
+// CHECK\-DAG: @_ZTV3Bar =
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBCHECK\-NOT:\fP directives could be mixed with \fBCHECK\-DAG:\fP directives to
+exclude strings between the surrounding \fBCHECK\-DAG:\fP directives. As a result,
+the surrounding \fBCHECK\-DAG:\fP directives cannot be reordered, i.e. all
+occurrences matching \fBCHECK\-DAG:\fP before \fBCHECK\-NOT:\fP must not fall behind
+occurrences matching \fBCHECK\-DAG:\fP after \fBCHECK\-NOT:\fP\&. For example,
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+; CHECK\-DAG: BEFORE
+; CHECK\-NOT: NOT
+; CHECK\-DAG: AFTER
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This case will reject input strings where \fBBEFORE\fP occurs after \fBAFTER\fP\&.
+.sp
+With captured variables, \fBCHECK\-DAG:\fP is able to match valid topological
+orderings of a DAG with edges from the definition of a variable to its use.
+It\(aqs useful, e.g., when your test cases need to match different output
+sequences from the instruction scheduler. For example,
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+; CHECK\-DAG: add [[REG1:r[0\-9]+]], r1, r2
+; CHECK\-DAG: add [[REG2:r[0\-9]+]], r3, r4
+; CHECK: mul r5, [[REG1]], [[REG2]]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In this case, any order of that two \fBadd\fP instructions will be allowed.
+.sp
+If you are defining \fIand\fP using variables in the same \fBCHECK\-DAG:\fP block,
+be aware that the definition rule can match \fIafter\fP its use.
+.sp
+So, for instance, the code below will pass:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+; CHECK\-DAG: vmov.32 [[REG2:d[0\-9]+]][0]
+; CHECK\-DAG: vmov.32 [[REG2]][1]
+vmov.32 d0[1]
+vmov.32 d0[0]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+While this other code, will not:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+; CHECK\-DAG: vmov.32 [[REG2:d[0\-9]+]][0]
+; CHECK\-DAG: vmov.32 [[REG2]][1]
+vmov.32 d1[1]
+vmov.32 d0[0]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+While this can be very useful, it\(aqs also dangerous, because in the case of
+register sequence, you must have a strong order (read before write, copy before
+use, etc). If the definition your test is looking for doesn\(aqt match (because
+of a bug in the compiler), it may match further away from the use, and mask
+real bugs away.
+.sp
+In those cases, to enforce the order, use a non\-DAG directive between DAG\-blocks.
+.SS The "CHECK\-LABEL:" directive
+.sp
+Sometimes in a file containing multiple tests divided into logical blocks, one
+or more \fBCHECK:\fP directives may inadvertently succeed by matching lines in a
+later block. While an error will usually eventually be generated, the check
+flagged as causing the error may not actually bear any relationship to the
+actual source of the problem.
+.sp
+In order to produce better error messages in these cases, the "\fBCHECK\-LABEL:\fP"
+directive can be used. It is treated identically to a normal \fBCHECK\fP
+directive except that FileCheck makes an additional assumption that a line
+matched by the directive cannot also be matched by any other check present in
+\fBmatch\-filename\fP; this is intended to be used for lines containing labels or
+other unique identifiers. Conceptually, the presence of \fBCHECK\-LABEL\fP divides
+the input stream into separate blocks, each of which is processed independently,
+preventing a \fBCHECK:\fP directive in one block matching a line in another block.
+For example,
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+define %struct.C* @C_ctor_base(%struct.C* %this, i32 %x) {
+entry:
+; CHECK\-LABEL: C_ctor_base:
+; CHECK: mov [[SAVETHIS:r[0\-9]+]], r0
+; CHECK: bl A_ctor_base
+; CHECK: mov r0, [[SAVETHIS]]
+ %0 = bitcast %struct.C* %this to %struct.A*
+ %call = tail call %struct.A* @A_ctor_base(%struct.A* %0)
+ %1 = bitcast %struct.C* %this to %struct.B*
+ %call2 = tail call %struct.B* @B_ctor_base(%struct.B* %1, i32 %x)
+ ret %struct.C* %this
+}
+
+define %struct.D* @D_ctor_base(%struct.D* %this, i32 %x) {
+entry:
+; CHECK\-LABEL: D_ctor_base:
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The use of \fBCHECK\-LABEL:\fP directives in this case ensures that the three
+\fBCHECK:\fP directives only accept lines corresponding to the body of the
+\fB@C_ctor_base\fP function, even if the patterns match lines found later in
+the file. Furthermore, if one of these three \fBCHECK:\fP directives fail,
+FileCheck will recover by continuing to the next block, allowing multiple test
+failures to be detected in a single invocation.
+.sp
+There is no requirement that \fBCHECK\-LABEL:\fP directives contain strings that
+correspond to actual syntactic labels in a source or output language: they must
+simply uniquely match a single line in the file being verified.
+.sp
+\fBCHECK\-LABEL:\fP directives cannot contain variable definitions or uses.
+.SS FileCheck Pattern Matching Syntax
+.sp
+All FileCheck directives take a pattern to match.
+For most uses of FileCheck, fixed string matching is perfectly sufficient. For
+some things, a more flexible form of matching is desired. To support this,
+FileCheck allows you to specify regular expressions in matching strings,
+surrounded by double braces: \fB{{yourregex}}\fP\&. Because we want to use fixed
+string matching for a majority of what we do, FileCheck has been designed to
+support mixing and matching fixed string matching with regular expressions.
+This allows you to write things like this:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+; CHECK: movhpd {{[0\-9]+}}(%esp), {{%xmm[0\-7]}}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In this case, any offset from the ESP register will be allowed, and any xmm
+register will be allowed.
+.sp
+Because regular expressions are enclosed with double braces, they are
+visually distinct, and you don\(aqt need to use escape characters within the double
+braces like you would in C. In the rare case that you want to match double
+braces explicitly from the input, you can use something ugly like
+\fB{{[{][{]}}\fP as your pattern.
+.SS FileCheck Variables
+.sp
+It is often useful to match a pattern and then verify that it occurs again
+later in the file. For codegen tests, this can be useful to allow any register,
+but verify that that register is used consistently later. To do this,
+\fBFileCheck\fP allows named variables to be defined and substituted into
+patterns. Here is a simple example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+; CHECK: test5:
+; CHECK: notw [[REGISTER:%[a\-z]+]]
+; CHECK: andw {{.*}}[[REGISTER]]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The first check line matches a regex \fB%[a\-z]+\fP and captures it into the
+variable \fBREGISTER\fP\&. The second line verifies that whatever is in
+\fBREGISTER\fP occurs later in the file after an "\fBandw\fP". \fBFileCheck\fP
+variable references are always contained in \fB[[ ]]\fP pairs, and their names can
+be formed with the regex \fB[a\-zA\-Z][a\-zA\-Z0\-9]*\fP\&. If a colon follows the name,
+then it is a definition of the variable; otherwise, it is a use.
+.sp
+\fBFileCheck\fP variables can be defined multiple times, and uses always
+get the latest value. Variables can also be used later on the same line they
+were defined on. For example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+; CHECK: op [[REG:r[0\-9]+]], [[REG]]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Can be useful if you want the operands of \fBop\fP to be the same register,
+and don\(aqt care exactly which register it is.
+.SS FileCheck Expressions
+.sp
+Sometimes there\(aqs a need to verify output which refers line numbers of the
+match file, e.g. when testing compiler diagnostics. This introduces a certain
+fragility of the match file structure, as "\fBCHECK:\fP" lines contain absolute
+line numbers in the same file, which have to be updated whenever line numbers
+change due to text addition or deletion.
+.sp
+To support this case, FileCheck allows using \fB[[@LINE]]\fP,
+\fB[[@LINE+<offset>]]\fP, \fB[[@LINE\-<offset>]]\fP expressions in patterns. These
+expressions expand to a number of the line where a pattern is located (with an
+optional integer offset).
+.sp
+This way match patterns can be put near the relevant test lines and include
+relative line number references, for example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+// CHECK: test.cpp:[[@LINE+4]]:6: error: expected \(aq;\(aq after top level declarator
+// CHECK\-NEXT: {{^int a}}
+// CHECK\-NEXT: {{^ \e^}}
+// CHECK\-NEXT: {{^ ;}}
+int a
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH AUTHOR
+Maintained by The LLVM Team (http://llvm.org/).
+.SH COPYRIGHT
+2003-2016, LLVM Project
+.\" Generated by docutils manpage writer.
+.