Tracking Issue for `-Zrustdoc-mergeable-info`

[weihanglo]

Summary

RFC: rust-lang/rfcs#3662 (rustdoc focused)
rust-lang/rust issue: rust-lang/rust#130676
Implementation: #16167 (WIP)
Documentation: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#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) from separate output directories, run rustdoc in parallel, and avoid (sometimes) unexpected documentation merge.

Unresolved Issues

• How to expose this feature in Cargo?
  • It would be a breaking change, as cargo doc already exposes the legacy rustdoc --merge=shared behavior (rustdoc artifacts are additive)
  • If Cargo provides a flag, say --config doc.merge=on|off, how to deal with that user switching between doc.merge=off and doc.merge=on? Should the pre-existing HTML file be kept or removed?
• Should rustdoc --merge=finalize be modeled in Cargo's "unit of execution" model
  • Currently in Cargo, a unit in the unit graph is tied to a Command execution, for example rustc or rustdoc. rustdoc --merge=finialize is apparently a "unit of execution". However, the current Unit struct is designed for compiler invocation, which have features, rustflags and Cargo target information. If we don't model this invocation in unit of work model, a special rebuild detection mechanism may need to be implemented. It might be worth a refactor if we want to support both this and Support -Zno-link #9019, and perhaps doctest execution in the future.
• Should all RUSTFLAGS apply to rustdoc --merge=finalize call?
  • Some probably only need to pass to the --merge=finalize invocation, like --extend-css?
• crate-info JSON file name collision. Same as below
  • rustdoc-json: multiple package versions clobber their output paths rust#142370
  • cargo rustdoc --output-format=json sometimes doesn't rebuild for different versions of same crate name. #16291

Future Extensions

No response

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.