Add compiletest docs for FileCheck prefixes and //@ filecheck-flags: (

rust-lang#1914)

This patch also adds docs for `//@ llvm-cov-flags:`, and notes that coverage
tests support revisions (though none of the current tests actually do so).

src/tests/compiletest.md

@@ -598,6 +598,21 @@ fn test_foo() {
 }
 ```
 
+In test suites that use the LLVM [FileCheck] tool, the current revision name is
+also registered as an additional prefix for FileCheck directives:
+
+```rust,ignore
+//@ revisions: NORMAL COVERAGE
+//@ [COVERAGE] compile-flags: -Cinstrument-coverage
+//@ [COVERAGE] needs-profiler-support
+
+// COVERAGE:   @__llvm_coverage_mapping
+// NORMAL-NOT: @__llvm_coverage_mapping
+
+// CHECK: main
+fn main() {}
+```
+
 Note that not all headers have meaning when customized to a revision.
 For example, the `ignore-test` header (and all "ignore" headers)
 currently only apply to the test as a whole, not to particular
@@ -609,6 +624,7 @@ Following is classes of tests that support revisions:
 - UI
 - assembly
 - codegen
+- coverage
 - debuginfo
 - rustdoc UI tests
 - incremental (these are special in that they inherently cannot be run in parallel)

src/tests/headers.md

@@ -95,6 +95,9 @@ found in [`header.rs`] from the compiletest source.
       for a known bug that has not yet been fixed
 * [Assembly](compiletest.md#assembly-tests) headers
     * `assembly-output` — the type of assembly output to check
+* [Tool-specific headers](#tool-specific-headers)
+    * `filecheck-flags` - passes extra flags to the `FileCheck` tool
+    * `llvm-cov-flags` - passes extra flags to the `llvm-cov` tool
 
 
 ### Ignoring tests
@@ -231,6 +234,19 @@ test suites.
   to be loaded by the host compiler.
 
 
+### Tool-specific headers
+
+The following headers affect how certain command-line tools are invoked,
+in test suites that use those tools:
+
+* `filecheck-flags` adds extra flags when running LLVM's `FileCheck` tool.
+  - Used by [codegen tests](compiletest.md#codegen-tests),
+  [assembly tests](compiletest.md#assembly-tests), and
+  [MIR-opt tests](compiletest.md#mir-opt-tests).
+* `llvm-cov-flags` adds extra flags when running LLVM's `llvm-cov` tool.
+  - Used by [coverage tests](compiletest.md#coverage-tests) in `coverage-run` mode.
+
+
 ## Substitutions
 
 Headers values support substituting a few variables which will be replaced