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

### What does this PR try to resolve?

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

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

### How to test and review this PR?

I'd like to reuse this file to track doc parts directories in
<#16309>,
and noticed that this file is for the entire workspace rather than
per-target,
hich is not compatible with mergeable cross-crate info JSONs.

For concurrent safety,
`build-dir` should be locked already since Cargo locks every intent
except check (see <#16307>).
This file is touched only under `UserIntent::Doc`.

Author: epage

src/cargo/core/compiler/build_context/mod.rs

@@ -13,9 +13,10 @@ use crate::util::logger::BuildLogger;
 use std::collections::{HashMap, HashSet};
 
 mod target_info;
-pub use self::target_info::{
-    FileFlavor, FileType, RustDocFingerprint, RustcTargetData, TargetInfo,
-};
+pub use self::target_info::FileFlavor;
+pub use self::target_info::FileType;
+pub use self::target_info::RustcTargetData;
+pub use self::target_info::TargetInfo;
 
 /// The build context, containing complete information needed for a build task
 /// before it gets started.

src/cargo/core/compiler/build_context/target_info.rs

@@ -7,19 +7,24 @@
 //! * [`RustcTargetData::info`] to get a [`TargetInfo`] for an in-depth query.
 //! * [`TargetInfo::rustc_outputs`] to get a list of supported file types.
 
+use crate::core::compiler::CompileKind;
+use crate::core::compiler::CompileMode;
+use crate::core::compiler::CompileTarget;
+use crate::core::compiler::CrateType;
 use crate::core::compiler::apply_env_config;
-use crate::core::compiler::{BuildRunner, CompileKind, CompileMode, CompileTarget, CrateType};
 use crate::core::{Dependency, Package, Target, TargetKind, Workspace};
 use crate::util::context::{GlobalContext, StringList, TargetConfig};
 use crate::util::interning::InternedString;
 use crate::util::{CargoResult, Rustc};
+
 use anyhow::Context as _;
 use cargo_platform::{Cfg, CfgExpr};
-use cargo_util::{ProcessBuilder, paths};
-use serde::{Deserialize, Serialize};
+use cargo_util::ProcessBuilder;
+use serde::Deserialize;
+
 use std::cell::RefCell;
 use std::collections::hash_map::{Entry, HashMap};
-use std::path::{Path, PathBuf};
+use std::path::PathBuf;
 use std::rc::Rc;
 use std::str::{self, FromStr};
 
@@ -1110,113 +1115,3 @@ impl<'gctx> RustcTargetData<'gctx> {
         &self.requested_kinds
     }
 }
-
-/// Structure used to deal with Rustdoc fingerprinting
-#[derive(Debug, Serialize, Deserialize)]
-pub struct RustDocFingerprint {
-    pub rustc_vv: String,
-}
-
-impl RustDocFingerprint {
-    /// This function checks whether the latest version of `Rustc` used to compile this
-    /// `Workspace`'s docs 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 `doc/` folder as well as overwriting
-    /// the rustdoc fingerprint info in order to guarantee that we won't end up with mixed
-    /// versions of the `js/html/css` files that `rustdoc` autogenerates which do not have
-    /// any versioning.
-    pub fn check_rustdoc_fingerprint(build_runner: &BuildRunner<'_, '_>) -> CargoResult<()> {
-        if build_runner
-            .bcx
-            .gctx
-            .cli_unstable()
-            .skip_rustdoc_fingerprint
-        {
-            return Ok(());
-        }
-        let actual_rustdoc_target_data = 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()?;
-        return Ok(());
-
-        fn clean_doc(path: &Path) -> CargoResult<()> {
-            let entries = path
-                .read_dir()
-                .with_context(|| format!("failed to read directory `{}`", path.display()))?;
-            for entry in entries {
-                let entry = entry?;
-                // Don't remove hidden files. Rustdoc does not create them,
-                // but the user might have.
-                if entry
-                    .file_name()
-                    .to_str()
-                    .map_or(false, |name| name.starts_with('.'))
-                {
-                    continue;
-                }
-                let path = entry.path();
-                if entry.file_type()?.is_dir() {
-                    paths::remove_dir_all(path)?;
-                } else {
-                    paths::remove_file(path)?;
-                }
-            }
-            Ok(())
-        }
-    }
-}

src/cargo/core/compiler/build_runner/mod.rs

