feat(rustdoc): stabilize `--emit` flag by weihanglo · Pull Request #146220 · rust-lang/rust

weihanglo · 2025-09-05T00:00:58Z

Stabilization Report: `rustdoc --emit`

Feature: rustdoc --emit
Tracking issue: #83784
Stabilization PR: #146220

What we are stabilizing

This stabilizes the rustdoc --emit flag, which controls what types of output rustdoc produces. The flag accepts a comma-separated list of the following emit types:

html-static-files --- Shared static files with content-hashed filenames for safe caching.
html-non-static-files --- Per-crate documentation files with deterministic filenames.
dep-info[=<path>] --- A Makefile-compatible .d file listing all source files loaded during documentation generation. Same as rustc's dep-info files.

When --emit is not specified, the default behavior is --emit=html-static-files,html-non-static-files (i.e., full HTML documentation output, no dep-info).

What we are not stabilizing

Interaction between other unstable options, such as -Zrustdoc-mergeable-info and --output-format=doctest
Available options and the default options when --emit not specified.
Extension of per-type emit paths for options currently missing that.

Motivation

Cargo

The primary consumer is Cargo, which needs --emit=dep-info=<path> to precisely track the input dependencies of a rustdoc invocation (see the -Zrustdoc-depinfo unstable Cargo feature). Without dep-info, Cargo cannot detect changes to files pulled in via #[path = "..."] or similar mechanisms and leads to stale documentation in incremental builds.

Cargo also uses the selective emission mechanism (html-static-files / html-non-static-files) when the unstable -Zrustdoc-mergeable-info feature is active. It skips writing shared static files and search index during per-crate doc generation and defer them to a final merge phase.

Under stable usage, Cargo passes all three emit types together.

docs.rs

docs.rs is the other major consumer. It uses selective emission to avoid redundantly copying toolchain-wide static files for every crate, which has historically been a source of breakage. See the tracking #83784 and the about page for more https://docs.rs/about/download.

Tests

tests/run-make/emit-shared-files --- Verifies selective emission of static vs non-static files.
tests/run-make/rustdoc-dep-info --- Verifies dep-info generation, including explicit path and --out-dir interaction.
tests/run-make/rustdoc-scrape-examples-dep-info --- Verifies dep-info works with scrape-examples.
tests/run-make/rustdoc-default-output/ --- Verifies --help output shows [html-static-files,html-non-static-files,dep-info]

weihanglo · 2025-09-05T00:03:31Z

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 · 2025-09-11T19:48:52Z

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

src/doc/rustdoc/src/command-line-arguments.md

GuillaumeGomez · 2025-10-13T20:51:02Z

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 · 2025-10-13T23:22:09Z

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 · 2025-10-25T18:00:15Z

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

weihanglo · 2025-10-25T18:33:33Z

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.

This option hasn't done anything for a long time, and can be removed. I've kept a shim in place to avoid breaking docs.rs, but the option no longer does anything. Using git-blame, I tracked this option down to f77ebd4, the commit that introduced EmitType in the first place. It was used with SharedResource::Unversioned, which no longer exists since f9e1f6f removed them. Part of rust-lang#146220

notriddle · 2025-10-27T17:24:00Z

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.

This option hasn't done anything for a long time, and can be removed. I've kept a shim in place to avoid breaking docs.rs, but the option no longer does anything. Using git-blame, I tracked this option down to f77ebd4, the commit that introduced EmitType in the first place. It was used with SharedResource::Unversioned, which no longer exists since f9e1f6f removed them. CC rust-lang#146220 Part of rust-lang#83784

…rces, r=GuillaumeGomez rustdoc: remove `--emit=unversioned-shared-resources` This option hasn't done anything for a long time, and can be removed. I've kept a shim in place to avoid breaking docs.rs, but the option no longer does anything. Using git-blame, I tracked this option down to f77ebd4, the commit that introduced EmitType in the first place. It was used with SharedResource::Unversioned, which no longer exists since f9e1f6f removed them. CC rust-lang#146220 Part of rust-lang#83784

src/doc/rustdoc/src/command-line-arguments.md

yotamofek · 2026-01-13T13:28:01Z

src/doc/rustdoc/src/command-line-arguments.md

+This flag controls the types of output by rustdoc. It accepts a comma-separated
+list of values, and may be specified multiple times. The valid emit kinds are:
+
+- `toolchain-shared-resources` --- Generates shared static files that their


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

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

fmease · 2026-02-20T20:19:59Z

@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 · 2026-02-20T20:23:57Z

src/doc/rustdoc/src/command-line-arguments.md

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

Under --emit=dep-info and --emit=invocation-specific rustdoc still generates an empty <OUTDIR>/static.files/ directory.

