rust-lang / rust-lang/rust

rustdoc-json: multiple package versions clobber their output paths

Open
#142,370 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-rustdoc-json C-bug T-rustdoc
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

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 doc

This 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)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the collision with the provided Cargo project and RUSTDOCFLAGS command, then trace rustdoc JSON output-path handling from the generated target/doc files. Investigate how dependency identity is represented for crates.io, git, path, and custom registry dependencies; done means distinct outputs are produced without clobbering when package names overlap.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.