Implement Rustdoc versioning checks

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

@@ -11,7 +11,9 @@ use std::collections::HashMap;
 use std::path::PathBuf;
 
 mod target_info;
-pub use self::target_info::{FileFlavor, FileType, RustcTargetData, TargetInfo};
+pub use self::target_info::{
+    FileFlavor, FileType, RustDocFingerprint, RustcTargetData, TargetInfo,
+};
 
 /// The build context, containing all information about a build task.
 ///

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

@@ -3,10 +3,14 @@ use crate::core::{Dependency, Target, TargetKind, Workspace};
 use crate::util::config::{Config, StringList, TargetConfig};
 use crate::util::{CargoResult, CargoResultExt, ProcessBuilder, Rustc};
 use cargo_platform::{Cfg, CfgExpr};
+use serde::{Deserialize, Serialize};
+use serde_json::{from_str, to_writer};
 use std::cell::RefCell;
 use std::collections::hash_map::{Entry, HashMap};
 use std::env;
-use std::path::PathBuf;
+use std::fs::File;
+use std::io::Read;
+use std::path::{Path, PathBuf};
 use std::str::{self, FromStr};
 
 /// Information about the platform target gleaned from querying rustc.
@@ -754,3 +758,79 @@ impl RustcTargetData {
         self.target_config(kind).links_overrides.get(lib_name)
     }
 }
+
+/// Structure used to deal with Rustdoc fingerprinting
+#[derive(Debug, Serialize, Deserialize)]
+pub struct RustDocFingerprint {
+    _rustc_verbose_version: String,
+}
+
+impl RustDocFingerprint {
+    /// Returns the version contained by this `RustDocFingerprint` instance.
+    fn version(&self) -> &str {
+        self._rustc_verbose_version.as_str()
+    }
+
+    /// Given the `doc` dir, returns the path to the rustdoc fingerprint file.
+    fn path_to_fingerprint(doc_dir: &Path) -> PathBuf {
+        doc_dir.to_path_buf().join(".rustdoc_fingerprint.json")
+    }
+
+    /// Generate an instance of `RustDocFingerprint` from the fingerprint file.
+    fn from_file(file: &mut File) -> anyhow::Result<Self> {
+        let mut contents = String::new();
+        file.read_to_string(&mut contents)?;
+        let rustdoc_target_data: Self = from_str(&contents)?;
+        Ok(rustdoc_target_data)
+    }
+
+    /// Write the `RustDocFingerprint` info into the fingerprint file.
+    pub fn write(&self, doc_dir: &Path) -> std::io::Result<()> {
+        let rustdoc_fingerprint_file =
+            File::create(RustDocFingerprint::path_to_fingerprint(doc_dir))?;
+        // We write the actual `Rustc` version to it so that we just need to compile it straight
+        // since there's no `doc/` folder to remove.
+        to_writer(&rustdoc_fingerprint_file, &self)
+            .map_err(|e| std::io::Error::new(std::io::ErrorKind::Other, format!("{:?}", e)))
+    }
+
+    /// 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, returning `(bool, Self)` where the `bool` says if the `doc` folder was removed.
+    ///
+    /// In case it's not, it takes care of removig 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 `Rustc` autogenerates which do not have
+    /// any versioning.
+    pub fn check_rustdoc_fingerprint(
+        doc_dir: &Path,
+        rustc_verbose_ver: &str,
+    ) -> anyhow::Result<(Self, bool)> {
+        let actual_rustdoc_target_data = RustDocFingerprint {
+            _rustc_verbose_version: rustc_verbose_ver.to_string(),
+        };
+
+        // Check wether `.rustdoc_fingerprint.json exists
+        let mut fingerprint = match File::open(RustDocFingerprint::path_to_fingerprint(doc_dir)) {
+            Ok(file) => file,
+            // If the file does not exist, then we cannot assume that the docs were compiled
+            // with the actual Rustc instace version. Therefore, we try to remove the
+            // `doc` directory forcing the recompilation of the docs. If the directory doesn't
+            // exists neither, we simply do nothing and continue.
+            Err(_) => {
+                // We don't care if this suceeds as explained above.
+                let _ = std::fs::remove_dir_all(doc_dir);
+                return Ok((actual_rustdoc_target_data, true));
+            }
+        };
+
+        let previous_rustdoc_target_data = RustDocFingerprint::from_file(&mut fingerprint)?;
+        // Check if rustc_version matches the one we just used. Otherways,
+        // remove the `doc` folder to trigger a re-compilation of the docs.
+        if previous_rustdoc_target_data.version() != actual_rustdoc_target_data.version() {
+            std::fs::remove_dir_all(doc_dir)?;
+            return Ok((actual_rustdoc_target_data, true));
+        };
+        Ok((actual_rustdoc_target_data, false))
+    }
+}

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

