feat: rebuild(-ish) rustdoc json for different version of same crates by motorailgun · Pull Request #16773 · rust-lang/cargo

motorailgun · 2026-03-20T23:27:24Z

What does this PR try to resolve?

As discussed in the linked issue, cargo rustdoc --output-format=json doesn't rebuild for same crate name but with different versions. This is because current cargo implementation around rustdoc only specifies output paths/names by only its crate names, but not with version(hash) info.

This PR forces new layout for json output, and uplift the file into backward-compatible place.

How to test and review this PR?

Can we consider just forcing new layout for --output-format=json? (and stop uplifting)
Uplifting will always happen even if uplifted json is fresh, and/or new layout is manually specified. (could not figure out how to prevent); however it is just a copy operation if docs JSON are already built and fresh.

rustbot · 2026-03-20T23:27:30Z

r? @epage

rustbot has assigned @epage.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

Owners of files modified in this PR: @ehuss, @epage, @weihanglo
@ehuss, @epage, @weihanglo expanded to ehuss, epage, weihanglo
Random selection from ehuss, epage, weihanglo

motorailgun · 2026-03-26T19:15:29Z

Updated to use new directory layout.

rustbot · 2026-04-01T18:22:18Z

This PR was rebased onto a different master 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.

motorailgun · 2026-04-06T23:23:46Z

Note: updated PR message reflecting changes.

weihanglo · 2026-04-15T12:09:18Z

        }

