Auto merge of #124847 - Oneirical:master, r=jieyouxu

Document tests in the `run-make` directory (A to C)

Part of the #121876 project.

This PR adds comments to some `run-make` tests which lack one, explaining _what_ is being tested. If possible, a link to the relevant PR or Issue responsible for the test is also provided.

This will help the porting efforts to `rmake.rs`, and will also allow maintainers to focus efforts on tests which are more pertinent to port. For example, [this test](https://github.com/rust-lang/rust/blob/master/tests/run-make/cat-and-grep-sanity-check/Makefile) will become useless after all tests containing `CGREP` are successfully ported.

In order to simplify review and at the suggestion of Kobzol on the rust-lang #gsoc Zulip, only the first 23 comments are part of this PR. If it is merged, future PRs will ensue commenting the rest of the tests.

Could be an UI test:

- `dep-info-doesnt-run-much`

23 files changed, 70 insertions, 0 deletions

diff --git a/tests/run-make/alloc-no-oom-handling/Makefile b/tests/run-make/alloc-no-oom-handling/Makefile
index 87f74c69c79..7c3ae90b58d 100644
--- a/tests/run-make/alloc-no-oom-handling/Makefile
+++ b/tests/run-make/alloc-no-oom-handling/Makefile
@@ -1,3 +1,6 @@
+# This test checks that alloc can still compile correctly when the unstable no_global_oom_handling feature is turned on.
+# See https://github.com/rust-lang/rust/pull/84266
+
 include ../tools.mk
 
 all:
diff --git a/tests/run-make/alloc-no-rc/Makefile b/tests/run-make/alloc-no-rc/Makefile
index 9824b17e6c2..fcfe1603b6c 100644
--- a/tests/run-make/alloc-no-rc/Makefile
+++ b/tests/run-make/alloc-no-rc/Makefile
@@ -1,3 +1,6 @@
+# This test checks that alloc can still compile correctly when the unstable no_rc feature is turned on.
+# See https://github.com/rust-lang/rust/pull/89891
+
 include ../tools.mk
 
 all:
diff --git a/tests/run-make/alloc-no-sync/Makefile b/tests/run-make/alloc-no-sync/Makefile
index 04ec4c7d8bc..997dbcf6603 100644
--- a/tests/run-make/alloc-no-sync/Makefile
+++ b/tests/run-make/alloc-no-sync/Makefile
@@ -1,3 +1,6 @@
+# This test checks that alloc can still compile correctly when the unstable no_sync feature is turned on.
+# See https://github.com/rust-lang/rust/pull/89891
+
 include ../tools.mk
 
 all:
diff --git a/tests/run-make/allocator-shim-circular-deps/Makefile b/tests/run-make/allocator-shim-circular-deps/Makefile
index 4624b846803..f667e2e2ec2 100644
--- a/tests/run-make/allocator-shim-circular-deps/Makefile
+++ b/tests/run-make/allocator-shim-circular-deps/Makefile
@@ -1,3 +1,8 @@
+# This test is designed to intentionally introduce a circular dependency scenario to check that a specific compiler bug doesn't make a resurgence.
+# The bug in question arose when at least one crate required a global allocator, and that crate was placed after the one defining it in the linker order. 
+# The generated symbols.o should not result in any linker errors.
+# See https://github.com/rust-lang/rust/issues/112715
+
 # ignore-cross-compile
 include ../tools.mk
 
diff --git a/tests/run-make/archive-duplicate-names/Makefile b/tests/run-make/archive-duplicate-names/Makefile
index 5433a42d252..207eee39299 100644
--- a/tests/run-make/archive-duplicate-names/Makefile
+++ b/tests/run-make/archive-duplicate-names/Makefile
@@ -1,3 +1,7 @@
+# When two object archives with the same filename are present, an iterator is supposed to inspect each object, recognize the duplication and extract each one to a different directory.
+# This test checks that this duplicate handling behaviour has not been broken.
+# See https://github.com/rust-lang/rust/pull/24439
+
 # ignore-cross-compile
 include ../tools.mk
 
diff --git a/tests/run-make/bare-outfile/Makefile b/tests/run-make/bare-outfile/Makefile
index 23b619ea0ba..ad6fe4bd167 100644
--- a/tests/run-make/bare-outfile/Makefile
+++ b/tests/run-make/bare-outfile/Makefile
@@ -1,3 +1,5 @@
+# This test checks that manually setting the output file as a bare file with no file extension still results in successful compilation.
+
 # ignore-cross-compile
 include ../tools.mk
 
diff --git a/tests/run-make/c-dynamic-dylib/Makefile b/tests/run-make/c-dynamic-dylib/Makefile
index b5bfbc76539..0d409640486 100644
--- a/tests/run-make/c-dynamic-dylib/Makefile
+++ b/tests/run-make/c-dynamic-dylib/Makefile
@@ -1,3 +1,6 @@
+# This test checks that dynamic Rust linking with C does not encounter any errors, with dynamic dependencies given preference over static.
+# See https://github.com/rust-lang/rust/issues/10434
+
 # ignore-cross-compile
 include ../tools.mk
 
diff --git a/tests/run-make/c-dynamic-rlib/Makefile b/tests/run-make/c-dynamic-rlib/Makefile
index 0475bd8acae..a64e89cc0dc 100644
--- a/tests/run-make/c-dynamic-rlib/Makefile
+++ b/tests/run-make/c-dynamic-rlib/Makefile
@@ -1,3 +1,6 @@
+# This test checks that dynamic Rust linking with C does not encounter any errors, with static dependencies given preference over dynamic. (This is the default behaviour.)
+# See https://github.com/rust-lang/rust/issues/10434
+
 # ignore-cross-compile
 include ../tools.mk
 
diff --git a/tests/run-make/c-link-to-rust-dylib/Makefile b/tests/run-make/c-link-to-rust-dylib/Makefile
index 2763cb6ed1d..201f717ece4 100644
--- a/tests/run-make/c-link-to-rust-dylib/Makefile
+++ b/tests/run-make/c-link-to-rust-dylib/Makefile
@@ -1,3 +1,6 @@
+# This test checks that C linking with Rust does not encounter any errors, with dynamic libraries.
+# See https://github.com/rust-lang/rust/issues/10434
+
 # ignore-cross-compile
 include ../tools.mk
 
diff --git a/tests/run-make/c-link-to-rust-staticlib/Makefile b/tests/run-make/c-link-to-rust-staticlib/Makefile
index e14775f5c18..d36cc421c46 100644
--- a/tests/run-make/c-link-to-rust-staticlib/Makefile
+++ b/tests/run-make/c-link-to-rust-staticlib/Makefile
@@ -1,3 +1,6 @@
+# This test checks that C linking with Rust does not encounter any errors, with static libraries.
+# See https://github.com/rust-lang/rust/issues/10434
+
 # ignore-cross-compile
 include ../tools.mk
 
diff --git a/tests/run-make/c-static-dylib/Makefile b/tests/run-make/c-static-dylib/Makefile
index 4e23edb6c57..05da1743c83 100644
--- a/tests/run-make/c-static-dylib/Makefile
+++ b/tests/run-make/c-static-dylib/Makefile
@@ -1,3 +1,6 @@
+# This test checks that static Rust linking with C does not encounter any errors, with dynamic dependencies given preference over static.
+# See https://github.com/rust-lang/rust/issues/10434
+
 # ignore-cross-compile
 include ../tools.mk
 
diff --git a/tests/run-make/c-static-rlib/Makefile b/tests/run-make/c-static-rlib/Makefile
index 4e351127cb6..298e432cdb8 100644
--- a/tests/run-make/c-static-rlib/Makefile
+++ b/tests/run-make/c-static-rlib/Makefile
@@ -1,3 +1,6 @@
+# This test checks that static Rust linking with C does not encounter any errors, with static dependencies given preference over dynamic. (This is the default behaviour.)
+# See https://github.com/rust-lang/rust/issues/10434
+
 # ignore-cross-compile
 include ../tools.mk
 
diff --git a/tests/run-make/c-unwind-abi-catch-lib-panic/Makefile b/tests/run-make/c-unwind-abi-catch-lib-panic/Makefile
index b8e0e9483cd..2bb8d42495d 100644
--- a/tests/run-make/c-unwind-abi-catch-lib-panic/Makefile
+++ b/tests/run-make/c-unwind-abi-catch-lib-panic/Makefile
@@ -1,3 +1,6 @@
+# Exercise unwinding a panic. This catches a panic across an FFI boundary and downcasts it into an integer. The Rust code that panics is in a separate crate.
+# See https://github.com/rust-lang/rust/commit/baf227ea0c1e07fc54395a51e4b3881d701180cb
+
 # ignore-cross-compile
 # needs-unwind
 include ../tools.mk
diff --git a/tests/run-make/c-unwind-abi-catch-panic/Makefile b/tests/run-make/c-unwind-abi-catch-panic/Makefile
index 1760ddb3061..0a38d838e32 100644
--- a/tests/run-make/c-unwind-abi-catch-panic/Makefile
+++ b/tests/run-make/c-unwind-abi-catch-panic/Makefile
@@ -1,3 +1,6 @@
+# Exercise unwinding a panic. This catches a panic across an FFI boundary and downcasts it into an integer. The Rust code that panics is in the same directory.
+# See https://github.com/rust-lang/rust/commit/baf227ea0c1e07fc54395a51e4b3881d701180cb
+
 # ignore-cross-compile
 # needs-unwind
 include ../tools.mk
diff --git a/tests/run-make/cat-and-grep-sanity-check/Makefile b/tests/run-make/cat-and-grep-sanity-check/Makefile
index 82351e22009..8ee69c0a0de 100644
--- a/tests/run-make/cat-and-grep-sanity-check/Makefile
+++ b/tests/run-make/cat-and-grep-sanity-check/Makefile
@@ -1,3 +1,7 @@
+# grep in run-make tests was partially replaced with a custom script, CGREP. This tests that CGREP does its job correctly.
+# See https://github.com/rust-lang/rust/commit/ab788a2ee175c7560f0ca58bbc183ecfd57d2f7a
+# FIXME(Oneirical): Note that this test will likely become useless after the port to rmake.rs tests (see https://github.com/rust-lang/rust/issues/121876)
+
 include ../tools.mk
 
 all:
diff --git a/tests/run-make/cdylib-dylib-linkage/Makefile b/tests/run-make/cdylib-dylib-linkage/Makefile
index 51fbfef2d85..db8393d3c05 100644
--- a/tests/run-make/cdylib-dylib-linkage/Makefile
+++ b/tests/run-make/cdylib-dylib-linkage/Makefile
@@ -1,3 +1,6 @@
+# This test checks that cdylibs can link against dylibs as dependencies, after this restriction was disabled.
+# See https://github.com/rust-lang/rust/commit/72aaa3a414d17aa0c4f19feafa5bab5f84b60e63
+
 # ignore-cross-compile
 include ../tools.mk
 
diff --git a/tests/run-make/cdylib-fewer-symbols/Makefile b/tests/run-make/cdylib-fewer-symbols/Makefile
index 4e08f979c36..d587cece5be 100644
--- a/tests/run-make/cdylib-fewer-symbols/Makefile
+++ b/tests/run-make/cdylib-fewer-symbols/Makefile
@@ -1,6 +1,8 @@
 # ignore-cross-compile
+
 # Test that allocator-related symbols don't show up as exported from a cdylib as
 # they're internal to Rust and not part of the public ABI.
+# See https://github.com/rust-lang/rust/commit/fbf98697021173a30b84d9145df0966a23a2f9d2
 
 include ../tools.mk
 
diff --git a/tests/run-make/cdylib/Makefile b/tests/run-make/cdylib/Makefile
index 3c8b5269554..2c6414c3255 100644
--- a/tests/run-make/cdylib/Makefile
+++ b/tests/run-make/cdylib/Makefile
@@ -1,3 +1,6 @@
+# When the cdylib crate type was added as a variation of dylib, it needed a test to check its function.
+# See https://github.com/rust-lang/rust/pull/33553
+
 # ignore-cross-compile
 include ../tools.mk
 
diff --git a/tests/run-make/codegen-options-parsing/Makefile b/tests/run-make/codegen-options-parsing/Makefile
index 56bb900b7d8..beaf233502b 100644
--- a/tests/run-make/codegen-options-parsing/Makefile
+++ b/tests/run-make/codegen-options-parsing/Makefile
@@ -1,3 +1,5 @@
+# This test intentionally feeds invalid inputs to codegen and checks if the error message outputs contain specific helpful indications.
+
 # ignore-cross-compile
 include ../tools.mk
 
diff --git a/tests/run-make/comment-section/Makefile b/tests/run-make/comment-section/Makefile
index 9f810063cc8..d0b98176ffe 100644
--- a/tests/run-make/comment-section/Makefile
+++ b/tests/run-make/comment-section/Makefile
@@ -1,3 +1,6 @@
+# Both GCC and Clang write by default a `.comment` section with compiler information. Rustc received a similar .comment section, so this tests checks that this section properly appears.
+# See https://github.com/rust-lang/rust/commit/74b8d324eb77a8f337b35dc68ac91b0c2c06debc
+
 include ../tools.mk
 
 # only-linux
diff --git a/tests/run-make/compile-stdin/Makefile b/tests/run-make/compile-stdin/Makefile
index 2a495281c24..b3d7cc777a0 100644
--- a/tests/run-make/compile-stdin/Makefile
+++ b/tests/run-make/compile-stdin/Makefile
@@ -1,3 +1,6 @@
+# When provided standard input piped directly into rustc, this test checks that the compilation completes successfully and that the output can be executed.
+# See https://github.com/rust-lang/rust/pull/28805
+
 # ignore-cross-compile
 include ../tools.mk
 
diff --git a/tests/run-make/compiler-lookup-paths-2/Makefile b/tests/run-make/compiler-lookup-paths-2/Makefile
index d4ff7d8daab..ecc0577384a 100644
--- a/tests/run-make/compiler-lookup-paths-2/Makefile
+++ b/tests/run-make/compiler-lookup-paths-2/Makefile
@@ -1,3 +1,6 @@
+# This test checks that extern crate declarations in Cargo without a corresponding declaration in the manifest of a dependency are NOT allowed.
+# See https://github.com/rust-lang/rust/pull/21113
+
 include ../tools.mk
 
 all:
diff --git a/tests/run-make/compiler-lookup-paths/Makefile b/tests/run-make/compiler-lookup-paths/Makefile
index 310d6772c34..fc0cbde4c35 100644
--- a/tests/run-make/compiler-lookup-paths/Makefile
+++ b/tests/run-make/compiler-lookup-paths/Makefile
@@ -1,3 +1,6 @@
+# rustc supports different types of lookup paths, such as dependency, native or crate. This test checks that these lookup paths are functional and result in functional compilation.
+# See https://github.com/rust-lang/rust/pull/19941
+
 include ../tools.mk
 
 # ignore-wasm32 (need a C compiler)