bootstrap: Enable rustdoc mergeable CCI for std and internal docs by camelid · Pull Request #160098 · rust-lang/rust

camelid · 2026-07-28T18:17:41Z

This feature is unstable but will be stabilized soon, and this is a good way of dogfooding it to make sure it works properly. It should have no effect on the generated docs, but it provides a significant speedup. For example, I measure a 3x speedup locally (3m 11s -> 1m 1s) for x doc src/tools -- note that this is with the latest rustdoc perf improvements (#159854).

r? @Kobzol

rustbot · 2026-07-28T18:17:46Z

Kobzol is not on the review rotation at the moment.
They may take a while to respond.

Kobzol · 2026-07-28T18:19:23Z

Let's try the main x64 Linux dist job, I will compare the docs build time before/after.

Btw, it would be nice to add a comment on top of the added argument, which explains why is it there.

@bors try jobs=dist-x86_64-linux

bootstrap: Enable rustdoc mergeable CCI for std and internal docs try-job: dist-x86_64-linux

camelid · 2026-07-28T19:36:10Z

@GuillaumeGomez @notriddle do you think this failure is due to a bug in mergeable CCI? It's a little weird because it seems to pass on LLVM 22.2 but not 22.1 -- so could be spurious? But it's suspicious that it's related to the search index.

Kobzol · 2026-07-28T19:37:40Z

I kinda doubt it is spurious. However, bootstrap does a lot of weird crimes related to the created and removal of various doc things being built in the build directory, could be caused by that. I'll take a look at it tomorrow.

camelid · 2026-07-28T19:40:03Z

Yes, I suspect it's a bug in rustdoc. It looks like the LLVM 22.2 CI disables js-std tests.

camelid · 2026-07-28T20:35:05Z

Looks like it's actually a cargo bug, where cargo isn't passing the --resource-suffix to the final merge step. Actually cargo isn't passing the RUSTDOCFLAGS at all. We should probably pass the same flags to the final merge invocation as to each crate's rustdoc invocation. This conflates two somewhat different things, but we already share the same flags across all crates so sharing it with the merge makes sense I think. Working with @weihanglo on a fix in cargo.

rust-bors · 2026-07-28T20:36:31Z

💔 Test for bf99269 failed: CI. Failed job:

try - dist-x86_64-linux (web logs, enhanced plaintext logs)

camelid · 2026-07-28T20:49:29Z

cc rust-lang/cargo#17269

Kobzol · 2026-07-28T21:38:44Z

The try build failure looks like it might be some different error, maybe related to some cursedness when documenting the standard library?

##[group]Documenting stage1 library{alloc, compiler_builtins, core, panic_abort, panic_unwind, proc_macro, profiler_builtins, rustc-std-workspace-core, std, std_detect, sysroot, test, unwind} in JSON format (stage1 -> stage1, x86_64-unknown-linux-gnu)
warning: output filename collision at /checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/dist/build/alloc/4e4894d7dbb95523/out/alloc.json
  |
  = note: the lib target `alloc` in package `alloc v0.0.0 (/checkout/library/alloc)` has the same output filename as the lib target `alloc` in package `alloc v0.0.0 (/checkout/library/alloc)`
  = note: this is a known bug where multiple crates with the same name use the same path; see <https://github.com/rust-lang/cargo/issues/6313>

weihanglo · 2026-07-28T21:55:13Z

Looks like it's actually a cargo bug, where cargo isn't passing the --resource-suffix to the final merge step. Actually cargo isn't passing the RUSTDOCFLAGS at all.

This is an unresolved question. See rust-lang/cargo#17269 (comment)

camelid · 2026-07-29T18:39:15Z

Came across another issue. Currently, when building compiler/tool docs, we do separate cargo invocations but have them all end up in the same output directory. So that rustc, rustdoc, cargo, clippy, etc. all share one docs site (/nightly/nightly-rustc). This works out of the box with legacy shared CCI because rustdoc updates the finalized artifacts with each build. However, with shared CCI, we run one finalize per docs target (i.e. one for rustc, one for rustdoc, one for clippy, etc.), which causes the CCI (crates.js, search-index, etc.) to be overwritten.

I'm not sure what the best fix for this is. Ideally, we would probably have bootstrap tell Cargo to not run finalize for the intermediate targets and just do one finalize at the end. It also suggests that enabling mergeable CCI by default in Cargo is a moderately breaking change for workflows that depend on separate cargo doc invocations working well together.

camelid · 2026-07-29T18:40:08Z

@notriddle @weihanglo do you have any thoughts about the above issue?

weihanglo · 2026-07-29T18:54:08Z

@camelid #160098 (comment)

Came across another issue. Currently, when building compiler/tool docs, we do separate cargo invocations but have them all end up in the same output directory. So that rustc, rustdoc, cargo, clippy, etc. all share one docs site (/nightly/nightly-rustc). This works out of the box with legacy shared CCI because rustdoc updates the finalized artifacts with each build. However, with shared CCI, we run one finalize per docs target (i.e. one for rustc, one for rustdoc, one for clippy, etc.), which causes the CCI (crates.js, search-index, etc.) to be overwritten.

I'm not sure what the best fix for this is. Ideally, we would probably have bootstrap tell Cargo to not run finalize for the intermediate targets and just do one finalize at the end. It also suggests that enabling mergeable CCI by default in Cargo is a moderately breaking change for workflows that depend on separate cargo doc invocations working well together.

Haven't checked how bootstrap builds docs, though I think it should just work, as cargo doc is additive (in order to follow how rustdoc works and keep backward-compat): https://github.com/rust-lang/cargo/blob/9c930d9f8d5ec08afd4bd69dbdcba2a336fbefe3/tests/testsuite/doc.rs#L3773-L3913

It might be possible that bootstrap is using -Zskip-rustdoc-fingerprint. See also rust-lang/cargo#9404

View changes since the review

Bootstrap is in fact using -Zskip-rustdoc-fingerprint. However, I think the issue is more fundamental than that because rustdoc assumes that finalize is always run exactly once per doc site. If you run finalize for rustc and then for a tool, it will just overwrite the shared files for rustc with ones specific to the tool.

Not sure. I thought the feature was additive hence the test in Cargo (it ran cargo doc -p foo then -p dep and then -p bar sequentially).

If it were not they Cargo probably can't ship it as a default for backward compatibility reasons.

What are those shared files being overwritten? Were they safe-from-overwrite previously without -Zrustdoc-mergeable-info?

The cargo test doesn't actually check the contents of the shared files as far as I can tell. Rustdoc is still additive for the crate docs (e.g. foo/struct.Bar.html will not be overwritten). But with mergeable CCI, sequential cargo doc invocations will clobber the shared files like the search index.

The shared files were deserialized, updated, and reserialized on every single rustdoc invocation before. With mergeable CCI, each crate's contribution to the CCI is serialized separately and the merge step combines them all into the final shared files. One possible fix for this backcompat issue is that the merge step could check for any existing shared files in the output directory and use those as the basis for its merge step. It would be nice to avoid that if we can though and have the merge be authoritative rather than being invoked any number of times.

notriddle · 2026-07-29T18:58:28Z

However, with shared CCI, we run one finalize per docs target (i.e. one for rustc, one for rustdoc, one for clippy, etc.), which causes the CCI (crates.js, search-index, etc.) to be overwritten.

As long as the same Cargo build directory is used for all three of these builds, that isn’t supposed to be a problem. The feature implements --doc-meta-dir as a directory specifically so that this can still work.

Did you try the feature and have it not work?

camelid · 2026-07-29T19:02:14Z

Yes, I tried this branch locally with e.g. x doc src/tools/rustdoc, and the crates.js file and search index are both broken. Crate documentation exists for all the rustc crates, but they are not in the crates.js file or search index.

camelid · 2026-07-29T19:03:48Z

The specific problem is that merging assumes it is given all meta-dir inputs and does not import existing finalized outputs. Since bootstrap invokes cargo doc on rustc separately from each of the tools, we run the merge step for each one, without providing meta-dir inputs from the other invocations.

weihanglo · 2026-07-29T19:04:06Z

Yes, I tried this branch locally with e.g. x doc src/tools/rustdoc, and the crates.js file and search index are both broken. Crate documentation exists for all the rustc crates, but they are not in the crates.js file or search index.

That may be due to skipping rustdoc-fingeprint. The fingerprint file tracks previous rustdoc run in order to collect all mergeable info across multiple cargo doc invocations.

camelid · 2026-07-29T19:08:17Z

Hmm, so what is in rustdoc-fingerprint? Does it include all the meta dirs that were generated along the way?

camelid · 2026-08-06T15:21:59Z

@weihanglo the index.html, settings.html, and some other root pages were not generated when doc merge finalize was run as a separate step. So that PR fixes it.

This feature is unstable but will be stabilized soon, and this is a good way of dogfooding it to make sure it works properly. It should have no effect on the generated docs, but it provides a significant speedup. For example, I measure a 3x speedup locally (3m 11s -> 1m 1s) for `x doc src/tools` -- note that this is with the latest rustdoc perf improvements (PR 159854).

rustbot · 2026-08-06T15:25:02Z

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

camelid · 2026-08-06T15:25:40Z

Will start a try job once CI passes. Or if you get to it before me, please run @bors try jobs=dist-x86_64-linux.

Kobzol · 2026-08-06T15:25:51Z

@bors try

bootstrap: Enable rustdoc mergeable CCI for std and internal docs

camelid · 2026-08-06T15:26:09Z

@Kobzol isn't that the wrong try job?

Kobzol · 2026-08-06T15:27:05Z

It is 😆 Thanks.

@bors try jobs=dist-x86_64-linux

bootstrap: Enable rustdoc mergeable CCI for std and internal docs try-job: dist-x86_64-linux

rust-bors · 2026-08-06T15:33:05Z

💔 Test for 7d8ef04 failed: CI. Failed job:

Calculate job matrix (web logs, enhanced plaintext logs)

camelid · 2026-08-06T15:33:42Z

Good ol' GitHub Actions... seems like there's some 500s.

camelid · 2026-08-06T22:39:02Z

Oh, wait, I guess we still need to fix the issue caused by bootstrap's weird symlinking of different doc directories. @notriddle is working on a patch.

We never run `x check` on RustcDoc. We only use it for docs.

camelid · 2026-08-07T18:01:59Z

@bors try jobs=dist-x86_64-linux

bootstrap: Enable rustdoc mergeable CCI for std and internal docs try-job: dist-x86_64-linux

rust-bors · 2026-08-07T20:24:01Z

💔 Test for 661fd6f failed: CI. Failed job:

try - dist-x86_64-linux (web logs, enhanced plaintext logs)

camelid · 2026-08-07T21:11:58Z

I wonder if it makes sense to split off another PR that enables the feature just for std -- that way we can start dogfooding it before the whole bootstrap mess is fixed?

GuillaumeGomez · 2026-08-07T21:13:02Z

I tend to prefer incremental over "all at once" but up to you.

I know that this change causes `doc` to build compiler stuff before building docs for bootstrap. This just reduces the combinatorics that we have to deal with.

rust-log-analyzer · 2026-08-08T00:27:21Z

The job aarch64-gnu-llvm-21-1 failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

##[endgroup]
Doc path: /checkout/obj/build/aarch64-unknown-linux-gnu/doc/alloc/index.html
[TIMING:end] doc::Std { build_compiler: Compiler { stage: 2, host: aarch64-unknown-linux-gnu, forced_compiler: false }, target: aarch64-unknown-linux-gnu, format: Html, crates: [] } -- 59.222
##[group]Testing stage2 rustdoc-js-std (aarch64-unknown-linux-gnu)
Error: ENOENT: no such file or directory, open '/checkout/obj/build/aarch64-unknown-linux-gnu/doc/search.index/root1.99.0.js'
    at Object.readFileSync (node:fs:449:20)
    at readFile (/checkout/src/tools/rustdoc-js/tester.js:30:15)
    at Object.loadRoot (/checkout/src/tools/rustdoc-js/tester.js:468:32)
    at /checkout/obj/build/aarch64-unknown-linux-gnu/doc/static.files/stringdex-b5109af9.js:2:24000
    at new Promise (<anonymous>)
    at Object.loadDatabase (/checkout/obj/build/aarch64-unknown-linux-gnu/doc/static.files/stringdex-b5109af9.js:2:23870)
    at Object.initSearch (/checkout/obj/build/aarch64-unknown-linux-gnu/doc/static.files/search-cf4fc35e.js:5:12018)
    at loadSearchJS (/checkout/src/tools/rustdoc-js/tester.js:458:57)
    at main (/checkout/src/tools/rustdoc-js/tester.js:628:34)
    at Object.<anonymous> (/checkout/src/tools/rustdoc-js/tester.js:656:1) {
  errno: -2,
  code: 'ENOENT',
  syscall: 'open',
  path: '/checkout/obj/build/aarch64-unknown-linux-gnu/doc/search.index/root1.99.0.js'
}
Bootstrap failed while executing `--stage 2 test --skip tidy --skip intrinsic-test --skip compiler --skip src`
Currently active steps:
test::RustdocJSStd { build_compiler: Compiler { stage: 2, host: aarch64-unknown-linux-gnu, forced_compiler: false }, target: aarch64-unknown-linux-gnu } at src/bootstrap/src/core/build_steps/test.rs:1332
Command `/usr/bin/node /checkout/src/tools/rustdoc-js/tester.js --crate-name std --resource-suffix 1.99.0 --doc-folder /checkout/obj/build/aarch64-unknown-linux-gnu/doc --test-folder /checkout/tests/rustdoc-js-std` failed with exit code 1
Created at: src/bootstrap/src/core/build_steps/test.rs:1341:27
Executed at: src/bootstrap/src/core/build_steps/test.rs:1382:17

Command has failed. Rerun with -v to see more details.
Build completed unsuccessfully in 0:43:58
  local time: Sat Aug  8 00:27:09 UTC 2026
  network time: Sat, 08 Aug 2026 00:27:09 GMT
##[error]Process completed with exit code 1.
##[group]Run echo "disk usage:"

rustbot assigned Kobzol Jul 28, 2026

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-bootstrap Relevant to the bootstrap subteam: Rust's build system (x.py and src/bootstrap) labels Jul 28, 2026