-        let crate_dir = doc_dir.join(&crate_name);
+        let crate_dir = if is_json_output {


We don't need to clean up doc.json file for the new layout, as they are isolated by units.

That said, I do want to know how this would affect cargo clean --doc. We should at least track it in the tracking issue

View changes since the review

From my quick observation, doc.json file will escape normal cargo clean --doc operation? Will dig into tomorrow.

cargo/src/cargo/ops/cargo_clean.rs

Lines 88 to 100 in f4f977f

if opts.doc {

if !opts.spec.is_empty() {

// FIXME: https://github.com/rust-lang/cargo/issues/8790

// This should support the ability to clean specific packages

// within the doc directory. It's a little tricky since it

// needs to find all documentable targets, but also consider

// the fact that target names might overlap with dependency

// names and such.

bail!("--doc cannot be used with -p");

}

// If the doc option is set, we just want to delete the doc directory.

target_dir = target_dir.join("doc");

clean_ctx.remove_paths(&[target_dir.into_path_unlocked()])?;

Tracking issue btw: #13283

Though I feel like we probably don't need to deal with cargo clean --doc. So the behavior doesn't need to be "cleaning anything related to artifacts."

--doc This option will cause cargo clean to remove only the doc directory in the target directory.

That makes me wonder -Zrustdoc-mergeable-info also doesn't need to support cargo clean.

@ranger-ross any thoughts?

I meant, we may leave it for future. No need to worry about it now

weihanglo

Thanks for working on this!

View changes since this review

weihanglo · 2026-04-17T00:58:33Z

-            debug!("removing pre-existing doc directory {:?}", crate_dir);
-            paths::remove_dir_all(crate_dir)?;
-        }
+        if !is_json_output {


rustdoc --output-format currently only accepts one format and each option is mutually exclusive, so this check should be fine for now.

If it ever changes to accepts muliple, we'll need to update this (and this place is unlikely the only place need an update).

weihanglo · 2026-04-17T00:58:53Z

    build_runner: &BuildRunner<'_, '_>,
    rustdoc: &mut ProcessBuilder,
 ) -> CargoResult<()> {
-    let gctx = build_runner.bcx.gctx;


nit: This is a better to be a refactor commit.

weihanglo · 2026-04-17T01:00:15Z

-    assert!(!dep_json.contains("dep_v1_fn"));
-    assert!(dep_json.contains("dep_v2_fn"));
+    assert!(dep_json.contains("dep_v1_fn"));
+    assert!(!dep_json.contains("dep_v2_fn"));


Nice test that makes cargo replaces outdated uplifted content!

weihanglo · 2026-04-17T01:02:18Z

BTW, if follows conventional commit message stricter, the first commit should be test: and the second one should be fix:.

Anyway, thanks!

motorailgun · 2026-04-17T01:31:46Z

Oh, is that failing test just flaky? If so I'd love to take some time to amend the commits (messages and histories).

weihanglo · 2026-04-17T03:25:58Z

Oh, is that failing test just flaky? If so I'd love to take some time to amend the commits (messages and histories).

Yeah definitely flaky.

Feel free to amend the commits if you'd like to. I will merge this on Friday anyway before the next Cargo submodule sync in rust-lang/rust (which is probably tomorrow within 24hrs)

---- util::local_poll_adapter::tests::deferred_success stdout ----

thread 'util::local_poll_adapter::tests::deferred_success' (9550) panicked at src/cargo/util/local_poll_adapter.rs:177:9:
assertion `left == right` failed
  left: Ready(Ok(50))
 right: Pending

rustbot assigned epage Mar 20, 2026

rustbot added A-build-execution Area: anything dealing with executing the compiler A-layout Area: target output directory layout, naming, and organization S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 20, 2026

motorailgun force-pushed the rustdoc-rebuild branch 2 times, most recently from a1ef71b to 04024f4 Compare March 21, 2026 02:47

weihanglo reviewed Mar 21, 2026

View reviewed changes

Comment thread src/cargo/core/compiler/build_runner/compilation_files.rs Outdated

motorailgun force-pushed the rustdoc-rebuild branch 2 times, most recently from be69519 to 2f32d53 Compare March 26, 2026 18:45

motorailgun requested a review from weihanglo March 26, 2026 19:15

This comment has been minimized.

Sign in to view

motorailgun force-pushed the rustdoc-rebuild branch from 2f32d53 to 184bf76 Compare April 1, 2026 18:22

weihanglo reviewed Apr 1, 2026

View reviewed changes

Comment thread src/cargo/core/compiler/build_runner/mod.rs Outdated

Comment thread src/cargo/core/compiler/rustdoc.rs Outdated

Comment thread tests/testsuite/build_dir.rs

motorailgun force-pushed the rustdoc-rebuild branch 2 times, most recently from 939c055 to 79399ac Compare April 6, 2026 23:18

BMG042 approved these changes Apr 7, 2026

View reviewed changes

This comment was marked as spam.

Sign in to view

weihanglo reviewed Apr 8, 2026

View reviewed changes

Comment thread src/cargo/core/compiler/build_runner/mod.rs Outdated

Comment thread src/cargo/core/compiler/build_runner/mod.rs Outdated

Comment thread src/cargo/core/compiler/rustdoc.rs

motorailgun force-pushed the rustdoc-rebuild branch from 79399ac to be0b993 Compare April 13, 2026 22:38

motorailgun requested a review from weihanglo April 13, 2026 23:12

weihanglo reviewed Apr 15, 2026

View reviewed changes

motorailgun force-pushed the rustdoc-rebuild branch 2 times, most recently from e727c71 to 225d510 Compare April 15, 2026 14:01

chore: add tests for rustdoc json output rebuild

998be7d

motorailgun force-pushed the rustdoc-rebuild branch 2 times, most recently from 86007ed to ca752fa Compare April 16, 2026 03:12

feat: rebuild(-ish) rustdoc json for different version of same crates

9e895e1

motorailgun force-pushed the rustdoc-rebuild branch from ca752fa to 9e895e1 Compare April 16, 2026 04:19

weihanglo approved these changes Apr 17, 2026

View reviewed changes

weihanglo added this pull request to the merge queue Apr 17, 2026

github-merge-queue bot removed this pull request from the merge queue due to failed status checks Apr 17, 2026

	if opts.doc {
	if !opts.spec.is_empty() {
	// FIXME: https://github.com/rust-lang/cargo/issues/8790
	// This should support the ability to clean specific packages
	// within the doc directory. It's a little tricky since it
	// needs to find all documentable targets, but also consider
	// the fact that target names might overlap with dependency
	// names and such.
	bail!("--doc cannot be used with -p");
	}
	// If the doc option is set, we just want to delete the doc directory.
	target_dir = target_dir.join("doc");
	clean_ctx.remove_paths(&[target_dir.into_path_unlocked()])?;

Conversation

motorailgun commented Mar 20, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR try to resolve?

How to test and review this PR?

Uh oh!

rustbot commented Mar 20, 2026

Uh oh!

Uh oh!

motorailgun commented Mar 26, 2026

Uh oh!

This comment has been minimized.

rustbot commented Apr 1, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

motorailgun commented Apr 6, 2026

Uh oh!

This comment was marked as spam.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

weihanglo Apr 15, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

motorailgun Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

weihanglo Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

weihanglo Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

weihanglo left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weihanglo Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

weihanglo Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

weihanglo Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

weihanglo commented Apr 17, 2026

Uh oh!

Uh oh!

motorailgun commented Apr 17, 2026

Uh oh!

weihanglo commented Apr 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

motorailgun commented Mar 20, 2026 •

edited by rustbot

Loading

weihanglo Apr 15, 2026 •

edited by rustbot

Loading

weihanglo left a comment •

edited by rustbot

Loading