Repository navigation
rustdoc-json: multiple package versions clobber their output paths #142370
Description
Rustdoc uses crate name as a base for file names (target/doc/$name.json), but this naming scheme is incompatible with Cargo projects where names are not unique, and multiple different crates can have the same name.
[package]
name = "exampledoc" # try `name = "wild"` for extra difficulty
edition = "2024"
[dependencies]
old = { package = "wild", version = "1" }
new = { package = "wild", version = "2" }pub use ::old;
pub use ::new;RUSTDOCFLAGS="-Z unstable-options --output-format=json" cargo +nightly docThis ends up writing target/doc/wild.json for only one of the two versions. The same problem can happen if Cargo has git, path, or custom registry dependencies that use names overlapping with crates-io dependencies, so even name + version isn't unique.
Using the package alias (new and old in this example) wouldn't be sufficient, because these aliases aren't globally unique either. Different crates in the same dependency tree can rename different deps to the same name.
cargo 1.89.0-nightly (fc1518ef0 2025-06-06)
Activity
bjorn3 commentedon Jun 11, 2025
Doesn't the same happen for the html docs?
kornelski commentedon Jun 11, 2025
Yes, the same happens to HTML docs, but the trade-offs are different for JSON.
JSON is consumed by tooling like
cargo-semver-checks, which doesn't need the paths to be pretty and URL-safe, but needs the data to be reliable and unambiguous.I think for tooling a relatively simple and robust solution would be to place the json files next to their
.rmetafiles. Rustdoc gets args like:and could write:
These
rmetapaths are present in--message-format=jsonoutput ofcargo doc, and could be used to map back to Cargo's uniquepkgid.aDotInTheVoid commentedon Jun 11, 2025
CC @obi1kenobi @LukeMathWalker
obi1kenobi commentedon Jun 11, 2025
My top concern is not accidentally blocking the work on cross-crate rustdoc JSON linking by a change made here. At RustWeek we discussed a variety of options about that, some of which also involved
.rmetaand--message-format=json, and I worry that we might accidentally make mutually-incompatible choices that may be hard to reverse.From
cargo-semver-checks' perspective, the clobbering is a known issue that doesn't affect us at all at the moment. It'll obviously be a bigger concern once we have multiple rustdoc JSON files to connect, which is why in my mind this issue is a sub-issue of that bigger piece of work.LukeMathWalker commentedon Jun 12, 2025
Naming collisions in
rustdoc-jsonare a known (and annoying) issue for Pavex.The downsides are multiple:
cargo's caching logic since it can confuse the docs for two different versions of the same crate thus skipping a recompute that would instead be needed.rustdoc's JSON docs is by far the task we spend most time on.Having said all that, I agree with @obi1kenobi—I believe we should strive for a structural solution that we aim to stabilize, while taking into account the other ambiguity issue we're dealing with in
rustdoc-json. The two things don't necessarily have to be solved by the same mechanism, but I'd like to have a shared agreement as to what the two solutions will look like to confirm they're compatible before moving on either one.Specifically on the
.rmetaproposal: assuming that tooling can be informed bycargoas to what path will be used (via--message-format=json, I assume?), I think this would be viable.My only concern would be in using a naming scheme that's highly not-human-friendly. It's not an issue for
.rmeta, since they are an intermediate build artifact, but I consider the JSON documents to be output artifacts. Nonetheless, they're geared towards tooling consumers, so that may not be a significant issue.