Directives for Test Building, Rustdoc, and Tool-Specific Options

7th chunk of `src/tests/directives.md`

390b40e5763b03ba3b5e003cc05f95f00ec1afe2b2ce86360000000100000fbb

| Directive           | Explanation                                                                                  | Supported test suites     | Possible values                                                                            |
|---------------------|----------------------------------------------------------------------------------------------|---------------------------|--------------------------------------------------------------------------------------------|
| `compile-flags`     | Flags passed to `rustc` when building the test or aux file                                   | All except for `run-make` | Any valid `rustc` flags, e.g. `-Awarnings -Dfoo`. Cannot be `-Cincremental` or `--edition` |
| `edition`           | The edition used to build the test                                                           | All except for `run-make` | Any valid `--edition` value                                                                |
| `rustc-env`         | Env var to set when running `rustc`                                                          | All except for `run-make` | `<KEY>=<VALUE>`                                                                            |
| `unset-rustc-env`   | Env var to unset when running `rustc`                                                        | All except for `run-make` | Any env var name                                                                           |
| `incremental`       | Proper incremental support for tests outside of incremental test suite                       | `ui`, `crashes`           | N/A                                                                                        |
| `no-prefer-dynamic` | Don't use `-C prefer-dynamic`, don't build as a dylib via a `--crate-type=dylib` preset flag | `ui`, `crashes`           | N/A                                                                                        |

<div class="warning">

Tests (outside of `run-make`) that want to use incremental tests not in the
incremental test-suite must not pass `-C incremental` via `compile-flags`, and
must instead use the `//@ incremental` directive.

Consider writing the test as a proper incremental test instead.

</div>

### Rustdoc

| Directive   | Explanation                                                  | Supported test suites                    | Possible values           |
|-------------|--------------------------------------------------------------|------------------------------------------|---------------------------|
| `doc-flags` | Flags passed to `rustdoc` when building the test or aux file | `rustdoc`, `rustdoc-js`, `rustdoc-json` | Any valid `rustdoc` flags |

<!--
**FIXME(rustdoc)**: what does `check-test-line-numbers-match` do?
Asked in
<https://rust-lang.zulipchat.com/#narrow/stream/266220-t-rustdoc/topic/What.20is.20the.20.60check-test-line-numbers-match.60.20directive.3F>.
-->

### Pretty printing

See [Pretty-printer](compiletest.md#pretty-printer-tests).

#### Misc directives

- `no-auto-check-cfg` — disable auto check-cfg (only for `--check-cfg` tests)
- [`revisions`](compiletest.md#revisions) — compile multiple times
- [`unused-revision-names`](compiletest.md#ignoring-unused-revision-names) -
      suppress tidy checks for mentioning unknown revision names
-[`forbid-output`](compiletest.md#incremental-tests) — incremental cfail rejects
      output pattern
- [`should-ice`](compiletest.md#incremental-tests) — incremental cfail should
      ICE
- [`reference`] — an annotation linking to a rule in the reference


### Tool-specific directives

The following directives 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.

Title: Directives for Test Building, Rustdoc, and Tool-Specific Options

Summary

This section details additional directives for controlling test building, including `unset-rustc-env`, `incremental`, and `no-prefer-dynamic`. It highlights the warning against using `-C incremental` directly via `compile-flags` and suggests using the `//@ incremental` directive instead. It also covers Rustdoc directives like `doc-flags` and mentions misc directives such as `no-auto-check-cfg`, `revisions`, `unused-revision-names`, `forbid-output`, `should-ice`, and `reference`. The section concludes with tool-specific directives like `filecheck-flags` and `llvm-cov-flags` for customizing the invocation of tools like `FileCheck` and `llvm-cov` in relevant test suites.