@@ -5,11 +5,6 @@ use std::sync::{Arc, Mutex};
 use filetime::FileTime;
 use jobserver::Client;
 
-use crate::core::compiler::{self, compilation, Unit};
-use crate::core::PackageId;
-use crate::util::errors::{CargoResult, CargoResultExt};
-use crate::util::profile;
-
 use super::build_plan::BuildPlan;
 use super::custom_build::{self, BuildDeps, BuildScriptOutputs, BuildScripts};
 use super::fingerprint::Fingerprint;
@@ -18,6 +13,10 @@ use super::layout::Layout;
 use super::lto::Lto;
 use super::unit_graph::UnitDep;
 use super::{BuildContext, Compilation, CompileKind, CompileMode, Executor, FileFlavor};
+use crate::core::compiler::{self, compilation, Unit};
+use crate::core::PackageId;
+use crate::util::errors::{CargoResult, CargoResultExt};
+use crate::util::profile;
 
 mod compilation_files;
 use self::compilation_files::CompilationFiles;

src/cargo/core/compiler/mod.rs

@@ -32,7 +32,9 @@ use lazycell::LazyCell;
 use log::debug;
 
 pub use self::build_config::{BuildConfig, CompileMode, MessageFormat};
-pub use self::build_context::{BuildContext, FileFlavor, FileType, RustcTargetData, TargetInfo};
+pub use self::build_context::{
+    BuildContext, FileFlavor, FileType, RustDocFingerprint, RustcTargetData, TargetInfo,
+};
 use self::build_plan::BuildPlan;
 pub use self::compilation::{Compilation, Doctest};
 pub use self::compile_kind::{CompileKind, CompileTarget};
@@ -589,15 +591,26 @@ fn rustdoc(cx: &mut Context<'_, '_>, unit: &Unit) -> CargoResult<Work> {
     if let CompileKind::Target(target) = unit.kind {
         rustdoc.arg("--target").arg(target.rustc_target());
     }
-
     let doc_dir = cx.files().out_dir(unit);
+    // 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. Otherways 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
+    // compiler versions of these files.
+    let (fingerprint, doc_dir_removed) = RustDocFingerprint::check_rustdoc_fingerprint(
+        &doc_dir,
+        cx.bcx.rustc().verbose_version.as_str(),
+    )?;
 
     // Create the documentation directory ahead of time as rustdoc currently has
     // a bug where concurrent invocations will race to create this directory if
     // it doesn't already exist.
     paths::create_dir_all(&doc_dir)?;
 
-    rustdoc.arg("-o").arg(doc_dir);
+    rustdoc.arg("-o").arg(doc_dir.clone());
 
     for feat in &unit.features {
         rustdoc.arg("--cfg").arg(&format!("feature=\"{}\"", feat));
@@ -649,7 +662,11 @@ fn rustdoc(cx: &mut Context<'_, '_>, unit: &Unit) -> CargoResult<Work> {
                 &mut |line| on_stderr_line(state, line, package_id, &target, &mut output_options),
                 false,
             )
-            .chain_err(|| format!("could not document `{}`", name))?;
+            .chain_err(|| format!("Could not document `{}`.", name))?;
+
+        if doc_dir_removed {
+            fingerprint.write(&doc_dir)?
+        };
         Ok(())
     }))
 }

tests/testsuite/doc.rs

@@ -5,6 +5,7 @@ use cargo_test_support::registry::Package;
 use cargo_test_support::{basic_lib_manifest, basic_manifest, git, project};
 use cargo_test_support::{is_nightly, rustc_host};
 use std::fs;
+use std::io::Read;
 use std::str;
 
 #[cargo_test]
@@ -1639,50 +1640,181 @@ fn crate_versions_flag_is_overridden() {
     asserts(output_documentation());
 }
 