@@ -174,14 +174,9 @@ impl<'a, 'gctx> BuildRunner<'a, 'gctx> {
         self.check_collisions()?;
         self.compute_metadata_for_doc_units();
 
-        // We need to make sure that if there were any previous docs
-        // already compiled, they were compiled with the same Rustc version that we're currently
-        // using. Otherwise we must remove the `doc/` folder and compile again forcing a rebuild.
-        //
-        // This is important because the `.js`/`.html` & `.css` files that are generated by Rustc don't have
-        // any versioning (See https://github.com/rust-lang/cargo/issues/8461).
-        // Therefore, we can end up with weird bugs and behaviours if we mix different
-        // versions of these files.
+        // We need to make sure that if there were any previous docs already compiled,
+        // they were compiled with the same Rustc version that we're currently using.
+        // See the function doc comment for more.
         if self.bcx.build_config.intent.is_doc() {
             RustDocFingerprint::check_rustdoc_fingerprint(&self)?
         }

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

@@ -371,6 +371,7 @@
 
 mod dep_info;
 mod dirty_reason;
+mod rustdoc;
 
 use std::collections::hash_map::{Entry, HashMap};
 use std::env;
@@ -409,6 +410,7 @@ pub use self::dep_info::parse_dep_info;
 pub use self::dep_info::parse_rustc_dep_info;
 pub use self::dep_info::translate_dep_info;
 pub use self::dirty_reason::DirtyReason;
+pub use self::rustdoc::RustDocFingerprint;
 
 /// Determines if a [`Unit`] is up-to-date, and if not prepares necessary work to
 /// update the persisted fingerprint.

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

@@ -0,0 +1,150 @@
+use std::path::Path;
+
+use anyhow::Context as _;
+use cargo_util::paths;
+use serde::Deserialize;
+use serde::Serialize;
+
+use crate::CargoResult;
+use crate::core::compiler::BuildRunner;
+use crate::core::compiler::CompileKind;
+
+/// Structure used to deal with Rustdoc fingerprinting
+///
+/// This is important because the `.js`/`.html` & `.css` files
+/// that are generated by Rustc don't have any versioning yet
+/// (see <https://github.com/rust-lang/cargo/issues/8461>).
+/// Therefore, we can end up with weird bugs and behaviours
+/// if we mix different versions of these files.
+///
+/// We need to make sure that if there were any previous docs already compiled,
+/// they were compiled with the same Rustc version that we're currently using.
+/// Otherwise we must remove the `doc/` folder and compile again forcing a rebuild.
+#[derive(Debug, Serialize, Deserialize)]
+pub struct RustDocFingerprint {
+    /// `rustc -vV` verbose version output.
+    pub rustc_vv: String,
+}
+
+impl RustDocFingerprint {
+    /// Checks whether the latest version of rustc used to compile this workspace's docs
+    /// 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 `<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
+            .gctx
+            .cli_unstable()
+            .skip_rustdoc_fingerprint
+        {
+            return Ok(());
+        }
+        let new_fingerprint = RustDocFingerprint {
+            rustc_vv: build_runner.bcx.rustc().verbose_version.clone(),
+        };
+
+        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()
+        .with_context(|| format!("failed to read directory `{}`", path.display()))?;
+    for entry in entries {
+        let entry = entry?;
+        // Don't remove hidden files. Rustdoc does not create them,
+        // but the user might have.
+        if entry
+            .file_name()
+            .to_str()
+            .map_or(false, |name| name.starts_with('.'))
+        {
+            continue;
+        }
+        let path = entry.path();
+        if entry.file_type()?.is_dir() {
+            paths::remove_dir_all(path)?;
+        } else {
+            paths::remove_file(path)?;
+        }
+    }
+    Ok(())
+}

src/cargo/core/compiler/mod.rs

@@ -72,16 +72,19 @@ use tracing::{debug, instrument, trace};
 
 pub use self::build_config::UserIntent;
 pub use self::build_config::{BuildConfig, CompileMode, MessageFormat, TimingOutput};
-pub use self::build_context::{
-    BuildContext, FileFlavor, FileType, RustDocFingerprint, RustcTargetData, TargetInfo,
-};
+pub use self::build_context::BuildContext;
+pub use self::build_context::FileFlavor;
+pub use self::build_context::FileType;
+pub use self::build_context::RustcTargetData;
+pub use self::build_context::TargetInfo;
 pub use self::build_runner::{BuildRunner, Metadata, UnitHash};
 pub use self::compilation::{Compilation, Doctest, UnitOutput};
 pub use self::compile_kind::{CompileKind, CompileKindFallback, CompileTarget};
 pub use self::crate_type::CrateType;
 pub use self::custom_build::LinkArgTarget;
 pub use self::custom_build::{BuildOutput, BuildScriptOutputs, BuildScripts, LibraryPath};
 pub(crate) use self::fingerprint::DirtyReason;
+pub use self::fingerprint::RustDocFingerprint;
 pub use self::job_queue::Freshness;
 use self::job_queue::{Job, JobQueue, JobState, Work};
 pub(crate) use self::layout::Layout;