Compiletest Directives: Overview and Listing

# Compiletest directives   Directives are special comments that tell compiletest how to build and interpret a test. They may also appear in `rmake.rs` [run-make tests](compiletest.md#run-make-tests). They are normally put after the short comment that explains the point of this test. Compiletest test suites use `//@` to signal that a comment is a directive. For example, this test uses the `//@ compile-flags` command to specify a custom flag to give to rustc when the test is compiled: ```rust,ignore // Test the behavior of `0 - 1` when overflow checks are disabled. //@ compile-flags: -C overflow-checks=off fn main() { let x = 0 - 1; ... } ``` Directives can be standalone (like `//@ run-pass`) or take a value (like `//@ compile-flags: -C overflow-checks=off`). Directives are written one directive per line: you cannot write multiple directives on the same line. For example, if you write `//@ only-x86 only-windows` then `only-windows` is interpreted as a comment, not a separate directive. ## Listing of compiletest directives The following is a list of compiletest directives. Directives are linked to sections that describe the command in more detail if available. This list may not be exhaustive. Directives can generally be found by browsing the `TestProps` structure found in [`header.rs`] from the compiletest source. ### Assembly  | Directive | Explanation | Supported test suites | Possible values | |-------------------|-------------------------------|-----------------------|----------------------------------------| | `assembly-output` | Assembly output kind to check | `assembly` | `emit-asm`, `bpf-linker`, `ptx-linker` | ### Auxiliary builds | Directive | Explanation | Supported test suites | Possible values | |-----------------------|-------------------------------------------------------------------------------------------------------|-----------------------|-----------------------------------------------| | `aux-bin` | Build a aux binary, made available in `auxiliary/bin` relative to test directory | All except `run-make` | Path to auxiliary `.rs` file | | `aux-build` | Build a separate crate from the named source file | All except `run-make` | Path to auxiliary `.rs` file | | `aux-crate` | Like `aux-build` but makes available as extern prelude | All except `run-make` | `<extern_prelude_name>=<path/to/aux/file.rs>` | | `aux-codegen-backend` | Similar to `aux-build` but pass the compiled dylib to `-Zcodegen-backend` when building the main file | `ui-fulldeps` | Path to codegen backend file | | `proc-macro` | Similar to `aux-build`, but for aux forces host and don't use `-Cprefer-dynamic`[^pm]. | All except `run-make` | Path to auxiliary proc-macro `.rs` file | | `build-aux-docs` | Build docs for auxiliaries as well | All except `run-make` | N/A | [compiletest](./compiletest.md) chapter for specifics. ### Controlling outcome expectations See [Controlling pass/fail expectations](ui.md#controlling-passfail-expectations). | Directive | Explanation | Supported test suites | Possible values | |-----------------------------|---------------------------------------------|-------------------------------------------|-----------------| | `check-pass` | Building (no codegen) should pass | `ui`, `crashes`, `incremental` | N/A |

This section introduces compiletest directives, which are special comments used in Rust tests to instruct the compiletest tool on how to build and interpret the test. Directives are identified by the `//@` prefix. The text provides a list of directives, categorized by functionality (Assembly, Auxiliary builds, and Controlling outcome expectations), including their explanations, supported test suites, and possible values.