Add a new `--build-id` flag to rustc

[LukeMathWalker]

Proposal

The problem

rustdoc's JSON output for a crate must often refer to items (e.g. functions, traits, types, etc.) defined in one or more its dependencies.

Very little information is captured about those dependencies: their name and the root URL to their docs.

This causes issues when multiple versions of the same crate appear as direct dependencies (e.g. via renames) of the crate we are documenting—e.g. it becomes impossible to find out where items are coming from.

The proposed solution

Add a --build-id flag to rustc. The value would be provided by cargo and then captured as part of the .rlib metadata, which would in turn make it available to rustdoc, as well as other parts of the compiler that might benefit from it (e.g. diagnostics, such as version mismatches which currently limit themselves to perhaps two different version of CRATE_NAME are being used?).

The provided build-id must:

• Uniquely identify the crate it points to within the current workspace;
• Be a valid string for the --package flag in cargo (e.g. cargo rustdoc -p <build-id> should always work). This allows toolmakers to fetch more information on-demand when working with rustdoc's JSON output;
• Be as human-friendly as possible (e.g. use just the crate name if there is no ambiguity) in order to be used in diagnostics.

Notes

This proposal supercedes https://github.com/rust-lang/compiler-team/issues/622, incorporating the feedback and ideas that were surfaced in the associated Zulip stream.

Mentors or Reviewers

A mentor would definitely be appreciated, I never touched any of the code involved here.

Process

The main points of the [Major Change Process][MCP] are as follows:

• [x] File an issue describing the proposal.
• [ ] A compiler team member or contributor who is knowledgeable in the area can second by writing @rustbot second.
  • Finding a "second" suffices for internal changes. If however, you are proposing a new public-facing feature, such as a -C flag, then full team check-off is required.
  • Compiler team members can initiate a check-off via @rfcbot fcp merge on either the MCP or the PR.
• [ ] Once an MCP is seconded, the Final Comment Period begins. If no objections are raised after 10 days, the MCP is considered approved.

Comments

This issue is not meant to be used for technical discussion. There is a Zulip stream for that. Use this issue to leave procedural comments, such as volunteering to review, indicating that you second the proposal (or third, etc), or raising a concern that you would like to be addressed.

[rustbot]

This issue is not meant to be used for technical discussion. There is a Zulip stream for that. Use this issue to leave procedural comments, such as volunteering to review, indicating that you second the proposal (or third, etc), or raising a concern that you would like to be addressed.

cc @rust-lang/compiler @rust-lang/compiler-contributors

[estebank]

Given that this is a user visible flag (otherwise I'd just second):

@rfcbot fcp merge

[rfcbot]

Team member @estebank has proposed to merge this. The next step is review by the rest of the tagged team members:

• [ ] @Aaron1011
• [x] @cjgillot
• [x] @compiler-errors
• [ ] @davidtwco
• [x] @eddyb
• [x] @estebank
• [x] @jackh726
• [x] @lcnr
• [x] @matthewjasper
• [x] @michaelwoerister
• [x] @nagisa
• [x] @oli-obk
• [ ] @petrochenkov
• [x] @pnkfelix
• [ ] @wesleywiser

Concerns:

• option-name (https://github.com/rust-lang/compiler-team/issues/635#issuecomment-1785349936)
• other-existing-options (https://github.com/rust-lang/compiler-team/issues/635#issuecomment-1779597156)

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[petrochenkov]

@rfcbot concern other-existing-options

The zulip thread lists some alternatives like -Cmetadata, the proposal needs to describe why the existing options are not enough and why a new separate option is necessary for this.

One alternative, for example, is making -Cmetadata more extensible so it could include e.g. json with different pieces of auxiliary information like this.

[pnkfelix]

(I'm checking my box under the assumption that the implementation of this MCP will explore leveraging an extension of --metadata rather than adding a whole new --build-id flag.)

@rfcbot reviewed

[wesleywiser]

@rfcbot concern option-name

When reading the title, I assumed this was an flagthat would allow the user to choose what --build-id value is passed to the linker. I would prefer we choose a different name for this flag if we can't reuse or extend -Cmetadata as @petrochenkov suggests.

[compiler-errors]

@apiraino:

I don't think it makes sense to block this FCP on finding a mentor, unless you think the change to the compiler is so large that its acceptance should be conditional on finding someone to implement it (which seems out of the ordinary) -- IMO, the FCP is just for approval of the technical change. Also, the syntax is @rfcbot to file a concern on the FCP.

[apiraino]

@compiler-errors fair point, sorry for the noise. Just wanted to be sure that that point was't forgotten.