diff --git a/doc/book/src/reference/unstable.md b/doc/book/src/reference/unstable.md index 80599ba093c..1194ec71ba5 100644 --- a/doc/book/src/reference/unstable.md +++ b/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. diff --git a/src/compiler/fingerprint/mod.rs b/src/compiler/fingerprint/mod.rs index a5d75aee4cc..81640f3ce33 100644 --- a/src/compiler/fingerprint/mod.rs +++ b/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 {}", diff --git a/src/compiler/mod.rs b/src/compiler/mod.rs index 18b5179f13a..665b6d80366 100644 --- a/src/compiler/mod.rs +++ b/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, unit: &Unit) -> CargoResult = ("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>, 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)?, diff --git a/tests/testsuite/cargo/z_help/stdout.term.svg b/tests/testsuite/cargo/z_help/stdout.term.svg index f8f602766b3..4910b0b1077 100644 --- a/tests/testsuite/cargo/z_help/stdout.term.svg +++ b/tests/testsuite/cargo/z_help/stdout.term.svg @@ -1,4 +1,4 @@ - +