fix: stabilize -Zrustdoc-depinfo

doc/book/src/reference/unstable.md

@@ -107,7 +107,6 @@ 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.
     * [rustdoc-mergeable-info](#rustdoc-mergeable-info) --- Use rustdoc mergeable cross-crate-info files.
 * `Cargo.toml` extensions
     * [Profile `rustflags` option](#profile-rustflags-option) --- Passed directly to rustc.
@@ -1856,15 +1855,6 @@ Requires `-Zunstable-options`.
 See [`cargo package --message-format`](../commands/cargo-package.md#option-cargo-package---message-format)
 for more information.
 
-## rustdoc depinfo
-
-* Original Issue: [#12266](https://github.com/rust-lang/cargo/issues/12266)
-* Tracking Issue: [#15370](https://github.com/rust-lang/cargo/issues/15370)
-
-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.
-
 ## embed-metadata
 * Original Pull Request: [#15378](https://github.com/rust-lang/cargo/pull/15378)
 * Tracking Issue: [#15495](https://github.com/rust-lang/cargo/issues/15495)
@@ -2438,3 +2428,8 @@ Support for `resolver.lockfile-path` config field has been stabilized in Rust 1.
 ## warnings
 
 The `build.warnings` config field has been stabilized in Rust 1.97.
+
+## rustdoc-depinfo
+
+Using rustdoc's dep-info files for documentation rebuild detection
+was stabilized in the 1.99.0 release.

src/compiler/fingerprint/mod.rs

@@ -136,9 +136,8 @@
 //!   below for more details.
 //!
 //! Note that some units are a little different. A Unit for *running* a build
-//! script or for `rustdoc` does not have a dep-info file (it's not
-//! applicable). Build script `invoked.timestamp` files are in the build
-//! output directory.
+//! script does not have a dep-info file (it's not applicable).
+//! Build script `invoked.timestamp` files are in the build output directory.
 //!
 //! ## Fingerprint calculation
 //!
@@ -166,10 +165,11 @@
 //!
 //! #### `rustc` dep-info files
 //!
-//! Cargo passes the `--emit=dep-info` flag to `rustc` so that `rustc` will
-//! generate a "dep info" file (with the `.d` extension). This is a
-//! Makefile-like syntax that includes all of the source files used to build
-//! the crate. This file is used by Cargo to know which files to check to see
+//! Cargo passes the `--emit=dep-info` flag to `rustc` and `rustdoc`
+//! so that compiler will generate a "dep info" file (with the `.d` extension).
+//! This is a Makefile-like syntax that includes all of the source files used
+//! to build the crate.
+//! This file is used by Cargo to know which files to check to see
 //! if the crate will need to be rebuilt. Example:
 //!
 //! ```makefile
@@ -251,23 +251,15 @@
 //! build, so it takes a conservative approach of assuming the file was *not*
 //! included, and it should be rebuilt during the next build.
 //!
-//! #### Rustdoc mtime handling
-//!
-//! Rustdoc does not emit a dep-info file, so Cargo currently has a relatively
-//! simple system for detecting rebuilds. [`LocalFingerprint::Precalculated`] is
-//! used for rustdoc units. For registry packages, this is the package
-//! version. For git packages, it is the git hash. For path packages, it is
-//! a string of the mtime of the newest file in the package.
-//!
-//! There are some known bugs with how this works, so it should be improved at
-//! some point.
-//!
 //! #### Build script mtime handling
 //!
 //! Build script mtime handling runs in different modes. There is the "old
 //! style" where the build script does not emit any `rerun-if` directives. In
-//! this mode, Cargo will use [`LocalFingerprint::Precalculated`]. See the
-//! "rustdoc" section above how it works.
+//! this mode, Cargo will use [`LocalFingerprint::Precalculated`].
+//! For registry packages, this is the package version.
+//! For git packages, it is the git hash.
+//! For path packages, it is a string of the mtime of the newest file in the package.
+
 //!
 //! In the new-style, each `rerun-if` directive is translated to the
 //! corresponding [`LocalFingerprint`] variant. The [`RerunIfChanged`] variant
@@ -810,12 +802,11 @@ impl<'de> Deserialize<'de> for DepFingerprint {
 #[derive(Debug, Serialize, Deserialize, Hash)]
 enum LocalFingerprint {
     /// This is a precalculated fingerprint which has an opaque string we just
-    /// hash as usual. This variant is primarily used for rustdoc where we
-    /// don't have a dep-info file to compare against.
+    /// hash as usual.
     ///
-    /// This is also used for build scripts with no `rerun-if-*` statements, but
-    /// that's overall a mistake and causes bugs in Cargo. We shouldn't use this
-    /// for build scripts.
+    /// This variant is primarily used for build scripts with no `rerun-if-*`
+    /// statements, but that's overall a mistake and causes bugs in Cargo.
+    /// We shouldn't use this for build scripts.
     Precalculated(String),
 
     /// This is used for crate compilations. The `dep_info` file is a relative
@@ -1587,9 +1578,14 @@ fn calculate_normal(
     // Afterwards calculate our own fingerprint information.
     let build_root = build_root(build_runner);
     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 wants_doc_json_output = build_runner.bcx.build_config.intent.wants_doc_json_output();
+    let local = if is_any_doc_gen && wants_doc_json_output {
+        // `--emit` would reject or drop the JSON doc output,
+        // so skip it and fall back to package fingerprint for JSON doc units.
+        //
+        // If we have `--emit=json-files` available,
+        // we could pass that along with `--emit=dep-info`.
+        // see rust-lang/rust#155679
         let fingerprint = pkg_fingerprint(build_runner.bcx, &unit.pkg).with_context(|| {
             format!(
                 "failed to determine package fingerprint for documenting {}",

src/compiler/mod.rs

@@ -891,7 +891,13 @@ 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 {
+    // `--emit` would reject or drop the JSON doc output,
+    // so skip it and fall back to package fingerprint for JSON doc units.
+    //
+    // If we have `--emit=json-files` available,
+    // we could pass that along with `--emit=dep-info`.
+    // see rust-lang/rust#155679
+    if !build_runner.bcx.build_config.intent.wants_doc_json_output() {
         // html-static-files is required for keeping the shared styling resources
         // html-non-static-files is required for keeping the original rustdoc emission
         let mut arg = if build_runner.bcx.gctx.cli_unstable().rustdoc_mergeable_info {
@@ -903,13 +909,10 @@ fn prepare_rustdoc(build_runner: &BuildRunner<'_, '_>, unit: &Unit) -> CargoResu
         };
         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");
-        }
-    } else if build_runner.bcx.gctx.cli_unstable().rustdoc_mergeable_info {
-        // toolchain resources are written at the end, at the same time as merging
-        rustdoc.arg("--emit=html-non-static-files");
+    if build_runner.bcx.gctx.cli_unstable().checksum_freshness {
+        rustdoc.arg("-Z").arg("checksum-hash-algorithm=blake3");
     }
 
     if build_runner.bcx.gctx.cli_unstable().rustdoc_mergeable_info {
@@ -1009,7 +1012,6 @@ fn rustdoc(build_runner: &mut BuildRunner<'_, '_>, unit: &Unit) -> CargoResult<W
     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::for_dirty(build_runner, unit);
     let script_metadatas = build_runner.find_build_script_metadatas(unit);
@@ -1106,7 +1108,7 @@ fn rustdoc(build_runner: &mut BuildRunner<'_, '_>, unit: &Unit) -> CargoResult<W
             return Err(e);
         }
 
-        if rustdoc_depinfo_enabled && rustdoc_dep_info_loc.exists() {
+        if rustdoc_dep_info_loc.exists() {
             fingerprint::translate_dep_info(
                 &rustdoc_dep_info_loc,
                 &dep_info_loc,

src/workspace/features.rs

@@ -916,7 +916,6 @@ unstable_cli_options!(
     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)"),
     rustc_unicode: bool = ("Enable `rustc`'s unicode error format in Cargo's error messages"),
-    rustdoc_depinfo: bool = ("Use dep-info files in rustdoc rebuild detection"),
     rustdoc_map: bool = ("Allow passing external documentation mappings to rustdoc"),
     rustdoc_mergeable_info: bool = ("Use rustdoc mergeable cross-crate-info files"),
     rustdoc_scrape_examples: bool = ("Allows Rustdoc to scrape code examples from reverse-dependencies"),
@@ -1018,6 +1017,9 @@ const STABILIZED_LOCKFILE_PATH: &str = "The `lockfile-path` config key is now al
 
 const STABILIZED_WARNINGS: &str = "The `build.warnings` config key is now always available";
 
+const STABILIZED_RUSTDOC_DEPINFO: &str = "Rustdoc dep-info-based rebuild detection \
+    is now always enabled.";
+
 fn deserialize_comma_separated_list<'de, D>(
     deserializer: D,
 ) -> Result<Option<Vec<String>>, D::Error>
@@ -1424,6 +1426,7 @@ impl CliUnstable {
             "config-include" => stabilized_warn(k, "1.93", STABILIZED_CONFIG_INCLUDE),
             "lockfile-path" => stabilized_warn(k, "1.97", STABILIZED_LOCKFILE_PATH),
             "warnings" => stabilized_warn(k, "1.97", STABILIZED_WARNINGS),
+            "rustdoc-depinfo" => stabilized_warn(k, "1.99", STABILIZED_RUSTDOC_DEPINFO),
 
             // Unstable features
             // Sorted alphabetically:
@@ -1478,7 +1481,6 @@ impl CliUnstable {
             "publish-timeout" => self.publish_timeout = parse_empty(k, v)?,
             "root-dir" => self.root_dir = v.map(|v| v.into()),
             "rustc-unicode" => self.rustc_unicode = parse_empty(k, v)?,
-            "rustdoc-depinfo" => self.rustdoc_depinfo = parse_empty(k, v)?,
             "rustdoc-map" => self.rustdoc_map = parse_empty(k, v)?,
             "rustdoc-mergeable-info" => self.rustdoc_mergeable_info = parse_empty(k, v)?,
             "rustdoc-scrape-examples" => self.rustdoc_scrape_examples = parse_empty(k, v)?,