Skip to content

Commit 6ff146c

Browse files
jieyouxujieyouxu
authored
Describe minicore test auxiliary and directive (#2097)
1 parent f715ad7 commit 6ff146c

File tree

5 files changed

+98
-34
lines changed

5 files changed

+98
-34
lines changed

‎src/SUMMARY.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,8 @@
2424
- [Best practices](./tests/best-practices.md)
2525
- [Compiletest](./tests/compiletest.md)
2626
- [UI tests](./tests/ui.md)
27-
- [Test headers](./tests/directives.md)
27+
- [Test directives](./tests/directives.md)
28+
- [Minicore](./tests/minicore.md)
2829
- [Ecosystem testing](./tests/ecosystem.md)
2930
- [Crater](./tests/crater.md)
3031
- [Fuchsia](./tests/fuchsia.md)

‎src/tests/compiletest.md

+6
Original file line numberDiff line numberDiff line change
@@ -283,6 +283,9 @@ more information.
283283

284284
See also the [assembly tests](#assembly-tests) for a similar set of tests.
285285

286+
If you need to work with `#![no_std]` cross-compiling tests, consult the
287+
[`minicore` test auxiliary](./minicore.md) chapter.
288+
286289
[`tests/codegen`]: https://github.com/rust-lang/rust/tree/master/tests/codegen
287290
[FileCheck]: https://llvm.org/docs/CommandGuide/FileCheck.html
288291

@@ -303,6 +306,9 @@ information.
303306

304307
See also the [codegen tests](#codegen-tests) for a similar set of tests.
305308

309+
If you need to work with `#![no_std]` cross-compiling tests, consult the
310+
[`minicore` test auxiliary](./minicore.md) chapter.
311+
306312
[`tests/assembly`]: https://github.com/rust-lang/rust/tree/master/tests/assembly
307313

308314

‎src/tests/directives.md

+33-33
Original file line numberDiff line numberDiff line change
@@ -65,46 +65,46 @@ not be exhaustive. Directives can generally be found by browsing the
6565
See [Controlling pass/fail
6666
expectations](ui.md#controlling-passfail-expectations).
6767

68-
| Directive | Explanation | Supported test suites | Possible values |
69-
|-----------------------------|---------------------------------------------|--------------------------------------------------|-----------------|
70-
| `check-pass` | Building (no codegen) should pass | `ui`, `crashes`, `incremental`[^inc1] | N/A |
71-
| `check-fail` | Building (no codegen) should fail | `ui`, `crashes` | N/A |
72-
| `build-pass` | Building should pass | `ui`, `crashes`, `codegen`, `incremental`[^inc1] | N/A |
73-
| `build-fail` | Building should fail | `ui`, `crashes` | N/A |
74-
| `run-pass` | Running the test binary should pass | `ui`, `crashes`, `incremental`[^inc1] | N/A |
75-
| `run-fail` | Running the test binary should fail | `ui`, `crashes` | N/A |
76-
| `ignore-pass` | Ignore `--pass` flag | `ui`, `crashes`, `codegen`, `incremental`[^inc1] | N/A |
77-
| `dont-check-failure-status` | Don't check exact failure status (i.e. `1`) | `ui`, `incremental` | N/A |
78-
| `failure-status` | Check | `ui`, `crashes` | Any `u16` |
79-
| `should-ice` | Check failure status is `101` | `coverage`, `incremental` | N/A |
80-
| `should-fail` | Compiletest self-test | All | N/A |
68+
| Directive | Explanation | Supported test suites | Possible values |
69+
|-----------------------------|---------------------------------------------|-------------------------------------------|-----------------|
70+
| `check-pass` | Building (no codegen) should pass | `ui`, `crashes`, `incremental` | N/A |
71+
| `check-fail` | Building (no codegen) should fail | `ui`, `crashes` | N/A |
72+
| `build-pass` | Building should pass | `ui`, `crashes`, `codegen`, `incremental` | N/A |
73+
| `build-fail` | Building should fail | `ui`, `crashes` | N/A |
74+
| `run-pass` | Running the test binary should pass | `ui`, `crashes`, `incremental` | N/A |
75+
| `run-fail` | Running the test binary should fail | `ui`, `crashes` | N/A |
76+
| `ignore-pass` | Ignore `--pass` flag | `ui`, `crashes`, `codegen`, `incremental` | N/A |
77+
| `dont-check-failure-status` | Don't check exact failure status (i.e. `1`) | `ui`, `incremental` | N/A |
78+
| `failure-status` | Check | `ui`, `crashes` | Any `u16` |
79+
| `should-ice` | Check failure status is `101` | `coverage`, `incremental` | N/A |
80+
| `should-fail` | Compiletest self-test | All | N/A |
8181

8282
### Controlling output snapshots and normalizations
8383

8484
See [Normalization](ui.md#normalization), [Output
8585
comparison](ui.md#output-comparison) and [Rustfix tests](ui.md#rustfix-tests)
8686
for more details.
8787

88-
| Directive | Explanation | Supported test suites | Possible values |
89-
|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|-----------------------------------------------------------------------------------------|
90-
| `check-run-results` | Check run test binary `run-{pass,fail}` output snapshot | `ui`, `crashes`, `incremental`[^inc1] if `run-pass` | N/A |
91-
| `error-pattern` | Check that output contains a regex pattern | `ui`, `crashes`, `incremental`[^inc1] if `run-pass` | Regex |
92-
| `check-stdout` | Check `stdout` against `error-pattern`s from running test binary[^check_stdout] | `ui`, `crashes`, `incremental`[^inc1] | N/A |
93-
| `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 |
94-
| `normalize-stderr-32bit` | Normalize actual stderr (for 32-bit platforms) with a rule `"<raw>" -> "<normalized>"` before comparing against snapshot | `ui`, `incremental`[^inc1] | `"<RAW>" -> "<NORMALIZED>"`, `<RAW>`/`<NORMALIZED>` is regex capture and replace syntax |
95-
| `normalize-stderr-64bit` | Normalize actual stderr (for 64-bit platforms) with a rule `"<raw>" -> "<normalized>"` before comparing against snapshot | `ui`, `incremental`[^inc1] | `"<RAW>" -> "<NORMALIZED>"`, `<RAW>`/`<NORMALIZED>` is regex capture and replace syntax |
96-
| `normalize-stderr-test` | Normalize actual stderr with a rule `"<raw>" -> "<normalized>"` before comparing against snapshot | `ui`, `incremental`[^inc1] | `"<RAW>" -> "<NORMALIZED>"`, `<RAW>`/`<NORMALIZED>` is regex capture and replace syntax |
97-
| `normalize-stdout-test` | Normalize actual stdout with a rule `"<raw>" -> "<normalized>"` before comparing against snapshot | `ui`, `incremental`[^inc1] | `"<RAW>" -> "<NORMALIZED>"`, `<RAW>`/`<NORMALIZED>` is regex capture and replace syntax |
98-
| `dont-check-compiler-stderr` | Don't check actual compiler stderr vs stderr snapshot | `ui` | N/A |
99-
| `dont-check-compiler-stdout` | Don't check actual compiler stdout vs stdout snapshot | `ui` | N/A |
100-
| `run-rustfix` | Apply all suggestions via `rustfix`, snapshot fixed output, and check fixed output builds | `ui` | N/A |
101-
| `rustfix-only-machine-applicable` | `run-rustfix` but only machine-applicable suggestions | `ui` | N/A |
102-
| `exec-env` | Env var to set when executing a test | `ui`, `crashes` | `<KEY>=<VALUE>` |
103-
| `unset-exec-env` | Env var to unset when executing a test | `ui`, `crashes` | Any env var name |
104-
| `stderr-per-bitwidth` | Generate a stderr snapshot for each bitwidth | `ui` | N/A |
105-
| `forbid-output` | A pattern which must not appear in `cfail` output | `incremental` | Regex pattern |
106-
| `run-flags` | Flags passed to the test executable | `ui` | Arbitrary flags |
107-
| `known-bug` | No error annotation needed due to known bug | `ui`, `crashes`, `incremental` | Issue number `#123456` |
88+
| Directive | Explanation | Supported test suites | Possible values |
89+
|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------|----------------------------------------------|-----------------------------------------------------------------------------------------|
90+
| `check-run-results` | Check run test binary `run-{pass,fail}` output snapshot | `ui`, `crashes`, `incremental` if `run-pass` | N/A |
91+
| `error-pattern` | Check that output contains a regex pattern | `ui`, `crashes`, `incremental` if `run-pass` | Regex |
92+
| `check-stdout` | Check `stdout` against `error-pattern`s from running test binary[^check_stdout] | `ui`, `crashes`, `incremental` | N/A |
93+
| `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 |
94+
| `normalize-stderr-32bit` | Normalize actual stderr (for 32-bit platforms) with a rule `"<raw>" -> "<normalized>"` before comparing against snapshot | `ui`, `incremental` | `"<RAW>" -> "<NORMALIZED>"`, `<RAW>`/`<NORMALIZED>` is regex capture and replace syntax |
95+
| `normalize-stderr-64bit` | Normalize actual stderr (for 64-bit platforms) with a rule `"<raw>" -> "<normalized>"` before comparing against snapshot | `ui`, `incremental` | `"<RAW>" -> "<NORMALIZED>"`, `<RAW>`/`<NORMALIZED>` is regex capture and replace syntax |
96+
| `normalize-stderr-test` | Normalize actual stderr with a rule `"<raw>" -> "<normalized>"` before comparing against snapshot | `ui`, `incremental` | `"<RAW>" -> "<NORMALIZED>"`, `<RAW>`/`<NORMALIZED>` is regex capture and replace syntax |
97+
| `normalize-stdout-test` | Normalize actual stdout with a rule `"<raw>" -> "<normalized>"` before comparing against snapshot | `ui`, `incremental` | `"<RAW>" -> "<NORMALIZED>"`, `<RAW>`/`<NORMALIZED>` is regex capture and replace syntax |
98+
| `dont-check-compiler-stderr` | Don't check actual compiler stderr vs stderr snapshot | `ui` | N/A |
99+
| `dont-check-compiler-stdout` | Don't check actual compiler stdout vs stdout snapshot | `ui` | N/A |
100+
| `run-rustfix` | Apply all suggestions via `rustfix`, snapshot fixed output, and check fixed output builds | `ui` | N/A |
101+
| `rustfix-only-machine-applicable` | `run-rustfix` but only machine-applicable suggestions | `ui` | N/A |
102+
| `exec-env` | Env var to set when executing a test | `ui`, `crashes` | `<KEY>=<VALUE>` |
103+
| `unset-exec-env` | Env var to unset when executing a test | `ui`, `crashes` | Any env var name |
104+
| `stderr-per-bitwidth` | Generate a stderr snapshot for each bitwidth | `ui` | N/A |
105+
| `forbid-output` | A pattern which must not appear in `cfail` output | `incremental` | Regex pattern |
106+
| `run-flags` | Flags passed to the test executable | `ui` | Arbitrary flags |
107+
| `known-bug` | No error annotation needed due to known bug | `ui`, `crashes`, `incremental` | Issue number `#123456` |
108108

109109
[^check_stdout]: presently <!-- date-check: Oct 2024 --> this has a weird quirk
110110
where the test binary's stdout and stderr gets concatenated and then

‎src/tests/minicore.md

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# `minicore` test auxiliary: using `core` stubs
2+
3+
<!-- date-check Oct 2024 -->
4+
5+
[`tests/auxiliary/minicore.rs`][`minicore`] is a test auxiliary for
6+
ui/codegen/assembly test suites. It provides `core` stubs for tests that need to
7+
build for cross-compiled targets but do not need/want to run.
8+
9+
A test can use [`minicore`] by specifying the `//@ add-core-stubs` directive.
10+
Then, mark the test with `#![feature(no_core)]` + `#![no_std]` + `#![no_core]`.
11+
Due to Edition 2015 extern prelude rules, you will probably need to declare
12+
`minicore` as an extern crate.
13+
14+
Due to the `no_std` + `no_core` nature of these tests, `//@ add-core-stubs`
15+
implies and requires that the test will be built with `-C panic=abort`.
16+
Unwinding panics are not supported.
17+
18+
If you find a `core` item to be missing from the [`minicore`] stub, consider
19+
adding it to the test auxiliary if it's likely to be used or is already needed
20+
by more than one test.
21+
22+
<div class="warning">
23+
Please note that [`minicore`] is only intended for `core` items, and explicitly
24+
**not** `std` or `alloc` items because `core` items are applicable to a wider
25+
range of tests.
26+
</div>
27+
28+
## Example codegen test that uses `minicore`
29+
30+
```rust,no_run
31+
//@ add-core-stubs
32+
//@ revisions: meow bark
33+
//@[meow] compile-flags: --target=x86_64-unknown-linux-gnu
34+
//@[meow] needs-llvm-components: x86
35+
//@[bark] compile-flags: --target=wasm32-unknown-unknown
36+
//@[bark] needs-llvm-components: webassembly
37+
38+
#![crate_type = "lib"]
39+
#![feature(no_core)]
40+
#![no_std]
41+
#![no_core]
42+
43+
extern crate minicore;
44+
use minicore::*;
45+
46+
struct Meow;
47+
impl Copy for Meow {} // `Copy` here is provided by `minicore`
48+
49+
// CHECK-LABEL: meow
50+
#[unsafe(no_mangle)]
51+
fn meow() {}
52+
```
53+
54+
[minicore]: https://github.com/rust-lang/rust/tree/master/tests/auxiliary/minicore.rs

‎src/tests/ui.md

+3
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@ used for many other purposes. For example, tests can also be configured to [run
1313
the resulting program](#controlling-passfail-expectations) to verify its
1414
behavior.
1515

16+
If you need to work with `#![no_std]` cross-compiling tests, consult the
17+
[`minicore` test auxiliary](./minicore.md) chapter.
18+
1619
[`tests/ui`]: https://github.com/rust-lang/rust/blob/master/tests/ui
1720

1821
## General structure of a test

0 commit comments

Comments
 (0)