feat(rustdoc): stabilize --emit flag

[weihanglo]

TODO: stabilization report?

r? rustdoc

[weihanglo]

Questions:

• Do we want to stabilize also unversioned-shared-resources option? It currently does nothing AFAIK.
• Do we want a stabilization report?
• How many details do we want to put in doc?

[weihanglo]

cc @aDotInTheVoid since you've involved in the PR removing the last blocker :)

[GuillaumeGomez]

We discussed on today's rustdoc meeting. Before going any further, we will investigate exactly what each --emit option does exactly to have a clearer picture of what's actually needed and also to add missing documentation.

[weihanglo]

We discussed on today's rustdoc meeting. Before going any further, we will investigate exactly what each --emit option does exactly to have a clearer picture of what's actually needed and also to add missing documentation.

Thanks for it!

This PR contains a doc based on my understanding and the history of these options, but I am not 100% sure if that is correct

[fmease]

I haven't read this yet but here are probably some very important and relevant considerations: #83784.

[weihanglo]

For the use case in Cargo, we actually don't need anything other than dep-info. The originak ask was here: #t-rustdoc > Plan to stabilize `--emit=dep-info[=path]` @ 💬:

One thing that might be a blocker: rust-lang/cargo#15605

Do we want to stabilize the --emit flag with all the emit types, or just dep-info? At this moment it is required for cargo to pass --emit=toolchain-shared-resources,invocation-specific,dep-info=<PATH> in order to make the generated doc look good and styled.

I guess one way forward is that rustdoc provides an extra emit type, say, default. So that cargo can run --emit=default,dep-info=/path/to/foo.d without even considering those other options. And in rustdoc documentation we can state that the default emit type is whatever the default emits rustdoc is doing. Pretty much like --remap-path-scope=all:

all - an alias for all of the above, also equivalent to supplying only --remap-path-prefix without --remap-path-scope.

[notriddle]

I've opened #148180, a follow-up that removes the no-op unversioned-shared-resources, which hasn't done anything ever since we switched to using hashes for cache busting.

[weihanglo]

This PR has updated and removed the unversioned-shared-resources option, which was removed in #148180

View changes since this review

[notriddle]

I haven’t found any more problems with this feature (that don’t involve its interaction with other unstable features).

I think it can be stabilized in its current form.

[GuillaumeGomez]

@rfcbot fcp merge rustdoc

[rust-rfcbot]

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

• @GuillaumeGomez
• @Manishearth
• @aDotInTheVoid
• @camelid
• @fmease
• @lolbinarycat
• @notriddle
• @yotamofek

Concerns:

• interaction-with-other-modes (feat(rustdoc): stabilize --emit flag #146220 (comment))
• naming (feat(rustdoc): stabilize --emit flag #146220 (comment))
• outdir-not-honored resolved by feat(rustdoc): stabilize --emit flag #146220 (comment)
• tiny-stab-report (feat(rustdoc): stabilize --emit flag #146220 (comment))

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.

[yotamofek]

Not sure whether these triple-dashes are considered standard :)

[weihanglo]

It's a mdbook stuff. Not sure about rustdoc but Cargo book uses that everywhere

https://rust-lang.github.io/mdBook/format/markdown.html#smart-punctuation

[rustbot]

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

[fmease]

@rfcbot reviewed

Do we want a stabilization report?

I'd like to have a tiny stabilization report, just a few sentences esp. around the motivation would be great. For example, it's unclear to me right now whether Cargo is only interested in --emit=dep-info or if it also cares about the other two options toolchain-shared-resources & invocation-specific or rather the mechanism they enable, namely suppressing the emission of invocation-specific artifacts (via --emit=toolchain-shared-resources (sic!)) and shared resources (via --emit=invocation-specific (sic!)). That'd be useful to know imo.

@rfcbot concern tiny-stab-report

I've noticed that --emit=depinfo (i.e., default path) doesn't put the *.d file into the outdir but instead in the CWD. rustc does put in in the CWD by default but that's because the default outdir is the CWD. However, for rustdoc it's doc/. If you give rustc an --outdir=<DIR> it does put the *.d file into <DIR> while rustdoc completely ignores --outdir=<DIR> for depinfo.

Could we please honor the outdir?

@rfcbot concern outdir-not-honored

(minor bikeshedding) Re. the naming of toolchain-shared-resources and invocation-specific, it feels slightly off to me. I'll retract my concern immediately if everyone else is fine with these terms.

E.g., seeing the word toolchain in the context of the rustdoc binary seems a bit "weird". The (often rustup) toolchain is the set of rustc+rustdoc+docs+other components, they live at different level of abstraction? version-specific-shared-resources feels more natural, maybe? Although at this point, I'd just go with shared-resources. Isn't it obvious that these shared resources aren't stable across versions? If we hypothetically had a "stable rustdoc ABI", stable-shared-resources would do the trick, wouldn't it?

Re. --emit=invocation-specific, we're emitting an adjective here. I know, this is pure bikeshedding at this point and a noun like invocation-specific-data is hardly better?

@rfcbot concern naming

Lastly, what should we do if the user passes (stable) --test or (unstable) --output-format=doctest? Or if the user passes a *.md Markdown file to rustdoc (stable)? At the moment, --emit=dep-info doesn't emit any *.d file in these three cases because they take completely different execution paths in rustdoc. I'm leaning towards rejecting --emit=dep-info in these cases or is that too strict / artificially restricted? Or do we want to follow rustc's example: Under --test --emit=dep-info it doesn't generate any (test) binary, it only emits a *.d file.

@rfcbot concern interaction-with-other-modes

---

The following isn't an official concern and only tangentially related. I'm wondering whether --output-format=doctests (#134529) should actually be --emit=doctests. I'd also like to CC the proposed --print (#151618, print requests like rustc) for visibility, too. They're distinct but quite similar (I guess print requests are completely non-normal execution and emissions "happen on the side" during normal execution but they can also make execution halt early?).

[fmease]

(non-blocking, just some impl cleanups we should do at some point)

1. Under --emit=dep-info and --emit=invocation-specific rustdoc still generates an empty <OUTDIR>/static.files/ directory.
2. On unknown emission/output types rustdoc doesn't list all legal types in the error diagnostic unlike rustc.

[notriddle]

Re. the naming of toolchain-shared-resources and invocation-specific, it feels slightly off to me.

toolchain-shared-resources should probably be called static-files, because that's the name of the directory that it actually emits.

test-dingus % ls
lib.rs
test-dingus % rustdoc +nightly --emit=toolchain-shared-resources -Zunstable-options lib.rs
test-dingus % ls
doc	lib.rs
test-dingus % ls doc
static.files

Maybe the invocation-specific data should be called data-files? That one's harder to name, but we don't want to call it crate-files (because it might come from a standalone markdown file) and I think invocation-specific-files is needlessly complex for what it is.

[fmease]

@rfcbot resolve outdir-not-honored

Fixed in #153003. Thanks, notriddle!