On unknown emission/output types rustdoc doesn't list all legal types in the error diagnostic unlike rustc.

notriddle · 2026-02-28T05:47:29Z

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.

rustdoc: make `--emit` and `--out-dir` mimic rustc The behavior in the test case matches rustc's: test-dingus % ls main.rs test-dingus % mkdir foobar test-dingus % rustc --emit=dep-info main.rs --out-dir=foobar test-dingus % ls foobar main.rs test-dingus % ls foobar main.d test-dingus % rustc --emit=dep-info=testfile.d main.rs --out-dir=foobar test-dingus % ls foobar main.rs testfile.d test-dingus % ls foobar main.d CC rust-lang#146220 (comment)

Rollup merge of #153003 - notriddle:emit-outdir, r=fmease rustdoc: make `--emit` and `--out-dir` mimic rustc The behavior in the test case matches rustc's: test-dingus % ls main.rs test-dingus % mkdir foobar test-dingus % rustc --emit=dep-info main.rs --out-dir=foobar test-dingus % ls foobar main.rs test-dingus % ls foobar main.d test-dingus % rustc --emit=dep-info=testfile.d main.rs --out-dir=foobar test-dingus % ls foobar main.rs testfile.d test-dingus % ls foobar main.d CC #146220 (comment)

fmease · 2026-03-04T13:04:28Z

@rfcbot resolve outdir-not-honored

Fixed in #153003. Thanks, notriddle!

