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. + +