fix(fingerprint): clean doc dirs for only requested targets

Previously if rustc version mismatches,
this removes all `doc` directories including target platforms that are
not part of the build.

This makes it `--target` aware and stops excessive cleanup,
by putting `.rustdoc_fingerprint.json` in each target directory.

Author: weihanglo

src/cargo/core/compiler/fingerprint/rustdoc.rs

@@ -7,6 +7,7 @@ use serde::Serialize;
 
 use crate::CargoResult;
 use crate::core::compiler::BuildRunner;
+use crate::core::compiler::CompileKind;
 
 /// Structure used to deal with Rustdoc fingerprinting
 ///
@@ -30,10 +31,17 @@ impl RustDocFingerprint {
     /// was the same as the one is currently being used in this `cargo doc` call.
     ///
     /// In case it's not,
-    /// it takes care of removing the `<artifact-dir>/doc/` folder
+    /// it takes care of removing the `<build-dir>/doc/` folder
     /// as well as overwriting the rustdoc fingerprint info.
     /// This is to guarantee that we won't end up with mixed versions of the `js/html/css` files
     /// which `rustdoc` autogenerates without any versioning.
+    ///
+    /// Each requested target platform maintains its own fingerprint file.
+    /// That is, if you run `cargo doc` and then `cargo doc --target wasm32-wasip1`,
+    /// you will have two separate fingerprint files:
+    ///
+    /// * `<build-dir>/.rustdoc_fingerprint.json` for host
+    /// * `<build-dir>/wasm32-wasip1/.rustdoc_fingerprint.json`
     pub fn check_rustdoc_fingerprint(build_runner: &BuildRunner<'_, '_>) -> CargoResult<()> {
         if build_runner
             .bcx
@@ -43,68 +51,79 @@ impl RustDocFingerprint {
         {
             return Ok(());
         }
-        let actual_rustdoc_target_data = RustDocFingerprint {
+        let new_fingerprint = RustDocFingerprint {
             rustc_vv: build_runner.bcx.rustc().verbose_version.clone(),
         };
 
-        let fingerprint_path = build_runner
-            .files()
-            .host_build_root()
-            .join(".rustdoc_fingerprint.json");
-        let write_fingerprint = || -> CargoResult<()> {
-            paths::write(
-                &fingerprint_path,
-                serde_json::to_string(&actual_rustdoc_target_data)?,
-            )
-        };
-        let Ok(rustdoc_data) = paths::read(&fingerprint_path) else {
-            // If the fingerprint does not exist, do not clear out the doc
-            // directories. Otherwise this ran into problems where projects
-            // like bootstrap were creating the doc directory before running
-            // `cargo doc` in a way that deleting it would break it.
-            return write_fingerprint();
-        };
-        match serde_json::from_str::<RustDocFingerprint>(&rustdoc_data) {
-            Ok(fingerprint) => {
-                if fingerprint.rustc_vv == actual_rustdoc_target_data.rustc_vv {
-                    return Ok(());
-                } else {
-                    tracing::debug!(
-                        "doc fingerprint changed:\noriginal:\n{}\nnew:\n{}",
-                        fingerprint.rustc_vv,
-                        actual_rustdoc_target_data.rustc_vv
-                    );
-                }
-            }
-            Err(e) => {
-                tracing::debug!("could not deserialize {:?}: {}", fingerprint_path, e);
-            }
-        };
-        // Fingerprint does not match, delete the doc directories and write a new fingerprint.
-        tracing::debug!(
-            "fingerprint {:?} mismatch, clearing doc directories",
-            fingerprint_path
-        );
-        build_runner
-            .bcx
-            .all_kinds
-            .iter()
-            .map(|kind| {
-                build_runner
-                    .files()
-                    .layout(*kind)
-                    .artifact_dir()
-                    .expect("artifact-dir was not locked")
-                    .doc()
-            })
-            .filter(|path| path.exists())
-            .try_for_each(|path| clean_doc(path))?;
-        write_fingerprint()?;
+        for kind in &build_runner.bcx.build_config.requested_kinds {
+            check_fingerprint(build_runner, &new_fingerprint, *kind)?;
+        }
 
         Ok(())
     }
 }
 
+/// Checks rustdoc fingerprint file for a given [`CompileKind`].
+fn check_fingerprint(
+    build_runner: &BuildRunner<'_, '_>,
+    new_fingerprint: &RustDocFingerprint,
+    kind: CompileKind,
+) -> CargoResult<()> {
+    let fingerprint_path = build_runner
+        .files()
+        .layout(kind)
+        .build_dir()
+        .root()
+        .join(".rustdoc_fingerprint.json");
+
+    let write_fingerprint = || -> CargoResult<()> {
+        paths::write(&fingerprint_path, serde_json::to_string(new_fingerprint)?)
+    };
+
+    let Ok(rustdoc_data) = paths::read(&fingerprint_path) else {
+        // If the fingerprint does not exist, do not clear out the doc
+        // directories. Otherwise this ran into problems where projects
+        // like bootstrap were creating the doc directory before running
+        // `cargo doc` in a way that deleting it would break it.
+        return write_fingerprint();
+    };
+
+    match serde_json::from_str::<RustDocFingerprint>(&rustdoc_data) {
+        Ok(on_disk_fingerprint) => {
+            if on_disk_fingerprint.rustc_vv == new_fingerprint.rustc_vv {
+                return Ok(());
+            } else {
+                tracing::debug!(
+                    "doc fingerprint changed:\noriginal:\n{}\nnew:\n{}",
+                    on_disk_fingerprint.rustc_vv,
+                    new_fingerprint.rustc_vv
+                );
+            }
+        }
+        Err(e) => {
+            tracing::debug!("could not deserialize {:?}: {}", fingerprint_path, e);
+        }
+    };
+    // Fingerprint does not match, delete the doc directories and write a new fingerprint.
+    tracing::debug!(
+        "fingerprint {:?} mismatch, clearing doc directories",
+        fingerprint_path
+    );
+    let doc_dir = build_runner
+        .files()
+        .layout(kind)
+        .artifact_dir()
+        .expect("artifact-dir was not locked")
+        .doc();
+    if doc_dir.exists() {
+        clean_doc(doc_dir)?;
+    }
+
+    write_fingerprint()?;
+
+    Ok(())
+}
+
 fn clean_doc(path: &Path) -> CargoResult<()> {
     let entries = path
         .read_dir()

tests/testsuite/doc.rs

@@ -2586,7 +2586,11 @@ LLVM version: 9.0
         serde_json::from_str(&fs::read_to_string(&host_fingerprint_path).unwrap())
             .expect("JSON Serde fail");
 
-    assert!(!target_fingerprint_path.exists());
+    let target_fingerprint: RustDocFingerprint =
+        serde_json::from_str(&fs::read_to_string(&target_fingerprint_path).unwrap())
+            .expect("JSON Serde fail");
+
+    assert_eq!(host_fingerprint.rustc_vv, target_fingerprint.rustc_vv);
 
     // Check that the fingerprint contains the actual rustc version
     // which has been used to compile the docs.
@@ -2600,8 +2604,14 @@ LLVM version: 9.0
     .unwrap();
     assert_eq!(&host_fingerprint.rustc_vv, &current_rustc_version);
 
-    // Write random `rustc -vV` output and bogus file for host
+    // Write random `rustc -vV` output and bogus file for both host and target
     fs::write(&host_fingerprint_path, &old_rustc_verbose_version).unwrap();
+    fs::write(&target_fingerprint_path, &old_rustc_verbose_version).unwrap();
+    fs::write(
+        p.build_dir().join(host).join("doc/bogus_file"),
+        "This is a bogus file and should be removed!",
+    )
+    .unwrap();
     fs::write(
         p.build_dir().join("doc/bogus_file"),
         "This is a bogus file and should be removed!",
@@ -2611,10 +2621,17 @@ LLVM version: 9.0
     // ...but run only target
     p.cargo("doc --target").arg(host).run();
 
-    // host doc dir got cleaned
-    assert!(!p.build_dir().join("doc/bogus_file").exists());
+    // host doc dir stays the same, and the fingerprint is still the old random one
+    assert!(p.build_dir().join("doc/bogus_file").exists());
+    assert_eq!(
+        &fs::read_to_string(&host_fingerprint_path).unwrap(),
+        &old_rustc_verbose_version,
+    );
+
+    // target doc dir got cleaned
+    assert!(!p.build_dir().join(host).join("doc/bogus_file").exists());
     let fingerprint: RustDocFingerprint =
-        serde_json::from_str(&fs::read_to_string(&host_fingerprint_path).unwrap()).unwrap();
+        serde_json::from_str(&fs::read_to_string(&target_fingerprint_path).unwrap()).unwrap();
     assert_eq!(&fingerprint.rustc_vv, &current_rustc_version);
 }