diff --git a/src/SUMMARY.md b/src/SUMMARY.md index aa18f5e94..20bba6806 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 efb48900d..dc886e252 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..40afe70de --- /dev/null +++ b/src/tests/minicore.md @@ -0,0 +1,54 @@ +# `minicore` test auxiliary: using `core` stubs + + + +[`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 `//@ add-core-stubs` 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, `//@ add-core-stubs` +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 if it's likely to be used or is already needed +by more than one test. + +
+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 +//@ add-core-stubs +//@ revisions: meow bark +//@[meow] compile-flags: --target=x86_64-unknown-linux-gnu +//@[meow] needs-llvm-components: x86 +//@[bark] compile-flags: --target=wasm32-unknown-unknown +//@[bark] needs-llvm-components: webassembly + +#![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 +#[unsafe(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