From 95dafab66045bdad26fdb7b72e09e15d24c1ada9 Mon Sep 17 00:00:00 2001
From: Weihang Lo <me@weihanglo.tw>
Date: Thu, 27 Mar 2025 10:45:05 -0400
Subject: [PATCH 1/4] feat(unstable): add `-Zrustdoc-depinfo` flag

---
 src/cargo/core/features.rs                   |  2 ++
 tests/testsuite/cargo/z_help/stdout.term.svg | 30 +++++++++++---------
 tests/testsuite/doc.rs                       | 17 +++++++++++
 3 files changed, 35 insertions(+), 14 deletions(-)

diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs
index f5aab9dc60b..152d308d832 100644
--- a/src/cargo/core/features.rs
+++ b/src/cargo/core/features.rs
@@ -790,6 +790,7 @@ unstable_cli_options!(
     public_dependency: bool = ("Respect a dependency's `public` field in Cargo.toml to control public/private dependencies"),
     publish_timeout: bool = ("Enable the `publish.timeout` key in .cargo/config.toml file"),
     root_dir: Option<PathBuf> = ("Set the root directory relative to which paths are printed (defaults to workspace root)"),
+    rustdoc_depinfo: bool = ("Use dep-info files in rustdoc rebuild detection"),
     rustdoc_map: bool = ("Allow passing external documentation mappings to rustdoc"),
     rustdoc_scrape_examples: bool = ("Allows Rustdoc to scrape code examples from reverse-dependencies"),
     sbom: bool = ("Enable the `sbom` option in build config in .cargo/config.toml file"),
@@ -1303,6 +1304,7 @@ impl CliUnstable {
             "trim-paths" => self.trim_paths = parse_empty(k, v)?,
             "publish-timeout" => self.publish_timeout = parse_empty(k, v)?,
             "root-dir" => self.root_dir = v.map(|v| v.into()),
+            "rustdoc-depinfo" => self.rustdoc_depinfo = parse_empty(k, v)?,
             "rustdoc-map" => self.rustdoc_map = parse_empty(k, v)?,
             "rustdoc-scrape-examples" => self.rustdoc_scrape_examples = parse_empty(k, v)?,
             "sbom" => self.sbom = parse_empty(k, v)?,
diff --git a/tests/testsuite/cargo/z_help/stdout.term.svg b/tests/testsuite/cargo/z_help/stdout.term.svg
index c7791176d58..c152f663f20 100644
--- a/tests/testsuite/cargo/z_help/stdout.term.svg
+++ b/tests/testsuite/cargo/z_help/stdout.term.svg
@@ -1,4 +1,4 @@
-<svg width="1230px" height="830px" xmlns="http://www.w3.org/2000/svg">
+<svg width="1230px" height="848px" xmlns="http://www.w3.org/2000/svg">
   <style>
     .fg { fill: #AAAAAA }
     .bg { background: #000000 }
@@ -80,31 +80,33 @@
 </tspan>
     <tspan x="10px" y="586px"><tspan>    -Z root-dir                 Set the root directory relative to which paths are printed (defaults to workspace root)</tspan>
 </tspan>
-    <tspan x="10px" y="604px"><tspan>    -Z rustdoc-map              Allow passing external documentation mappings to rustdoc</tspan>
+    <tspan x="10px" y="604px"><tspan>    -Z rustdoc-depinfo          Use dep-info files in rustdoc rebuild detection</tspan>
 </tspan>
-    <tspan x="10px" y="622px"><tspan>    -Z rustdoc-scrape-examples  Allows Rustdoc to scrape code examples from reverse-dependencies</tspan>
+    <tspan x="10px" y="622px"><tspan>    -Z rustdoc-map              Allow passing external documentation mappings to rustdoc</tspan>
 </tspan>
-    <tspan x="10px" y="640px"><tspan>    -Z sbom                     Enable the `sbom` option in build config in .cargo/config.toml file</tspan>
+    <tspan x="10px" y="640px"><tspan>    -Z rustdoc-scrape-examples  Allows Rustdoc to scrape code examples from reverse-dependencies</tspan>
 </tspan>
-    <tspan x="10px" y="658px"><tspan>    -Z script                   Enable support for single-file, `.rs` packages</tspan>
+    <tspan x="10px" y="658px"><tspan>    -Z sbom                     Enable the `sbom` option in build config in .cargo/config.toml file</tspan>
 </tspan>
-    <tspan x="10px" y="676px"><tspan>    -Z target-applies-to-host   Enable the `target-applies-to-host` key in the .cargo/config.toml file</tspan>
+    <tspan x="10px" y="676px"><tspan>    -Z script                   Enable support for single-file, `.rs` packages</tspan>
 </tspan>
-    <tspan x="10px" y="694px"><tspan>    -Z trim-paths               Enable the `trim-paths` option in profiles</tspan>
+    <tspan x="10px" y="694px"><tspan>    -Z target-applies-to-host   Enable the `target-applies-to-host` key in the .cargo/config.toml file</tspan>
 </tspan>
-    <tspan x="10px" y="712px"><tspan>    -Z unstable-options         Allow the usage of unstable options</tspan>
+    <tspan x="10px" y="712px"><tspan>    -Z trim-paths               Enable the `trim-paths` option in profiles</tspan>
 </tspan>
-    <tspan x="10px" y="730px"><tspan>    -Z warnings                 Allow use of the build.warnings config key</tspan>
+    <tspan x="10px" y="730px"><tspan>    -Z unstable-options         Allow the usage of unstable options</tspan>
 </tspan>
-    <tspan x="10px" y="748px">
+    <tspan x="10px" y="748px"><tspan>    -Z warnings                 Allow use of the build.warnings config key</tspan>
 </tspan>
-    <tspan x="10px" y="766px"><tspan>Run with `cargo -Z [FLAG] [COMMAND]`</tspan>
+    <tspan x="10px" y="766px">
 </tspan>
-    <tspan x="10px" y="784px">
+    <tspan x="10px" y="784px"><tspan>Run with `cargo -Z [FLAG] [COMMAND]`</tspan>
 </tspan>
-    <tspan x="10px" y="802px"><tspan>See https://doc.rust-lang.org/nightly/cargo/reference/unstable.html for more information about these flags.</tspan>
+    <tspan x="10px" y="802px">
 </tspan>
-    <tspan x="10px" y="820px">
+    <tspan x="10px" y="820px"><tspan>See https://doc.rust-lang.org/nightly/cargo/reference/unstable.html for more information about these flags.</tspan>
+</tspan>
+    <tspan x="10px" y="838px">
 </tspan>
   </text>
 
diff --git a/tests/testsuite/doc.rs b/tests/testsuite/doc.rs
index fcaa553f027..f8a220ebcc5 100644
--- a/tests/testsuite/doc.rs
+++ b/tests/testsuite/doc.rs
@@ -2897,3 +2897,20 @@ Caused by:
         .with_status(101)
         .run();
 }
+
+#[cargo_test(nightly, reason = "`rustdoc --emit` is unstable")]
+fn rustdoc_depinfo_gated() {
+    let p = project()
+        .file("Cargo.toml", &basic_lib_manifest("foo"))
+        .file("src/lib.rs", "")
+        .build();
+
+    p.cargo("doc -Zrustdoc-depinfo")
+        .with_status(101)
+        .with_stderr_data(str![[r#"
+[ERROR] the `-Z` flag is only accepted on the nightly channel of Cargo, but this is the `stable` channel
+See https://doc.rust-lang.org/book/appendix-07-nightly-rust.html for more information about Rust release channels.
+
+"#]])
+        .run();
+}

From 3530a26e5a55987ebcad0f681fc411936b719508 Mon Sep 17 00:00:00 2001
From: Weihang Lo <me@weihanglo.tw>
Date: Thu, 27 Mar 2025 12:15:15 -0400
Subject: [PATCH 2/4] docs(unstable): explain `-Z rustdoc-depinfo`

---
 src/doc/src/reference/unstable.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md
index c527fb63d1f..1d031301992 100644
--- a/src/doc/src/reference/unstable.md
+++ b/src/doc/src/reference/unstable.md
@@ -98,6 +98,7 @@ Each new feature described below should explain how to use it.
     * [rustdoc-map](#rustdoc-map) --- Provides mappings for documentation to link to external sites like [docs.rs](https://docs.rs/).
     * [scrape-examples](#scrape-examples) --- Shows examples within documentation.
     * [output-format](#output-format-for-rustdoc) --- Allows documentation to also be emitted in the experimental [JSON format](https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc_json_types/).
+    * [rustdoc-depinfo](#rustdoc-depinfo) --- Use dep-info files in rustdoc rebuild detection.
 * `Cargo.toml` extensions
     * [Profile `rustflags` option](#profile-rustflags-option) --- Passed directly to rustc.
     * [codegen-backend](#codegen-backend) --- Select the codegen backend used by rustc.
@@ -1901,6 +1902,14 @@ Requires `-Zunstable-options`.
 See [`cargo package --message-format`](../commands/cargo-package.md#option-cargo-package---message-format)
 for more information.
 
+## rustdoc depinfo
+
+* Tracking Issue: [#00000](https://github.com/rust-lang/cargo/issues/00000)
+
+The `-Z rustdoc-depinfo` flag leverages rustdoc's dep-info files to determine
+whether documentations are required to re-generate. This can be combined with
+`-Z checksum-freshness` to detect checksum changes rather than file mtime.
+
 # Stabilized and removed features
 
 ## Compile progress

From 1f6d4be0815c8d0d9236ff105aed4451d5d34c53 Mon Sep 17 00:00:00 2001
From: Weihang Lo <me@weihanglo.tw>
Date: Thu, 27 Mar 2025 11:48:27 -0400
Subject: [PATCH 3/4] test(doc): show scenarios `cargo doc` not rebuild

---
 tests/testsuite/doc.rs | 265 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 265 insertions(+)

diff --git a/tests/testsuite/doc.rs b/tests/testsuite/doc.rs
index f8a220ebcc5..f6397c755c0 100644
--- a/tests/testsuite/doc.rs
+++ b/tests/testsuite/doc.rs
@@ -2914,3 +2914,268 @@ See https://doc.rust-lang.org/book/appendix-07-nightly-rust.html for more inform
 "#]])
         .run();
 }
+
+#[cargo_test(nightly, reason = "`rustdoc --emit` is unstable")]
+fn rebuild_tracks_target_src_outside_package_root() {
+    let p = cargo_test_support::project_in("parent")
+        .file(
+            "Cargo.toml",
+            r#"
+                [package]
+                name = "foo"
+                edition = "2015"
+                [lib]
+                path = "../lib.rs"
+            "#,
+        )
+        .file("../lib.rs", "//! # depinfo-before")
+        .build();
+
+    p.cargo("doc -Zrustdoc-depinfo")
+        .masquerade_as_nightly_cargo(&["rustdoc-depinfo"])
+        .with_stderr_data(str![[r#"
+[DOCUMENTING] foo v0.0.0 ([ROOT]/parent/foo)
+[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
+[GENERATED] [ROOT]/parent/foo/target/doc/foo/index.html
+
+"#]])
+        .run();
+
+    let doc_html = p.read_file("target/doc/foo/index.html");
+    assert!(doc_html.contains("depinfo-before"));
+
+    p.change_file("../lib.rs", "//! # depinfo-after");
+
+    p.cargo("doc --verbose -Zrustdoc-depinfo")
+        .masquerade_as_nightly_cargo(&["rustdoc-depinfo"])
+        .with_stderr_data(str![[r#"
+[FRESH] foo v0.0.0 ([ROOT]/parent/foo)
+[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
+[GENERATED] [ROOT]/parent/foo/target/doc/foo/index.html
+
+"#]])
+        .run();
+
+    let doc_html = p.read_file("target/doc/foo/index.html");
+    assert!(!doc_html.contains("depinfo-after"));
+}
+
+#[cargo_test(nightly, reason = "`rustdoc --emit` is unstable")]
+fn rebuild_tracks_include_str() {
+    let p = cargo_test_support::project_in("parent")
+        .file("Cargo.toml", &basic_lib_manifest("foo"))
+        .file("src/lib.rs", r#"#![doc = include_str!("../../README")]"#)
+        .file("../README", "# depinfo-before")
+        .build();
+
+    p.cargo("doc -Zrustdoc-depinfo")
+        .masquerade_as_nightly_cargo(&["rustdoc-depinfo"])
+        .with_stderr_data(str![[r#"
+[DOCUMENTING] foo v0.5.0 ([ROOT]/parent/foo)
+[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
+[GENERATED] [ROOT]/parent/foo/target/doc/foo/index.html
+
+"#]])
+        .run();
+
+    let doc_html = p.read_file("target/doc/foo/index.html");
+    assert!(doc_html.contains("depinfo-before"));
+
+    p.change_file("../README", "# depinfo-after");
+
+    p.cargo("doc --verbose -Zrustdoc-depinfo")
+        .masquerade_as_nightly_cargo(&["rustdoc-depinfo"])
+        .with_stderr_data(str![[r#"
+[FRESH] foo v0.5.0 ([ROOT]/parent/foo)
+[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
+[GENERATED] [ROOT]/parent/foo/target/doc/foo/index.html
+
+"#]])
+        .run();
+
+    let doc_html = p.read_file("target/doc/foo/index.html");
+    assert!(!doc_html.contains("depinfo-after"));
+}
+
+#[cargo_test(nightly, reason = "`rustdoc --emit` is unstable")]
+fn rebuild_tracks_path_attr() {
+    let p = cargo_test_support::project_in("parent")
+        .file("Cargo.toml", &basic_lib_manifest("foo"))
+        .file("src/lib.rs", r#"#[path = "../../bar.rs"] pub mod bar;"#)
+        .file("../bar.rs", "//! # depinfo-before")
+        .build();
+
+    p.cargo("doc -Zrustdoc-depinfo")
+        .masquerade_as_nightly_cargo(&["rustdoc-depinfo"])
+        .with_stderr_data(str![[r#"
+[DOCUMENTING] foo v0.5.0 ([ROOT]/parent/foo)
+[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
+[GENERATED] [ROOT]/parent/foo/target/doc/foo/index.html
+
+"#]])
+        .run();
+
+    let doc_html = p.read_file("target/doc/foo/index.html");
+    assert!(doc_html.contains("depinfo-before"));
+
+    p.change_file("../bar.rs", "//! # depinfo-after");
+
+    p.cargo("doc --verbose -Zrustdoc-depinfo")
+        .masquerade_as_nightly_cargo(&["rustdoc-depinfo"])
+        .with_stderr_data(str![[r#"
+[FRESH] foo v0.5.0 ([ROOT]/parent/foo)
+[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
+[GENERATED] [ROOT]/parent/foo/target/doc/foo/index.html
+
+"#]])
+        .run();
+
+    let doc_html = p.read_file("target/doc/foo/index.html");
+    assert!(!doc_html.contains("depinfo-after"));
+}
+
+#[cargo_test(nightly, reason = "`rustdoc --emit` is unstable")]
+fn rebuild_tracks_env() {
+    let env = "__RUSTDOC_INJECTED";
+    let p = project()
+        .file("Cargo.toml", &basic_lib_manifest("foo"))
+        .file("src/lib.rs", &format!(r#"#![doc = env!("{env}")]"#))
+        .build();
+
+    p.cargo("doc -Zrustdoc-depinfo")
+        .env(env, "# depinfo-before")
+        .masquerade_as_nightly_cargo(&["rustdoc-depinfo"])
+        .with_stderr_data(str![[r#"
+[DOCUMENTING] foo v0.5.0 ([ROOT]/foo)
+[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
+[GENERATED] [ROOT]/foo/target/doc/foo/index.html
+
+"#]])
+        .run();
+
+    let doc_html = p.read_file("target/doc/foo/index.html");
+    assert!(doc_html.contains("depinfo-before"));
+
+    p.cargo("doc --verbose -Zrustdoc-depinfo")
+        .env(env, "# depinfo-after")
+        .masquerade_as_nightly_cargo(&["rustdoc-depinfo"])
+        .with_stderr_data(str![[r#"
+[FRESH] foo v0.5.0 ([ROOT]/foo)
+[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
+[GENERATED] [ROOT]/foo/target/doc/foo/index.html
+
+"#]])
+        .run();
+
+    let doc_html = p.read_file("target/doc/foo/index.html");
+    assert!(!doc_html.contains("depinfo-after"));
+}
+
+#[cargo_test(nightly, reason = "`rustdoc --emit` is unstable")]
+fn rebuild_tracks_env_in_dep() {
+    let env = "__RUSTDOC_INJECTED";
+    Package::new("bar", "0.1.0")
+        .file("src/lib.rs", &format!(r#"#![doc = env!("{env}")]"#))
+        .publish();
+
+    let env = "__RUSTDOC_INJECTED";
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+                [package]
+                name = "foo"
+                edition = "2015"
+                [dependencies]
+                bar = "0.1.0"
+            "#,
+        )
+        .file("src/lib.rs", "")
+        .build();
+
+    p.cargo("doc -Zrustdoc-depinfo")
+        .env(env, "# depinfo-before")
+        .masquerade_as_nightly_cargo(&["rustdoc-depinfo"])
+        .with_stderr_data(
+            str![[r#"
+[UPDATING] `dummy-registry` index
+[LOCKING] 1 package to latest compatible version
+[DOWNLOADING] crates ...
+[DOWNLOADED] bar v0.1.0 (registry `dummy-registry`)
+[CHECKING] bar v0.1.0
+[DOCUMENTING] bar v0.1.0
+[DOCUMENTING] foo v0.0.0 ([ROOT]/foo)
+[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
+[GENERATED] [ROOT]/foo/target/doc/foo/index.html
+
+"#]]
+            .unordered(),
+        )
+        .run();
+
+    let doc_html = p.read_file("target/doc/bar/index.html");
+    assert!(doc_html.contains("depinfo-before"));
+
+    p.cargo("doc --verbose -Zrustdoc-depinfo")
+        .env(env, "# depinfo-after")
+        .masquerade_as_nightly_cargo(&["rustdoc-depinfo"])
+        .with_stderr_data(str![[r#"
+[DIRTY] bar v0.1.0: the environment variable __RUSTDOC_INJECTED changed
+[CHECKING] bar v0.1.0
+[RUNNING] `rustc --crate-name bar [..]`
+[DIRTY] foo v0.0.0 ([ROOT]/foo): the dependency bar was rebuilt
+[DOCUMENTING] foo v0.0.0 ([ROOT]/foo)
+[RUNNING] `rustdoc [..]--crate-name foo [..]`
+[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
+[GENERATED] [ROOT]/foo/target/doc/foo/index.html
+
+"#]])
+        .run();
+
+    let doc_html = p.read_file("target/doc/bar/index.html");
+    assert!(!doc_html.contains("depinfo-after"));
+}
+
+#[cargo_test(
+    nightly,
+    reason = "`rustdoc --emit` is unstable; requires -Zchecksum-hash-algorithm"
+)]
+fn rebuild_tracks_checksum() {
+    let p = cargo_test_support::project_in("parent")
+        .file("Cargo.toml", &basic_lib_manifest("foo"))
+        .file("src/lib.rs", r#"#![doc = include_str!("../../README")]"#)
+        .file("../README", "# depinfo-before")
+        .build();
+
+    p.cargo("doc -Zrustdoc-depinfo -Zchecksum-freshness")
+        .masquerade_as_nightly_cargo(&["rustdoc-depinfo", "checksum-freshness"])
+        .with_stderr_data(str![[r#"
+[DOCUMENTING] foo v0.5.0 ([ROOT]/parent/foo)
+[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
+[GENERATED] [ROOT]/parent/foo/target/doc/foo/index.html
+
+"#]])
+        .run();
+
+    let doc_html = p.read_file("target/doc/foo/index.html");
+    assert!(doc_html.contains("depinfo-before"));
+
+    p.change_file("../README", "# depinfo-after");
+    // Change mtime into the future
+    p.root().move_into_the_future();
+
+    p.cargo("doc --verbose -Zrustdoc-depinfo -Zchecksum-freshness")
+        .masquerade_as_nightly_cargo(&["rustdoc-depinfo"])
+        .with_stderr_data(str![[r#"
+[DIRTY] foo v0.5.0 ([ROOT]/parent/foo): the precalculated components changed
+[DOCUMENTING] foo v0.5.0 ([ROOT]/parent/foo)
+[RUNNING] `rustdoc [..]`
+[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
+[GENERATED] [ROOT]/parent/foo/target/doc/foo/index.html
+
+"#]])
+        .run();
+
+    let doc_html = p.read_file("target/doc/foo/index.html");
+    assert!(doc_html.contains("depinfo-after"));
+}

From a18e60462ed4d4a95c256e3a3f0469d3dff62f46 Mon Sep 17 00:00:00 2001
From: Weihang Lo <me@weihanglo.tw>
Date: Thu, 27 Mar 2025 10:16:06 -0400
Subject: [PATCH 4/4] feat(fingerprint): integrate rustdoc dep-info files

This leverages the unstable `--emit=depinfo` option from rustdoc,
so that rustdoc invocation rebuild can be better tracked
without traversing the entire directory.

Some design decisions:

* Rustdoc's depinfo doesn't and shouldn't emit to `target/doc`,
  as the directory is considered part of the final artifact directory.
  In regard to that, we specify the dep-info output path to
  the fingerprint directory of rustdoc invocation.
  It looks like this
  `target/debug/.fingerprint/serde-12d29d32b3b8b38f/doc-lib-serde.d`.
* We also start supporting `-Zchecksum-freshness` as a side effect.
  Could make it a separate PR if desired.
* `-Zbinary-dep-depinfo` is not enabled along with this,
  since doc generations don't really require any binary dependencies.
---
 src/cargo/core/compiler/fingerprint/mod.rs |  4 +-
 src/cargo/core/compiler/mod.rs             | 58 ++++++++++++++++++++++
 tests/testsuite/doc.rs                     | 38 +++++++++-----
 3 files changed, 87 insertions(+), 13 deletions(-)

diff --git a/src/cargo/core/compiler/fingerprint/mod.rs b/src/cargo/core/compiler/fingerprint/mod.rs
index 379bab0b159..f30bab0ea3f 100644
--- a/src/cargo/core/compiler/fingerprint/mod.rs
+++ b/src/cargo/core/compiler/fingerprint/mod.rs
@@ -1494,7 +1494,9 @@ fn calculate_normal(
 
     // Afterwards calculate our own fingerprint information.
     let build_root = build_root(build_runner);
-    let local = if unit.mode.is_doc() || unit.mode.is_doc_scrape() {
+    let is_any_doc_gen = unit.mode.is_doc() || unit.mode.is_doc_scrape();
+    let rustdoc_depinfo_enabled = build_runner.bcx.gctx.cli_unstable().rustdoc_depinfo;
+    let local = if is_any_doc_gen && !rustdoc_depinfo_enabled {
         // rustdoc does not have dep-info files.
         let fingerprint = pkg_fingerprint(build_runner.bcx, &unit.pkg).with_context(|| {
             format!(
diff --git a/src/cargo/core/compiler/mod.rs b/src/cargo/core/compiler/mod.rs
index 3ec3b74ba93..7825a30fe1b 100644
--- a/src/cargo/core/compiler/mod.rs
+++ b/src/cargo/core/compiler/mod.rs
@@ -763,6 +763,19 @@ fn prepare_rustdoc(build_runner: &BuildRunner<'_, '_>, unit: &Unit) -> CargoResu
     add_error_format_and_color(build_runner, &mut rustdoc);
     add_allow_features(build_runner, &mut rustdoc);
 
+    if build_runner.bcx.gctx.cli_unstable().rustdoc_depinfo {
+        // invocation-specific is required for keeping the original rustdoc emission
+        let mut arg = OsString::from("--emit=invocation-specific,dep-info=");
+        arg.push(rustdoc_dep_info_loc(build_runner, unit));
+        rustdoc.arg(arg);
+
+        if build_runner.bcx.gctx.cli_unstable().checksum_freshness {
+            rustdoc.arg("-Z").arg("checksum-hash-algorithm=blake3");
+        }
+
+        rustdoc.arg("-Zunstable-options");
+    }
+
     if let Some(trim_paths) = unit.profile.trim_paths.as_ref() {
         trim_paths_args_rustdoc(&mut rustdoc, build_runner, unit, trim_paths)?;
     }
@@ -838,6 +851,20 @@ fn rustdoc(build_runner: &mut BuildRunner<'_, '_>, unit: &Unit) -> CargoResult<W
     let package_id = unit.pkg.package_id();
     let manifest_path = PathBuf::from(unit.pkg.manifest_path());
     let target = Target::clone(&unit.target);
+
+    let rustdoc_dep_info_loc = rustdoc_dep_info_loc(build_runner, unit);
+    let dep_info_loc = fingerprint::dep_info_loc(build_runner, unit);
+    let build_dir = build_runner.bcx.ws.build_dir().into_path_unlocked();
+    let pkg_root = unit.pkg.root().to_path_buf();
+    let cwd = rustdoc
+        .get_cwd()
+        .unwrap_or_else(|| build_runner.bcx.gctx.cwd())
+        .to_path_buf();
+    let fingerprint_dir = build_runner.files().fingerprint_dir(unit);
+    let is_local = unit.is_local();
+    let env_config = Arc::clone(build_runner.bcx.gctx.env_config()?);
+    let rustdoc_depinfo_enabled = build_runner.bcx.gctx.cli_unstable().rustdoc_depinfo;
+
     let mut output_options = OutputOptions::new(build_runner, unit);
     let script_metadata = build_runner.find_build_script_metadata(unit);
     let scrape_outputs = if should_include_scrape_units(build_runner.bcx, unit) {
@@ -903,6 +930,7 @@ fn rustdoc(build_runner: &mut BuildRunner<'_, '_>, unit: &Unit) -> CargoResult<W
             paths::remove_dir_all(crate_dir)?;
         }
         state.running(&rustdoc);
+        let timestamp = paths::set_invocation_time(&fingerprint_dir)?;
 
         let result = rustdoc
             .exec_with_streaming(
@@ -930,6 +958,29 @@ fn rustdoc(build_runner: &mut BuildRunner<'_, '_>, unit: &Unit) -> CargoResult<W
             return Err(e);
         }
 
+        if rustdoc_depinfo_enabled && rustdoc_dep_info_loc.exists() {
+            fingerprint::translate_dep_info(
+                &rustdoc_dep_info_loc,
+                &dep_info_loc,
+                &cwd,
+                &pkg_root,
+                &build_dir,
+                &rustdoc,
+                // Should we track source file for doc gen?
+                is_local,
+                &env_config,
+            )
+            .with_context(|| {
+                internal(format_args!(
+                    "could not parse/generate dep info at: {}",
+                    rustdoc_dep_info_loc.display()
+                ))
+            })?;
+            // This mtime shift allows Cargo to detect if a source file was
+            // modified in the middle of the build.
+            paths::set_file_time_no_err(dep_info_loc, timestamp);
+        }
+
         Ok(())
     }))
 }
@@ -2012,3 +2063,10 @@ fn scrape_output_path(build_runner: &BuildRunner<'_, '_>, unit: &Unit) -> CargoR
         .outputs(unit)
         .map(|outputs| outputs[0].path.clone())
 }
+
+/// Gets the dep-info file emitted by rustdoc.
+fn rustdoc_dep_info_loc(build_runner: &BuildRunner<'_, '_>, unit: &Unit) -> PathBuf {
+    let mut loc = build_runner.files().fingerprint_file_path(unit, "");
+    loc.set_extension("d");
+    loc
+}
diff --git a/tests/testsuite/doc.rs b/tests/testsuite/doc.rs
index f6397c755c0..15b664f9a0a 100644
--- a/tests/testsuite/doc.rs
+++ b/tests/testsuite/doc.rs
@@ -2949,7 +2949,9 @@ fn rebuild_tracks_target_src_outside_package_root() {
     p.cargo("doc --verbose -Zrustdoc-depinfo")
         .masquerade_as_nightly_cargo(&["rustdoc-depinfo"])
         .with_stderr_data(str![[r#"
-[FRESH] foo v0.0.0 ([ROOT]/parent/foo)
+[DIRTY] foo v0.0.0 ([ROOT]/parent/foo): the file `../lib.rs` has changed ([TIME_DIFF_AFTER_LAST_BUILD])
+[DOCUMENTING] foo v0.0.0 ([ROOT]/parent/foo)
+[RUNNING] `rustdoc [..]`
 [FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
 [GENERATED] [ROOT]/parent/foo/target/doc/foo/index.html
 
@@ -2957,7 +2959,7 @@ fn rebuild_tracks_target_src_outside_package_root() {
         .run();
 
     let doc_html = p.read_file("target/doc/foo/index.html");
-    assert!(!doc_html.contains("depinfo-after"));
+    assert!(doc_html.contains("depinfo-after"));
 }
 
 #[cargo_test(nightly, reason = "`rustdoc --emit` is unstable")]
@@ -2986,7 +2988,9 @@ fn rebuild_tracks_include_str() {
     p.cargo("doc --verbose -Zrustdoc-depinfo")
         .masquerade_as_nightly_cargo(&["rustdoc-depinfo"])
         .with_stderr_data(str![[r#"
-[FRESH] foo v0.5.0 ([ROOT]/parent/foo)
+[DIRTY] foo v0.5.0 ([ROOT]/parent/foo): the file `src/../../README` has changed ([TIME_DIFF_AFTER_LAST_BUILD])
+[DOCUMENTING] foo v0.5.0 ([ROOT]/parent/foo)
+[RUNNING] `rustdoc [..]`
 [FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
 [GENERATED] [ROOT]/parent/foo/target/doc/foo/index.html
 
@@ -2994,7 +2998,7 @@ fn rebuild_tracks_include_str() {
         .run();
 
     let doc_html = p.read_file("target/doc/foo/index.html");
-    assert!(!doc_html.contains("depinfo-after"));
+    assert!(doc_html.contains("depinfo-after"));
 }
 
 #[cargo_test(nightly, reason = "`rustdoc --emit` is unstable")]
@@ -3023,7 +3027,9 @@ fn rebuild_tracks_path_attr() {
     p.cargo("doc --verbose -Zrustdoc-depinfo")
         .masquerade_as_nightly_cargo(&["rustdoc-depinfo"])
         .with_stderr_data(str![[r#"
-[FRESH] foo v0.5.0 ([ROOT]/parent/foo)
+[DIRTY] foo v0.5.0 ([ROOT]/parent/foo): the file `src/../../bar.rs` has changed ([TIME_DIFF_AFTER_LAST_BUILD])
+[DOCUMENTING] foo v0.5.0 ([ROOT]/parent/foo)
+[RUNNING] `rustdoc [..]`
 [FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
 [GENERATED] [ROOT]/parent/foo/target/doc/foo/index.html
 
@@ -3031,7 +3037,7 @@ fn rebuild_tracks_path_attr() {
         .run();
 
     let doc_html = p.read_file("target/doc/foo/index.html");
-    assert!(!doc_html.contains("depinfo-after"));
+    assert!(doc_html.contains("depinfo-after"));
 }
 
 #[cargo_test(nightly, reason = "`rustdoc --emit` is unstable")]
@@ -3060,7 +3066,9 @@ fn rebuild_tracks_env() {
         .env(env, "# depinfo-after")
         .masquerade_as_nightly_cargo(&["rustdoc-depinfo"])
         .with_stderr_data(str![[r#"
-[FRESH] foo v0.5.0 ([ROOT]/foo)
+[DIRTY] foo v0.5.0 ([ROOT]/foo): the environment variable __RUSTDOC_INJECTED changed
+[DOCUMENTING] foo v0.5.0 ([ROOT]/foo)
+[RUNNING] `rustdoc [..]`
 [FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
 [GENERATED] [ROOT]/foo/target/doc/foo/index.html
 
@@ -3068,7 +3076,7 @@ fn rebuild_tracks_env() {
         .run();
 
     let doc_html = p.read_file("target/doc/foo/index.html");
-    assert!(!doc_html.contains("depinfo-after"));
+    assert!(doc_html.contains("depinfo-after"));
 }
 
 #[cargo_test(nightly, reason = "`rustdoc --emit` is unstable")]
@@ -3119,21 +3127,27 @@ fn rebuild_tracks_env_in_dep() {
     p.cargo("doc --verbose -Zrustdoc-depinfo")
         .env(env, "# depinfo-after")
         .masquerade_as_nightly_cargo(&["rustdoc-depinfo"])
-        .with_stderr_data(str![[r#"
+        .with_stderr_data(
+            str![[r#"
+[DIRTY] bar v0.1.0: the environment variable __RUSTDOC_INJECTED changed
+[DOCUMENTING] bar v0.1.0
 [DIRTY] bar v0.1.0: the environment variable __RUSTDOC_INJECTED changed
 [CHECKING] bar v0.1.0
 [RUNNING] `rustc --crate-name bar [..]`
+[RUNNING] `rustdoc [..]--crate-name bar [..]`
 [DIRTY] foo v0.0.0 ([ROOT]/foo): the dependency bar was rebuilt
 [DOCUMENTING] foo v0.0.0 ([ROOT]/foo)
 [RUNNING] `rustdoc [..]--crate-name foo [..]`
 [FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
 [GENERATED] [ROOT]/foo/target/doc/foo/index.html
 
-"#]])
+"#]]
+            .unordered(),
+        )
         .run();
 
     let doc_html = p.read_file("target/doc/bar/index.html");
-    assert!(!doc_html.contains("depinfo-after"));
+    assert!(doc_html.contains("depinfo-after"));
 }
 
 #[cargo_test(
@@ -3167,7 +3181,7 @@ fn rebuild_tracks_checksum() {
     p.cargo("doc --verbose -Zrustdoc-depinfo -Zchecksum-freshness")
         .masquerade_as_nightly_cargo(&["rustdoc-depinfo"])
         .with_stderr_data(str![[r#"
-[DIRTY] foo v0.5.0 ([ROOT]/parent/foo): the precalculated components changed
+[DIRTY] foo v0.5.0 ([ROOT]/parent/foo): file size changed (16 != 15) for `src/../../README`
 [DOCUMENTING] foo v0.5.0 ([ROOT]/parent/foo)
 [RUNNING] `rustdoc [..]`
 [FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s