feat(unstable): add -Zrustdoc-mergeable-info

Co-authored-by: Michael Howell <michael@notriddle.com>
Co-authored-by: Weihang Lo <me@weihanglo.tw>

Author: notriddle

src/cargo/core/features.rs

@@ -884,6 +884,7 @@ unstable_cli_options!(
     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"),
     sbom: bool = ("Enable the `sbom` option in build config in .cargo/config.toml file"),
     script: bool = ("Enable support for single-file, `.rs` packages"),
@@ -1415,6 +1416,7 @@ impl CliUnstable {
             "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)?,
             "sbom" => self.sbom = parse_empty(k, v)?,
             "section-timings" => self.section_timings = parse_empty(k, v)?,

src/doc/src/reference/unstable.md

@@ -103,6 +103,7 @@ Each new feature described below should explain how to use it.
     * [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.
     * [Profile `hint-mostly-unused` option](#profile-hint-mostly-unused-option) --- Hint that a dependency is mostly unused, to optimize compilation time.
@@ -2059,6 +2060,17 @@ cargo +nightly check --compile-time-deps --all-targets -Z unstable-options
 
 Enable `rustc`'s unicode error format in Cargo's error messages
 
+## rustdoc mergeable info
+
+* Original Pull Request: [#16309](https://github.com/rust-lang/cargo/pull/16309)
+* Tracking issue: [#16306](https://github.com/rust-lang/cargo/issues/16306)
+* Tracking rustc issue: [rust-lang/rust#130676](https://github.com/rust-lang/rust/issues/130676)
+
+The `-Z rustdoc-mergeable-info` leverage rustdoc's mergeable crate info,
+so that `cargo doc` can merge cross-crate information
+(like the search index, source files index, etc.)
+from separate output directories,
+and run `rustdoc` in parallel.
 
 # Stabilized and removed features
 

tests/testsuite/cargo/z_help/stdout.term.svg

@@ -3201,3 +3201,20 @@ fn rebuild_tracks_checksum() {
     let doc_html = p.read_file("target/doc/foo/index.html");
     assert!(doc_html.contains("depinfo-after"));
 }
+
+#[cargo_test(nightly, reason = "rustdoc mergeable crate info is unstable")]
+fn mergeable_info_gated() {
+    let p = project()
+        .file("Cargo.toml", &basic_lib_manifest("foo"))
+        .file("src/lib.rs", "")
+        .build();
+
+    p.cargo("doc -Zrustdoc-mergeable-info")
+        .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();
+}