rustdoc: Tracking issue for mergeable cross-crate info

@EtomicBomb

This is a tracking issue for the RFC "Mergeable rustdoc cross-crate info" (rust-lang/rfcs#3662).

Note

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.
Instead, open a dedicated issue for the specific matter or post in the #t-rustdoc Zulip channel.

Discussion comments will get marked as off-topic or deleted.
Repeated discussions on the tracking issue may lead to the tracking issue getting locked.

Steps

Implement the RFC (rustdoc rfc#3662 changes under unstable flags #129337)
- Implement the RFC in Cargo
Add documentation (to Rustdoc Book) -- cc @EtomicBomb
- rustdoc: make mergeable crate info more usable #148234
Stabilization PR (see instructions on rustc-dev-guide)

Unresolved Questions

Consider removing --merge=shared and only allow it by not providing a --merge flag. This would allow removing the implementation of shared CCI later, once Cargo uses mergeable CCI. Mergeable rustdoc cross-crate info rfcs#3662 (comment)
- resolved: We removed --merge altogether, and it's inferred from the presence of the flags for which dirs to read/write from.
What happens if two rustdoc invocations have the same --write-doc-meta-dir directory? Fix, simplify, and document doc meta finalize mode #159473 (comment)

Implementation history

rustdoc-search: add an integration test for CCI

Rollup merge of rust-lang#148186 - notriddle:test-cci, r=GuillaumeGom…

Unrolled build for #148186

rustdoc-search: add an integration test for CCI

Rollup merge of #148186 - notriddle:test-cci, r=GuillaumeGomez,jieyouxu

Rollup merge of rust-lang#148234 - notriddle:doc-cci, r=GuillaumeGomez

Unrolled build for #148234

Rollup merge of #148234 - notriddle:doc-cci, r=GuillaumeGomez

Might be worth speeding things up. Opening a zulip thread.

@rust-lang/cargo is the current design good enough for your team as well? Rustdoc is planning to stabilize it so we'd like to confirm with you it's ok before doing so.

There is some investigation we still need to do around rebuild tracking.

Currently, the build output for our rustdoc step directly outputs to the artifact directory. If there is any change, the whole thing needs to run. Nothing can be cached. Mergeable information is a little different in that we need to track it independent of the artifact directory but it is generated by the same step as the artifact directory. This can lead to bugs with rebuild detection.

In discussing this, it got us thinking about a more ideal setup and wanted to see what people's thoughts were. When we build binaries, each build unit has an independent piece of information that can be tracked and cached on its own. We don't make any global changes until link time. If rustdoc could go a step further than mergeable information and could generate a unit of information at each step and then only generate HTML at the end, this would align a lot better with caching and rebuild tracking. For example one way this could be done is if rustdoc's HTML renderer was built as a facade over the json output. Each package's build step would generate a json dump and then the final rustdoc call would load the specified json and generate the HTML for them.

If rustdoc could go a step further than mergeable information and could generate a unit of information at each step and then only generate HTML at the end, this would align a lot better with caching and rebuild tracking. For example one way this could be done is if rustdoc's HTML renderer was built as a facade over the json output. Each package's build step would generate a json dump and then the final rustdoc call would load the specified json and generate the HTML for them.

If I understand correctly when using mergeable cross-crate info, cargo can just tell each rustdoc invocation to put the html files in a separate directory with --out-dir and only at the end in the same step that does rustdoc --merge=finalize hardlink all those html files together into the doc output directory. Are you asking for rustdoc to ignore --out-dir entirely when doing --merge=none and put the html files in --parts-out-dir instead and have --merge=finalize copy all html files into the --out-dir?

If I understand correctly when using mergeable cross-crate info, cargo can just tell each rustdoc invocation to put the html files in a separate directory with --out-dir and only at the end in the same step that does rustdoc --merge=finalize hardlink all those html files together into the doc output directory. Are you asking for rustdoc to ignore --out-dir entirely when doing --merge=none and put the html files in --parts-out-dir instead and have --merge=finalize copy all html files into the --out-dir?

Rustdoc output are generally opaque to Cargo, as it has its own merge rules. The above approach sounds doable, but want to confirm with t-rustdoc if there is any caveat or limitations.

@GuillaumeGomez

@rust-lang/cargo is the current design good enough for your team as well? Rustdoc is planning to stabilize it so we'd like to confirm with you it's ok before doing so.

@GuillaumeGomez this is my little wish, not a blocker

rustdoc: follow-up work for --emit=toolchain-shared-resources #83784 (comment)

I opened #152902 to stabilize the options.

cargo can just tell each rustdoc invocation to put the html files in a separate directory with --out-dir and only at the end in the same step that does rustdoc --merge=finalize hardlink all those html files together into the doc output directory

The performance of my naive hardlink implementation (weihanglo/cargo#87) doesn't seem good enough to cross the line. The hardlink part on M1 macbook (APFS) took 1minute for hardlinking 305 crate docs with 75k files. It was a similar benchmark like the one in rust-lang/cargo#16309. The other issue of Cargo doing hardlinks is that rustdoc knows how to maintain the out-dir while Cargo doesn't. For example, in this test rustdoc would clean up pre-existing doc for crate with duplicate names. Cargo also doesn't know under out-dir, what are inside src/ or other directories.

We should see if there is some way to automatically run our rustdoc-html testsuite on both legacy-shared CCI and mergeable CCI.

tools: document arch/chips crates against their real targets, merge i…

Dogfood: #163582

Searching for ast::Attribute in rustc: https://doc.rust-lang.org/nightly/nightly-rustc/?search=ast%3A%3Aattribute

Navigation Menu

Repository navigation

rustdoc: Tracking issue for mergeable cross-crate info #130676

Steps

Unresolved Questions

Implementation history

4 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

rustdoc: Tracking issue for mergeable cross-crate info #130676

Description

Steps

Unresolved Questions

Implementation history

Activity

4 remaining items

GuillaumeGomez commented on Jan 28, 2026

GuillaumeGomez commented on Feb 9, 2026

epage commented on Feb 9, 2026

bjorn3 commented on Feb 9, 2026

weihanglo commented on Feb 10, 2026

weihanglo commented on Feb 10, 2026

GuillaumeGomez commented on Feb 20, 2026

weihanglo commented on Mar 20, 2026

camelid commented on Aug 7, 2026

notriddle commented on Oct 3, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions