From 126482334fe2774c2052c46fc2c49da8fbf979cd Mon Sep 17 00:00:00 2001
From: Jiahao XU <30436523+NobodyXu@users.noreply.github.com>
Date: Mon, 30 Sep 2024 00:20:40 +1000
Subject: [PATCH] Update doc for detecting changes/upgrades of compilers

---
 src/lib.rs | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/src/lib.rs b/src/lib.rs
index 98556981..cf6072df 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1269,6 +1269,17 @@ impl Build {
     /// Define whether metadata should be emitted for cargo to detect environment
     /// changes that should trigger a rebuild.
     ///
+    /// NOTE that cc does not emit metadata to detect changes for `PATH`, since it could
+    /// be changed every comilation yet does not affect the result of compilation
+    /// (i.e. rust-analyzer adds temporary directory to `PATH`).
+    ///
+    /// cc in general, has no way detecting changes to compiler, as there are so many ways to
+    /// change it and sidestep the detection, for example the compiler might be wrapped in a script
+    /// so detecting change of the file, or using checksum won't work.
+    ///
+    /// We recommend users to decide for themselves, if they want rebuild if the compiler has been upgraded
+    /// or changed, and how to detect that.
+    ///
     /// This has no effect if the `cargo_metadata` option is `false`.
     ///
     /// This option defaults to `true`.