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`

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:

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:

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:

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
 

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
 

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
 

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
 

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
 

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
 

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
 

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
 

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
 

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

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

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:

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
 

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
 

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
 

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
 

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

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
 

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:

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)