From 4108747e3d09e8e5da6f3726804ed78cf4f577c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=AE=B8=E6=9D=B0=E5=8F=8B=20Jieyou=20Xu=20=28Joe=29?= <39484203+jieyouxu@users.noreply.github.com> Date: Fri, 11 Oct 2024 21:25:42 +0800 Subject: [PATCH 1/3] Drop undefined footnotes --- src/tests/directives.md | 66 ++++++++++++++++++++--------------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/src/tests/directives.md b/src/tests/directives.md index 66ba0d14b..d8ce8f624 100644 --- a/src/tests/directives.md +++ b/src/tests/directives.md @@ -65,19 +65,19 @@ not be exhaustive. Directives can generally be found by browsing the 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`[^inc1] | N/A | -| `check-fail` | Building (no codegen) should fail | `ui`, `crashes` | N/A | -| `build-pass` | Building should pass | `ui`, `crashes`, `codegen`, `incremental`[^inc1] | N/A | -| `build-fail` | Building should fail | `ui`, `crashes` | N/A | -| `run-pass` | Running the test binary should pass | `ui`, `crashes`, `incremental`[^inc1] | N/A | -| `run-fail` | Running the test binary should fail | `ui`, `crashes` | N/A | -| `ignore-pass` | Ignore `--pass` flag | `ui`, `crashes`, `codegen`, `incremental`[^inc1] | N/A | -| `dont-check-failure-status` | Don't check exact failure status (i.e. `1`) | `ui`, `incremental` | N/A | -| `failure-status` | Check | `ui`, `crashes` | Any `u16` | -| `should-ice` | Check failure status is `101` | `coverage`, `incremental` | N/A | -| `should-fail` | Compiletest self-test | All | N/A | +| Directive | Explanation | Supported test suites | Possible values | +|-----------------------------|---------------------------------------------|-------------------------------------------|-----------------| +| `check-pass` | Building (no codegen) should pass | `ui`, `crashes`, `incremental` | N/A | +| `check-fail` | Building (no codegen) should fail | `ui`, `crashes` | N/A | +| `build-pass` | Building should pass | `ui`, `crashes`, `codegen`, `incremental` | N/A | +| `build-fail` | Building should fail | `ui`, `crashes` | N/A | +| `run-pass` | Running the test binary should pass | `ui`, `crashes`, `incremental` | N/A | +| `run-fail` | Running the test binary should fail | `ui`, `crashes` | N/A | +| `ignore-pass` | Ignore `--pass` flag | `ui`, `crashes`, `codegen`, `incremental` | N/A | +| `dont-check-failure-status` | Don't check exact failure status (i.e. `1`) | `ui`, `incremental` | N/A | +| `failure-status` | Check | `ui`, `crashes` | Any `u16` | +| `should-ice` | Check failure status is `101` | `coverage`, `incremental` | N/A | +| `should-fail` | Compiletest self-test | All | N/A | ### Controlling output snapshots and normalizations @@ -85,26 +85,26 @@ See [Normalization](ui.md#normalization), [Output comparison](ui.md#output-comparison) and [Rustfix tests](ui.md#rustfix-tests) for more details. -| Directive | Explanation | Supported test suites | Possible values | -|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|-----------------------------------------------------------------------------------------| -| `check-run-results` | Check run test binary `run-{pass,fail}` output snapshot | `ui`, `crashes`, `incremental`[^inc1] if `run-pass` | N/A | -| `error-pattern` | Check that output contains a regex pattern | `ui`, `crashes`, `incremental`[^inc1] if `run-pass` | Regex | -| `check-stdout` | Check `stdout` against `error-pattern`s from running test binary[^check_stdout] | `ui`, `crashes`, `incremental`[^inc1] | N/A | -| `compare-output-lines-by-subset` | Check output contains the contents of the snapshot by lines opposed to checking for strict equality | `ui`, `coverage` | N/A | -| `normalize-stderr-32bit` | Normalize actual stderr (for 32-bit platforms) with a rule `"" -> ""` before comparing against snapshot | `ui`, `incremental`[^inc1] | `"" -> ""`, ``/`` is regex capture and replace syntax | -| `normalize-stderr-64bit` | Normalize actual stderr (for 64-bit platforms) with a rule `"" -> ""` before comparing against snapshot | `ui`, `incremental`[^inc1] | `"" -> ""`, ``/`` is regex capture and replace syntax | -| `normalize-stderr-test` | Normalize actual stderr with a rule `"" -> ""` before comparing against snapshot | `ui`, `incremental`[^inc1] | `"" -> ""`, ``/`` is regex capture and replace syntax | -| `normalize-stdout-test` | Normalize actual stdout with a rule `"" -> ""` before comparing against snapshot | `ui`, `incremental`[^inc1] | `"" -> ""`, ``/`` is regex capture and replace syntax | -| `dont-check-compiler-stderr` | Don't check actual compiler stderr vs stderr snapshot | `ui` | N/A | -| `dont-check-compiler-stdout` | Don't check actual compiler stdout vs stdout snapshot | `ui` | N/A | -| `run-rustfix` | Apply all suggestions via `rustfix`, snapshot fixed output, and check fixed output builds | `ui` | N/A | -| `rustfix-only-machine-applicable` | `run-rustfix` but only machine-applicable suggestions | `ui` | N/A | -| `exec-env` | Env var to set when executing a test | `ui`, `crashes` | `=` | -| `unset-exec-env` | Env var to unset when executing a test | `ui`, `crashes` | Any env var name | -| `stderr-per-bitwidth` | Generate a stderr snapshot for each bitwidth | `ui` | N/A | -| `forbid-output` | A pattern which must not appear in `cfail` output | `incremental` | Regex pattern | -| `run-flags` | Flags passed to the test executable | `ui` | Arbitrary flags | -| `known-bug` | No error annotation needed due to known bug | `ui`, `crashes`, `incremental` | Issue number `#123456` | +| Directive | Explanation | Supported test suites | Possible values | +|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------|----------------------------------------------|-----------------------------------------------------------------------------------------| +| `check-run-results` | Check run test binary `run-{pass,fail}` output snapshot | `ui`, `crashes`, `incremental` if `run-pass` | N/A | +| `error-pattern` | Check that output contains a regex pattern | `ui`, `crashes`, `incremental` if `run-pass` | Regex | +| `check-stdout` | Check `stdout` against `error-pattern`s from running test binary[^check_stdout] | `ui`, `crashes`, `incremental` | N/A | +| `compare-output-lines-by-subset` | Check output contains the contents of the snapshot by lines opposed to checking for strict equality | `ui`, `coverage` | N/A | +| `normalize-stderr-32bit` | Normalize actual stderr (for 32-bit platforms) with a rule `"" -> ""` before comparing against snapshot | `ui`, `incremental` | `"" -> ""`, ``/`` is regex capture and replace syntax | +| `normalize-stderr-64bit` | Normalize actual stderr (for 64-bit platforms) with a rule `"" -> ""` before comparing against snapshot | `ui`, `incremental` | `"" -> ""`, ``/`` is regex capture and replace syntax | +| `normalize-stderr-test` | Normalize actual stderr with a rule `"" -> ""` before comparing against snapshot | `ui`, `incremental` | `"" -> ""`, ``/`` is regex capture and replace syntax | +| `normalize-stdout-test` | Normalize actual stdout with a rule `"" -> ""` before comparing against snapshot | `ui`, `incremental` | `"" -> ""`, ``/`` is regex capture and replace syntax | +| `dont-check-compiler-stderr` | Don't check actual compiler stderr vs stderr snapshot | `ui` | N/A | +| `dont-check-compiler-stdout` | Don't check actual compiler stdout vs stdout snapshot | `ui` | N/A | +| `run-rustfix` | Apply all suggestions via `rustfix`, snapshot fixed output, and check fixed output builds | `ui` | N/A | +| `rustfix-only-machine-applicable` | `run-rustfix` but only machine-applicable suggestions | `ui` | N/A | +| `exec-env` | Env var to set when executing a test | `ui`, `crashes` | `=` | +| `unset-exec-env` | Env var to unset when executing a test | `ui`, `crashes` | Any env var name | +| `stderr-per-bitwidth` | Generate a stderr snapshot for each bitwidth | `ui` | N/A | +| `forbid-output` | A pattern which must not appear in `cfail` output | `incremental` | Regex pattern | +| `run-flags` | Flags passed to the test executable | `ui` | Arbitrary flags | +| `known-bug` | No error annotation needed due to known bug | `ui`, `crashes`, `incremental` | Issue number `#123456` | [^check_stdout]: presently this has a weird quirk where the test binary's stdout and stderr gets concatenated and then From 0f568c4492ec923e7e70c62a9e6048abb880ee81 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=AE=B8=E6=9D=B0=E5=8F=8B=20Jieyou=20Xu=20=28Joe=29?= <39484203+jieyouxu@users.noreply.github.com> Date: Fri, 11 Oct 2024 21:26:55 +0800 Subject: [PATCH 2/3] Use directives consistently --- src/SUMMARY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 6bc19e62d..1737ada16 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -24,7 +24,7 @@ - [Best practices](./tests/best-practices.md) - [Compiletest](./tests/compiletest.md) - [UI tests](./tests/ui.md) - - [Test headers](./tests/directives.md) + - [Test directives](./tests/directives.md) - [Ecosystem testing](./tests/ecosystem.md) - [Crater](./tests/crater.md) - [Fuchsia](./tests/fuchsia.md) From 0e54ad170b901cf4d61dafc150f4bbe5b75aebec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=AE=B8=E6=9D=B0=E5=8F=8B=20Jieyou=20Xu=20=28Joe=29?= <39484203+jieyouxu@users.noreply.github.com> Date: Fri, 11 Oct 2024 21:38:05 +0800 Subject: [PATCH 3/3] Describe `minicore` test auxiliary and directive --- src/SUMMARY.md | 1 + src/tests/compiletest.md | 6 ++++++ src/tests/minicore.md | 45 ++++++++++++++++++++++++++++++++++++++++ src/tests/ui.md | 3 +++ 4 files changed, 55 insertions(+) create mode 100644 src/tests/minicore.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 1737ada16..a9ee9738e 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -25,6 +25,7 @@ - [Compiletest](./tests/compiletest.md) - [UI tests](./tests/ui.md) - [Test directives](./tests/directives.md) + - [Minicore](./tests/minicore.md) - [Ecosystem testing](./tests/ecosystem.md) - [Crater](./tests/crater.md) - [Fuchsia](./tests/fuchsia.md) diff --git a/src/tests/compiletest.md b/src/tests/compiletest.md index 41cc141a2..4dcf73199 100644 --- a/src/tests/compiletest.md +++ b/src/tests/compiletest.md @@ -283,6 +283,9 @@ more information. See also the [assembly tests](#assembly-tests) for a similar set of tests. +If you need to work with `#![no_std]` cross-compiling tests, consult the +[`minicore` test auxiliary](./minicore.md) chapter. + [`tests/codegen`]: https://github.com/rust-lang/rust/tree/master/tests/codegen [FileCheck]: https://llvm.org/docs/CommandGuide/FileCheck.html @@ -303,6 +306,9 @@ information. See also the [codegen tests](#codegen-tests) for a similar set of tests. +If you need to work with `#![no_std]` cross-compiling tests, consult the +[`minicore` test auxiliary](./minicore.md) chapter. + [`tests/assembly`]: https://github.com/rust-lang/rust/tree/master/tests/assembly diff --git a/src/tests/minicore.md b/src/tests/minicore.md new file mode 100644 index 000000000..dc5db00c6 --- /dev/null +++ b/src/tests/minicore.md @@ -0,0 +1,45 @@ +# `minicore` test auxiliary + +[`tests/auxiliary/minicore.rs`][`minicore`] is a test auxiliary for +ui/codegen/assembly test suites. It provides `core` stubs for tests that need to +build for cross-compiled targets but do not need/want to run. + +A test can use [`minicore`] by specifying the `//@ use-minicore` directive. Then, +mark the test with `#![feature(no_core)]` + `#![no_std]` + `#![no_core]`. Due to +Edition 2015 extern prelude rules, you will probably need to declare `minicore` +as an extern crate. + +Due to the `no_std` + `no_core` nature of these tests, `//@ use-minicore` +implies and requires that the test will be built with `-C panic=abort`. +Unwinding panics are not supported. + +If you find a `core` item to be missing from the [`minicore`] stub, consider +adding it to the test auxiliary. However, please note that [`minicore`] is only +intended for `core` items, and explicitly not `std` or `alloc` items because +`core` items are applicable to a wider range of tests. + +## Example codegen test that uses `minicore` + +```rust,no_run +//@ use-minicore +//@ revisions: meow +//@[meow] compile-flags: --target=x86_64-unknown-linux-gnu +//@[meow] needs-llvm-components: x86 + +#![crate_type = "lib"] +#![feature(no_core)] +#![no_std] +#![no_core] + +extern crate minicore; +use minicore::*; + +struct Meow; +impl Copy for Meow {} // `Copy` here is provided by `minicore` + +// CHECK-LABEL: meow +#[no_mangle] +fn meow() {} +``` + +[minicore]: https://github.com/rust-lang/rust/tree/master/tests/auxiliary/minicore.rs diff --git a/src/tests/ui.md b/src/tests/ui.md index 610af41e5..23105a57f 100644 --- a/src/tests/ui.md +++ b/src/tests/ui.md @@ -13,6 +13,9 @@ used for many other purposes. For example, tests can also be configured to [run the resulting program](#controlling-passfail-expectations) to verify its behavior. +If you need to work with `#![no_std]` cross-compiling tests, consult the +[`minicore` test auxiliary](./minicore.md) chapter. + [`tests/ui`]: https://github.com/rust-lang/rust/blob/master/tests/ui ## General structure of a test