rustdoc: rename `--emit` names These new names are pithier and match up with the rest of our terminology: - `--emit=html-static-files` matches the default name of the directory that it actually emits, which is `static.files` (the hyphen is used for emit because every other emit option uses hyphens, but the directory uses a dot because we don't want its name to conflict with a crate). - `--emit=html-non-static-files` matches the convention that emit is a noun, not an adjective, and it logically groups with other data formats. This commit changes the docs, but leaves in support for the old names, to break the cycle with cargo and docs.rs. This commit needs merged, then cargo and docs.rs will be updated to use the new names, then, finally, the old names will be removed. CC #146220 (comment)

rustdoc: rename `--emit` names These new names are pithier and match up with the rest of our terminology: - `--emit=html-static-files` matches the default name of the directory that it actually emits, which is `static.files` (the hyphen is used for emit because every other emit option uses hyphens, but the directory uses a dot because we don't want its name to conflict with a crate). - `--emit=html-non-static-files` matches the convention that emit is a noun, not an adjective, and it logically groups with other data formats. This commit changes the docs, but leaves in support for the old names, to break the cycle with cargo and docs.rs. This commit needs merged, then cargo and docs.rs will be updated to use the new names, then, finally, the old names will be removed. CC rust-lang#146220 (comment)

fmease · 2026-03-11T13:23:43Z

@rfcbot resolve naming

Fixed in #153460. Thanks, notriddle! If you disagree with the new names that were chosen please raise a new pFCP concern!

GuillaumeGomez · 2026-03-11T15:38:20Z

So just needs an update for the docs @weihanglo then the PR seems ready to go!

fmease · 2026-03-11T15:46:34Z

As well as a tiny stabilization report, please :D (FCP concern tiny-stab-report). Moreover, FCP concern interaction-with-other-modes hasn't been resolved yet.

weihanglo · 2026-03-14T14:28:28Z

RE: concern interaction-with-other-modes

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.

I wonder if --output-format=doctest we could also have dep-info, so other build system can deteremine whether a rustdoc invocation needs to rerun. For markdown input, I am not familiar with the use case. Sorry.

(That said, those options are unstable still)

rustbot · 2026-03-14T15:02:25Z

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.

weihanglo · 2026-03-14T15:09:17Z

@fmease A informal stabilization report has got updated in the PR description. Feel free to edit :)

One thing I put there was my personal opinion

What we are not stabilizing

...

Available options and the default emit options.

I am trying to mimic --remap-path-scope that rustdoc can reserve the future flexibility to extend the default options. I am not sure if this is what rustdoc team wants though. If yes, I could update the doc with something like this:

The options accepted by --emit are not exhaustive — new options may be added in future releases. Newly introduced options may also be included in the default outputs when --emit is not specified.

ojeda · 2026-03-14T19:20:33Z

I wonder if --output-format=doctest we could also have dep-info, so other build system can deteremine whether a rustdoc invocation needs to rerun.

That would be nice!

Currently, I approximate it by rerunning if the object file changes, which in turn should cover the source files, but that of course means we require building the crate before.

So if you mean we could generate the tests independently (e.g. in parallel) to building (which seems to be the case from a quick test, i.e. the crate is not required to be built to extract the tests), then it would quite nice!

notriddle · 2026-03-15T02:02:46Z

It seems like we can avoid going through a one-way door by making it a fatal error to use --test and --emit at the same time. #153895

rustbot assigned GuillaumeGomez Sep 5, 2025

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Sep 5, 2025

weihanglo marked this pull request as ready for review September 24, 2025 19:21

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Sep 24, 2025

fmease added the needs-fcp This change is insta-stable, or significant enough to need a team FCP to proceed. label Oct 13, 2025

fmease reviewed Oct 13, 2025

View reviewed changes

src/doc/rustdoc/src/command-line-arguments.md Outdated Show resolved Hide resolved

notriddle self-assigned this Oct 13, 2025

fmease mentioned this pull request Oct 13, 2025

rustdoc's --emit=dep-info=- doesn't output to STDOUT unlike rustc's #147649

Closed

weihanglo force-pushed the rustdoc-emit branch from e1a5014 to cc82db2 Compare October 25, 2025 15:56

This comment has been minimized.

Sign in to view

weihanglo force-pushed the rustdoc-emit branch from cc82db2 to bfb63c3 Compare October 25, 2025 16:04

weihanglo mentioned this pull request Oct 25, 2025

chore(triagebot): enable range-diff and review-changes-since rust-lang/cargo#16152

Merged

fmease mentioned this pull request Oct 25, 2025

rustdoc: follow-up work for --emit=toolchain-shared-resources #83784

Open

3 tasks

ojeda mentioned this pull request Oct 26, 2025

rustdoc wanted features & bugfixes Rust-for-Linux/linux#350

Open

27 tasks

notriddle mentioned this pull request Oct 27, 2025

rustdoc: remove --emit=unversioned-shared-resources #148180

Merged

weihanglo force-pushed the rustdoc-emit branch from bfb63c3 to b7f8908 Compare October 27, 2025 18:49

This comment has been minimized.

Sign in to view

yotamofek reviewed Jan 13, 2026

View reviewed changes

weihanglo force-pushed the rustdoc-emit branch from b7f8908 to d5d59c7 Compare January 13, 2026 16:09

This comment has been minimized.

Sign in to view

fmease reviewed Feb 20, 2026

View reviewed changes

notriddle mentioned this pull request Feb 23, 2026

rustdoc: make --emit and --out-dir mimic rustc #153003

Merged

fmease mentioned this pull request Feb 23, 2026

Stabilize rustdoc --merge --parts-out-dir, and --include-parts-dir options #152902

Open

notriddle mentioned this pull request Mar 5, 2026

rustdoc: rename --emit names #153460

Merged

weihanglo force-pushed the rustdoc-emit branch from d5d59c7 to 956387b Compare March 14, 2026 15:02

This comment has been minimized.

Sign in to view

feat(rustdoc): stabilize --emit flag

12105b6

weihanglo force-pushed the rustdoc-emit branch from 956387b to 12105b6 Compare March 14, 2026 15:18

ojeda mentioned this pull request Mar 14, 2026

Rust unstable features needed for the kernel Rust-for-Linux/linux#2

Open

48 tasks

Uh oh!

Conversation

weihanglo commented Sep 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Stabilization Report: rustdoc --emit

What we are stabilizing

What we are not stabilizing

Motivation

Cargo

docs.rs

Tests

Uh oh!

weihanglo commented Sep 5, 2025

Uh oh!

weihanglo commented Sep 11, 2025

Uh oh!

Uh oh!

GuillaumeGomez commented Oct 13, 2025

Uh oh!

weihanglo commented Oct 13, 2025

Uh oh!

This comment has been minimized.

fmease commented Oct 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

weihanglo commented Oct 25, 2025

Uh oh!

notriddle commented Oct 27, 2025

Uh oh!

This comment has been minimized.

Uh oh!

Uh oh!

yotamofek Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

weihanglo Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

fmease commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fmease Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

notriddle commented Feb 28, 2026

Uh oh!

fmease commented Mar 4, 2026

Uh oh!

fmease commented Mar 11, 2026

Uh oh!

GuillaumeGomez commented Mar 11, 2026

Uh oh!

fmease commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

weihanglo commented Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

RE: concern interaction-with-other-modes

Uh oh!

rustbot commented Mar 14, 2026

Uh oh!

This comment has been minimized.

weihanglo commented Mar 14, 2026

What we are not stabilizing

Uh oh!

ojeda commented Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

notriddle commented Mar 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

weihanglo commented Sep 5, 2025 •

edited

Loading

Stabilization Report: `rustdoc --emit`

fmease commented Oct 25, 2025 •

edited

Loading

fmease commented Feb 20, 2026 •

edited

Loading

fmease Feb 20, 2026 •

edited

Loading

fmease commented Mar 11, 2026 •

edited

Loading

weihanglo commented Mar 14, 2026 •

edited

Loading

ojeda commented Mar 14, 2026 •

edited

Loading