+#[cargo_test]
+fn rustc_adds_doc_fingerprint() {
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+            [package]
+            name = "foo"
+            version = "0.1.0"
+            authors = []
+        "#,
+        )
+        .file("src/lib.rs", "//! Hello")
+        .build();
+
+    p.cargo("doc").run();
+
+    // Read fingerprint rustc version and check it matches the expected one
+    let mut fingerprint = fs::File::open(
+        p.root()
+            .join("target")
+            .join("doc")
+            .join(".rustdoc_fingerprint.json"),
+    )
+    .expect("Failed to read fingerprint");
+
+    let mut rustc_verbose_version = String::new();
+    fingerprint
+        .read_to_string(&mut rustc_verbose_version)
+        .expect("Error reading the fingerprint contents");
+    let output = std::process::Command::new("rustc")
+        .arg("-vV")
+        .stdout(std::process::Stdio::inherit())
+        .output()
+        .expect("Failed to get actual rustc verbose version");
+    assert!(rustc_verbose_version
+        .as_str()
+        .contains(String::from_utf8_lossy(&output.stdout).as_ref()));
+}
+
+#[cargo_test]
+fn doc_fingerprint_versioning_consistent() {
+    // Test that using different Rustc versions forces a
+    // doc re-compilation producing new html, css & js files.
+
+    // Random rustc verbose version
+    let stable_rustc_verbose_version = format!(
+        "\
+rustc 1.41.1 (f3e1a954d 2020-02-24)
+binary: rustc
+commit-hash: f3e1a954d2ead4e2fc197c7da7d71e6c61bad196
+commit-date: 2020-02-24
+host: {}
+release: 1.41.1
+LLVM version: 9.0
+",
+        rustc_host()
+    );
+
+    // Create the dummy project.
+    let dummy_project = project()
+        .file(
+            "Cargo.toml",
+            r#"
+        [package]
+        name = "foo"
+        version = "1.2.4"
+        authors = []
+    "#,
+        )
+        .file("src/lib.rs", "//! These are the docs!")
+        .build();
+
+    dummy_project.cargo("doc").run();
+
+    // As the test shows avobe. Now we have generated the `doc/` folder and inside
+    // the rustdoc fingerprint file is located.
+    // So we will remove it and create a new fingerprint with an old rustc version
+    // inside it.
+    fs::remove_file(
+        dummy_project
+            .root()
+            .join("target")
+            .join("doc")
+            .join(".rustdoc_fingerprint.json"),
+    )
+    .expect("Failed to read fingerprint on tests");
+
+    fs::write(
+        dummy_project
+            .root()
+            .join("target")
+            .join("doc")
+            .join(".rustdoc_fingerprint.json"),
+        stable_rustc_verbose_version,
+    )
+    .expect("Error writing old rustc version");
+
+    // Now if we trigger another compilation, since the fingerprint contains an old version
+    // of rustc, cargo should remove the entire `/doc` folder (including the fingerprint)
+    // and generating another one with the actual version.
+    dummy_project.cargo("doc").run();
+
+    // Edit the fingerprint rustc version.
+    // Read fingerprint rustc version and return it as String
+    let get_fingerprint_version = |root_path: std::path::PathBuf| -> String {
+        let mut fingerprint = fs::File::open(
+            root_path
+                .join("target")
+                .join("doc")
+                .join(".rustdoc_fingerprint.json"),
+        )
+        .expect("Failed to read fingerprint on tests");
+
+        let mut rustc_verbose_version = String::new();
+        fingerprint
+            .read_to_string(&mut rustc_verbose_version)
+            .expect("Error reading the fingerprint contents");
+        rustc_verbose_version
+    };
+
+    let output = std::process::Command::new("rustc")
+        .arg("-vV")
+        .stdout(std::process::Stdio::inherit())
+        .output()
+        .expect("Failed to get actual rustc verbose version");
+    assert!(get_fingerprint_version(dummy_project.root())
+        .as_str()
+        .contains(String::from_utf8_lossy(&output.stdout).as_ref()));
+}
+
 #[cargo_test]
 fn doc_test_in_workspace() {
     let p = project()
         .file(
             "Cargo.toml",
             r#"
-                [workspace]
-                members = [
-                    "crate-a",
-                    "crate-b",
-                ]
-            "#,
+              [workspace]
+              members = [
+                  "crate-a",
+                  "crate-b",
+              ]
+          "#,
         )
         .file(
             "crate-a/Cargo.toml",
             r#"
-                [project]
-                name = "crate-a"
-                version = "0.1.0"
-            "#,
+              [project]
+              name = "crate-a"
+              version = "0.1.0"
+          "#,
         )
         .file(
             "crate-a/src/lib.rs",
             "\
-                //! ```
-                //! assert_eq!(1, 1);
-                //! ```
-            ",
+              //! ```
+              //! assert_eq!(1, 1);
+              //! ```
+          ",
         )
         .file(
             "crate-b/Cargo.toml",
             r#"
-                [project]
-                name = "crate-b"
-                version = "0.1.0"
-            "#,
+              [project]
+              name = "crate-b"
+              version = "0.1.0"
+          "#,
         )
         .file(
             "crate-b/src/lib.rs",
             "\
-                //! ```
-                //! assert_eq!(1, 1);
-                //! ```
-            ",
+              //! ```
+              //! assert_eq!(1, 1);
+              //! ```
+          ",
         )
         .build();
     p.cargo("test --doc -vv")