From 2f2ce28b182ba90d22cb5fa9931a044d28860636 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] Describe `minicore` test auxiliary and directive

---
 src/SUMMARY.md           |  1 +
 src/tests/compiletest.md |  6 ++++++
 src/tests/minicore.md    | 41 ++++++++++++++++++++++++++++++++++++++++
 src/tests/ui.md          |  3 +++
 4 files changed, 51 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..a98929131
--- /dev/null
+++ b/src/tests/minicore.md
@@ -0,0 +1,41 @@
+# `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.
+
+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