Update Makefiles with explanatory comments

23 files changed, 67 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..2f053f4025b 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 verifies that the Rust compiler can still compile correctly when the unstable no_global_oom_handling feature is turned on, which disables global error handling in alloc.
+# 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..f7422dec3a5 100644
--- a/tests/run-make/alloc-no-rc/Makefile
+++ b/tests/run-make/alloc-no-rc/Makefile
@@ -1,3 +1,6 @@
+# This test verifies that the Rust compiler can still compile correctly when the unstable no_rc feature is turned on, which disables rc in alloc.
+# 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..16db6404fa2 100644
--- a/tests/run-make/alloc-no-sync/Makefile
+++ b/tests/run-make/alloc-no-sync/Makefile
@@ -1,3 +1,6 @@
+# This test verifies that the Rust compiler can still compile correctly when the unstable no_sync feature is turned on, which disables sync in alloc.
+# 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..04531503eab 100644
--- a/tests/run-make/allocator-shim-circular-deps/Makefile
+++ b/tests/run-make/allocator-shim-circular-deps/Makefile
@@ -1,3 +1,6 @@
+# This test intentionally creates a circular dependency, and checks if this causes the resurgence of the compiler bug linked below.
+# 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..a9a3373ac56 100644
--- a/tests/run-make/archive-duplicate-names/Makefile
+++ b/tests/run-make/archive-duplicate-names/Makefile
@@ -1,3 +1,6 @@
+# This test reads two object archives with the same filename, and extracts each one to a unique location. This checks that the functionality of the linked PR is preserved.
+# 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..d99634ba09a 100644
--- a/tests/run-make/c-dynamic-dylib/Makefile
+++ b/tests/run-make/c-dynamic-dylib/Makefile
@@ -1,3 +1,6 @@
+# This test verifies 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..8e510dc3cdb 100644
--- a/tests/run-make/c-dynamic-rlib/Makefile
+++ b/tests/run-make/c-dynamic-rlib/Makefile
@@ -1,3 +1,6 @@
+# This test verifies 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..79b23eb3791 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 verifies 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..71a632800d0 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 verifies 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..b808f465217 100644
--- a/tests/run-make/c-static-dylib/Makefile
+++ b/tests/run-make/c-static-dylib/Makefile
@@ -1,3 +1,6 @@
+# This test verifies 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..18a6b2bee07 100644
--- a/tests/run-make/c-static-rlib/Makefile
+++ b/tests/run-make/c-static-rlib/Makefile
@@ -1,3 +1,6 @@
+# This test verifies 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..327c5354849 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
+# 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..9038941504b 100644
--- a/tests/run-make/cdylib-dylib-linkage/Makefile
+++ b/tests/run-make/cdylib-dylib-linkage/Makefile
@@ -1,3 +1,6 @@
+# This test verifies 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..47a870ef087 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 verify 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..c4029f29d28 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 the expected strings.
+
 # 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..b325b6a6f87 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 verifies 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..1ad0e24b0eb 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 verifies 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)