Add --print-json=... flag

[jieyouxu]

Proposal

Summary

Add an unstable --print-json={print_requests...} compiler flag which allows combining multiple print requests and outputs machine-consumable JSON lines, one line for each print request, which are more friendly for tooling.

Example output (format illustrative, exact shape/format subject to further experimentation)

$ rustc --print-json=file-names,supported-crate-types --target=wasm32-unknown-unknown -Zunstable-options
{"message-type": "print", "id": "file-names", "value": ["a.wasm", "libb.rlib"]}
{"message-type": "print", "id": "supported-crate-types", "value": ["staticlib", "lib", "bin"]}

Prior discussions:

• https://rust-lang.zulipchat.com/#narrow/channel/246057-t-cargo/topic/rustc.20--print-json.20shape/with/511298091
• https://rust-lang.zulipchat.com/#narrow/channel/131828-t-compiler/topic/Proposal.3A.20.60--print.3Dsupported-crate-types.60/near/508828584
• https://rust-lang.zulipchat.com/#narrow/channel/131828-t-compiler/topic/Print.20stability.20guarantees.20and.20the.20lack.20thereof/with/507979581
• https://rust-lang.zulipchat.com/#narrow/channel/131828-t-compiler/topic/Improving.20communication.20interface.20between.20cargo.2Frustc/with/492539201

Motivation: make (multiple) print request output more tool-friendly

Presently, rustc --print=print_request_1,print_request_2 will simply concatenate the output of both print requests with no clear delimitation. For instance, cargo has to resort to using a ___ crate name hack to delimit output between e.g. --print=split-debuginfo and --print=cfg for the same rustc invocation (as cargo wants to avoid incurring multiple rustc invocation overhead).

            process.arg("--print=sysroot");
            process.arg("--print=split-debuginfo");
            process.arg("--print=crate-name"); // `___` as a delimiter.
            process.arg("--print=cfg");

Properly outputting multiple JSON lines will clearly delimit output between multiple print requests and thus allow cargo to not need this hack (for newer rustc versions that has --print-json).

JSON lines are also more tooling friendly, as tools can use e.g. serde_json to derive deserializers for print request output, instead of having to invent/implement adhoc parsers for different print requests that outputs slightly different formats (where we don't have clearly stated stability guarantees re. their output formats or content).

Stability guarantees and the lack thereof

The message container "shape"

The "skeleton" message container shape of {"message-type": "print", "id": "$print-request-name", "value": /* form-differs-per-print-request */ } would be guaranteed stable.

This is subject to further bikeshedding/design/experimentation.

Shape of individual print requests

The stability of the shape of the value (of the message container above; i.e. print request output) is delegated to individual print requests.

Unstable print requests

Given multiple print requests (e.g. --print-json=p1,p2), -Z unstable-options will be required if any print requests are unstable (usual print request stability apply).

Valid values / output of individual print requests

Delegated to individual print requests.

Alternative: --error-format=json + --print=...?

I have considered using existing --error-format=json + --print=... to encode --print-json=.... However, the flag is error-format, which IMO is confusing because print requests are arguably not error messages.

Path to stabilization

This will need to go through some experimentation to determine if the output shape is tool-friendly and iron out possible quirks.

A proposal for stabilization of this flag will need to go through usual compiler FCP progress.

Special attention should be paid to figuring out and documenting the stability guarantees surrounding the output shape/format of this flag, and its interactions with individual print request stability guarantees.

Unresolved questions

• What about other output formats?
  • Honestly, I think just pick one. JSON is tool-friendly enough and arguably more common than say TOML or YAML or whatever. I don't think we want to invent our own either.

Mentors or Reviewers

@bjorn3, @Urgau or compiler
cc @weihanglo and @epage as we discussed what cargo needs regarding print requests.

Process

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

• 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.

You can read more about Major Change Proposals on forge.

[rustbot]

Important

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.

Concerns or objections can formally be registered here by adding a comment.

@rfcbot concern reason-for-concern
<description of the concern>

Concerns can be lifted with:

@rfcbot resolve reason-for-concern

See documentation at https://forge.rust-lang.org

cc @rust-lang/compiler

[jieyouxu]

@rfcbot concern duplicate-flag-impl-and-docs

I don't think introducing a whole new CLI option is necessary and advisable, it will just IMO duplicate the code and documentation for no reason, especialy since I think all print options should eventually support the JSON output.Urgau: Something like a "parameter" :json at the end of the print option should do it, eg. --print=crate-name:json

-- #t-compiler/major changes > Add `--print-json=...` flag compiler-team#860 @ 💬