Simplify doc meta mode by notriddle · Pull Request #159473 · rust-lang/rust

notriddle · 2026-07-17T22:35:07Z

Get rid of the mode where you can finalize the CCI and generate more docs at the same time. It isn't used in Cargo, and probably won't be used elsewhere?

rustbot · 2026-07-17T22:35:12Z

r? @folkertdev

rustbot has assigned @folkertdev.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

Owners of files modified in this PR: compiler
compiler expanded to 74 candidates
Random selection from 17 candidates

notriddle · 2026-07-17T22:36:25Z

r? @camelid

rustbot · 2026-07-17T22:36:29Z

camelid is currently at their maximum review capacity.
They may take a while to respond.

Since we're getting rid of the ability to do finalize and document at the same time, we can't actually do this in the rustdoc-html test build system and need to do it this way instead.

Co-authored-by: Noah Lev <37223377+camelid@users.noreply.github.com>

rustbot · 2026-07-26T02:19:44Z

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.

camelid

Looks good overall, but I'd like to avoid the dummy crate and TyCtxt, and some of the tests seem to be translated wrong from the original files.

View changes since this review

camelid · 2026-07-27T17:49:47Z

+    let krate = ast::Crate {
+        attrs: Default::default(),
+        items: Default::default(),
+        spans: Default::default(),
+        id: ast::DUMMY_NODE_ID,
+        is_placeholder: false,
+    };


I don't love that we're creating a dummy crate here just to get a TyCtxt. It seems like we only use the TyCtxt to get the Sess. So I don't think you actually need to do this. interface::Compiler already has a Sess on it.

I've removed the synthetic crate, but not the synthetic InputStr.

camelid · 2026-07-27T17:56:50Z

+            let config = core::create_config(
+                Input::Str {
+                    name: rustc_span::FileName::Custom(String::new()),
+                    input: String::new(),
+                },
+                options,
+                &render_options,
+            );
            return wrap_return(
                dcx,
-                rustc_span::create_session_globals_then(options.edition, &[], None, || {
-                    run_merge_finalize(render_options)
+                interface::run_compiler(config, |compiler| {
+                    run_merge_finalize(render_options, compiler)


Ditto here, but getting rid of the fake Input::Str is harder, and this seems less bad than making a fake crate and TyCtxt. So fine to just leave it.

camelid · 2026-07-27T18:13:27Z

+        .arg(format!("--read-doc-meta-dir={}", parts_out_dir.display()))
+        .arg("--enable-index-page")
+        .run();
+    output.assert_stderr_not_contains("error: the compiler unexpectedly panicked. this is a bug.");


nit: Is this necessary? Shouldn't the run-make test fail automatically if one of its subprocesses ICEs? (I'm not super familiar with run-make, so I might be wrong about this.)

I just checked, and you're right.

rust/src/tools/run-make-support/src/command.rs

Lines 232 to 240 in d3ea035

pub fn run(&mut self) -> CompletedProcess {

let output = self.command_output();

if !output.status().success() {

handle_failed_output(&self, output, panic::Location::caller().line());

} else {

verbose_print_command(self, &output);

}

output

}

Apparently, when a run-make command exits with a non-zero exit code, this thing will fail the test.

rust/src/tools/run-make-support/src/util.rs

Lines 31 to 43 in d3ea035

pub(crate) fn handle_failed_output(

cmd: &Command,

output: CompletedProcess,

caller_line_number: u32,

) -> ! {

if output.status().success() {

eprintln!("command unexpectedly succeeded at line {caller_line_number}");

} else {

eprintln!("command failed at line {caller_line_number}");

}

print_command_output(cmd, &output);

std::process::exit(1)

}

camelid · 2026-07-27T18:15:38Z

+
+fn main() {
+    let merged_dir = path("merged");
+    let parts_out_dir = path("parts");


Is this just not used at all?

It's not. I've removed it.

camelid · 2026-07-27T18:19:59Z

+        .library_search_path(cwd())
+        .out_dir(&out_dir)
+        .arg("-Zunstable-options")
+        .arg("--write-doc-meta-dir=parts-wrong")


I don't understand why this is parts-wrong -- if they all use the same name, there's nothing wrong about it. I think this might have been lost in translation from the original test.

There's no --read-doc-meta-dir, and the sierra.rs tests all verify that the shared resources aren't generated.

I've added a comment, and renamed the dir parts-unused, to clarify this.

rustbot · 2026-07-27T18:22:36Z

Reminder, once the PR becomes ready for a review, use @rustbot ready.

weihanglo · 2026-07-29T04:36:19Z

-If this parameter is supplied but `--read-doc-meta-dir` isn't, it runs in *intermediate mode*:
-some pages may be written to the output dir, but there is a lot of functionality that won't work
-until rustdoc is run in *finalize mode*.
+When `--write-doc-meta-dir` is supplied, rustdoc will write the crate's shared metadata to


Probably not the right question for this PR, and I haven't read the implementation here, though I am curious:

How does this interact with --out-dir. I guess --out-dir is ignored here?

How does this interact with all those --emit files (w/ or w/o --out-dir? Where will those files be emitted?

View changes since the review

Context: I'd like to pass --emit=dep-info without specifying the full (absolute) path for those dep-info files. Because of this issue #159743 we cannot specify full path, and currently blocks rust-lang/cargo#17020.

(That said, it is a very Cargo specific issue I feel like)

The --out-dir is still used as the path for --emit files. --write-doc-meta-dir doesn't pay attention to --out-dir.

I see. So eventually if individual rustdoc doesn't need to emit html contents, cargo then can use --emit to control dep-info emission location exclusively. Thanks!

camelid · 2026-07-29T18:31:07Z

We're also missing the root-level help.html and settings.html files in the finalize step.

notriddle · 2026-07-30T03:15:18Z

Good catch! settings.html and help.html are moved, so they get generated at finalize now.

rust-log-analyzer · 2026-07-30T04:07:10Z

The job aarch64-gnu-llvm-21-1 failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

---- [run-make] tests/run-make/emit-shared-files stdout ----

error: rmake recipe failed to complete
status: exit status: 101
command: cd "/checkout/obj/build/aarch64-unknown-linux-gnu/test/run-make/emit-shared-files/rmake_out" && env -u RUSTFLAGS -u __STD_REMAP_DEBUGINFO_ENABLED AR="ar" BUILD_ROOT="/checkout/obj/build/aarch64-unknown-linux-gnu" CC="cc" CC_DEFAULT_FLAGS="-ffunction-sections -fdata-sections -fPIC" CXX="c++" CXX_DEFAULT_FLAGS="-ffunction-sections -fdata-sections -fPIC" HOST_RUSTC_DYLIB_PATH="/checkout/obj/build/aarch64-unknown-linux-gnu/stage2/lib" LD_LIBRARY_PATH="/checkout/obj/build/aarch64-unknown-linux-gnu/bootstrap-tools/aarch64-unknown-linux-gnu/release/build/run_make_support/81c3418404f46bf6/out:/checkout/obj/build/aarch64-unknown-linux-gnu/stage0/lib/rustlib/aarch64-unknown-linux-gnu/lib" LD_LIB_PATH_ENVVAR="LD_LIBRARY_PATH" LLVM_BIN_DIR="/usr/lib/llvm-21/bin" LLVM_COMPONENTS="aarch64 aarch64asmparser aarch64codegen aarch64desc aarch64disassembler aarch64info aarch64utils aggressiveinstcombine all all-targets amdgpu amdgpuasmparser amdgpucodegen amdgpudesc amdgpudisassembler amdgpuinfo amdgputargetmca amdgpuutils analysis arm armasmparser armcodegen armdesc armdisassembler arminfo armutils asmparser asmprinter avr avrasmparser avrcodegen avrdesc avrdisassembler avrinfo binaryformat bitreader bitstreamreader bitwriter bpf bpfasmparser bpfcodegen bpfdesc bpfdisassembler bpfinfo cfguard cgdata codegen codegentypes core coroutines coverage debuginfobtf debuginfocodeview debuginfodwarf debuginfodwarflowlevel debuginfogsym debuginfologicalview debuginfomsf debuginfopdb demangle dlltooldriver dwarfcfichecker dwarflinker dwarflinkerclassic dwarflinkerparallel dwp engine executionengine extensions filecheck frontendatomic frontenddirective frontenddriver frontendhlsl frontendoffloading frontendopenacc frontendopenmp fuzzercli fuzzmutate globalisel hexagon hexagonasmparser hexagoncodegen hexagondesc hexagondisassembler hexagoninfo hipstdpar instcombine instrumentation interfacestub interpreter ipo irprinter irreader jitlink lanai lanaiasmparser lanaicodegen lanaidesc lanaidisassembler lanaiinfo libdriver lineeditor linker loongarch loongarchasmparser loongarchcodegen loongarchdesc loongarchdisassembler loongarchinfo lto m68k m68kasmparser m68kcodegen m68kdesc m68kdisassembler m68kinfo mc mca mcdisassembler mcjit mcparser mips mipsasmparser mipscodegen mipsdesc mipsdisassembler mipsinfo mirparser msp430 msp430asmparser msp430codegen msp430desc msp430disassembler msp430info native nativecodegen nvptx nvptxcodegen nvptxdesc nvptxinfo objcarcopts objcopy object objectyaml option orcdebugging orcjit orcshared orctargetprocess passes perfjitevents powerpc powerpcasmparser powerpccodegen powerpcdesc powerpcdisassembler powerpcinfo profiledata remarks riscv riscvasmparser riscvcodegen riscvdesc riscvdisassembler riscvinfo riscvtargetmca runtimedyld sandboxir scalaropts selectiondag sparc sparcasmparser sparccodegen sparcdesc sparcdisassembler sparcinfo spirv spirvanalysis spirvcodegen spirvdesc spirvinfo support symbolize systemz systemzasmparser systemzcodegen systemzdesc systemzdisassembler systemzinfo tablegen target targetparser telemetry textapi textapibinaryreader transformutils ve veasmparser vecodegen vectorize vedesc vedisassembler veinfo webassembly webassemblyasmparser webassemblycodegen webassemblydesc webassemblydisassembler webassemblyinfo webassemblyutils windowsdriver windowsmanifest x86 x86asmparser x86codegen x86desc x86disassembler x86info x86targetmca xcore xcorecodegen xcoredesc xcoredisassembler xcoreinfo xray xtensa xtensaasmparser xtensacodegen xtensadesc xtensadisassembler xtensainfo" LLVM_FILECHECK="/usr/lib/llvm-21/bin/FileCheck" NODE="/usr/bin/node" PYTHON="/usr/bin/python3" RUSTC="/checkout/obj/build/aarch64-unknown-linux-gnu/stage2/bin/rustc" RUSTDOC="/checkout/obj/build/aarch64-unknown-linux-gnu/stage2/bin/rustdoc" SOURCE_ROOT="/checkout" TARGET="aarch64-unknown-linux-gnu" TARGET_EXE_DYLIB_PATH="/checkout/obj/build/aarch64-unknown-linux-gnu/stage2/lib/rustlib/aarch64-unknown-linux-gnu/lib" __BOOTSTRAP_JOBS="4" __RMAKE_VERBOSE_SUBPROCESS_OUTPUT="1" __RUSTC_DEBUG_ASSERTIONS_ENABLED="1" __STD_DEBUG_ASSERTIONS_ENABLED="1" "/checkout/obj/build/aarch64-unknown-linux-gnu/test/run-make/emit-shared-files/rmake"
stdout: none
--- stderr -------------------------------
LD_LIBRARY_PATH="/checkout/obj/build/aarch64-unknown-linux-gnu/test/run-make/emit-shared-files/rmake_out:/checkout/obj/build/aarch64-unknown-linux-gnu/stage2/lib:/checkout/obj/build/aarch64-unknown-linux-gnu/bootstrap-tools/aarch64-unknown-linux-gnu/release/build/run_make_support/81c3418404f46bf6/out:/checkout/obj/build/aarch64-unknown-linux-gnu/stage0/lib/rustlib/aarch64-unknown-linux-gnu/lib" "/checkout/obj/build/aarch64-unknown-linux-gnu/stage2/bin/rustdoc" "-Zunstable-options" "--emit=html-non-static-files" "--out-dir" "invocation-only" "--resource-suffix=-xxx" "--theme" "y.css" "--extend-css" "z.css" "x.rs" "--target=aarch64-unknown-linux-gnu"
output status: `exit status: 0`
=== STDOUT ===



=== STDERR ===
warning: theme file "y.css" is missing CSS rules from the default theme
  |
  = warning: the theme may appear incorrect when loaded
  = help: to see what rules are missing, call `rustdoc --check-theme "y.css"`




LD_LIBRARY_PATH="/checkout/obj/build/aarch64-unknown-linux-gnu/test/run-make/emit-shared-files/rmake_out:/checkout/obj/build/aarch64-unknown-linux-gnu/stage2/lib:/checkout/obj/build/aarch64-unknown-linux-gnu/bootstrap-tools/aarch64-unknown-linux-gnu/release/build/run_make_support/81c3418404f46bf6/out:/checkout/obj/build/aarch64-unknown-linux-gnu/stage0/lib/rustlib/aarch64-unknown-linux-gnu/lib" "/checkout/obj/build/aarch64-unknown-linux-gnu/stage2/bin/rustdoc" "-Zunstable-options" "--emit=html-static-files" "--out-dir" "toolchain-only" "--resource-suffix=-xxx" "--extend-css" "z.css" "x.rs" "--target=aarch64-unknown-linux-gnu"
output status: `exit status: 0`
=== STDOUT ===



=== STDERR ===



LD_LIBRARY_PATH="/checkout/obj/build/aarch64-unknown-linux-gnu/test/run-make/emit-shared-files/rmake_out:/checkout/obj/build/aarch64-unknown-linux-gnu/stage2/lib:/checkout/obj/build/aarch64-unknown-linux-gnu/bootstrap-tools/aarch64-unknown-linux-gnu/release/build/run_make_support/81c3418404f46bf6/out:/checkout/obj/build/aarch64-unknown-linux-gnu/stage0/lib/rustlib/aarch64-unknown-linux-gnu/lib" "/checkout/obj/build/aarch64-unknown-linux-gnu/stage2/bin/rustdoc" "-Zunstable-options" "--emit=html-static-files" "--out-dir" "all-shared" "--resource-suffix=-xxx" "--extend-css" "z.css" "x.rs" "--target=aarch64-unknown-linux-gnu"
output status: `exit status: 0`
=== STDOUT ===



=== STDERR ===




thread 'main' (301927) panicked at /checkout/tests/run-make/emit-shared-files/rmake.rs:92:5:
assertion failed: !path("all-shared/settings.html").exists()
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
------------------------------------------

---- [run-make] tests/run-make/emit-shared-files stdout end ----

rustbot assigned folkertdev Jul 17, 2026

rustbot assigned camelid and unassigned folkertdev Jul 17, 2026

notriddle mentioned this pull request Jul 17, 2026

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

Open

camelid reviewed Jul 23, 2026

View reviewed changes

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

fmease reviewed Jul 25, 2026

View reviewed changes

Comment thread tests/run-make/rustdoc/merge-cross-crate-info/kitchen-sink-separate-dirs/indigo.rs

notriddle and others added 9 commits July 25, 2026 19:06

rustdoc: fix --enable-index-page with finalize

91131bb

rustdoc: move CCI tests to run-make

a36c898

Since we're getting rid of the ability to do finalize and document at the same time, we can't actually do this in the rustdoc-html test build system and need to do it this way instead.

rustdoc: write rmake scripts to test CCI

6887d4d

Document the changed doc meta features

32f1625

Update src/doc/rustdoc/src/unstable-features.md

18d6ebf

Co-authored-by: Noah Lev <37223377+camelid@users.noreply.github.com>

Update src/doc/rustdoc/src/unstable-features.md

ac3994e

Co-authored-by: Noah Lev <37223377+camelid@users.noreply.github.com>

rustdoc: clean up unused @ build diectives

c352016

rustdoc: no --read-doc-meta-dir and --write-doc-meta-dir at once

e03942b

rustdoc: move CCI run-make tests into the directory

d0fec14

notriddle force-pushed the rename-parts-to-dep-meta branch from 9e2125b to d0fec14 Compare July 26, 2026 02:19

camelid 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 Jul 27, 2026

camelid requested changes Jul 27, 2026

View reviewed changes

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

rustdoc: stop constructing an unneeded synth Crate

9d136ed

This comment has been minimized.

Sign in to view

rustdoc: remove unused code from rmake tests

f73cd1e

notriddle force-pushed the rename-parts-to-dep-meta branch from c3d3011 to f73cd1e Compare July 28, 2026 04:05

GuillaumeGomez approved these changes Jul 28, 2026

View reviewed changes

weihanglo reviewed Jul 29, 2026

View reviewed changes

weihanglo mentioned this pull request Jul 29, 2026

fix: stabilize -Zrustdoc-depinfo rust-lang/cargo#17020

Open

rustdoc: generate settings and help at finalize

23fae6c

	pub fn run(&mut self) -> CompletedProcess {
	let output = self.command_output();
	if !output.status().success() {
	handle_failed_output(&self, output, panic::Location::caller().line());
	} else {
	verbose_print_command(self, &output);
	}
	output
	}

	pub(crate) fn handle_failed_output(
	cmd: &Command,
	output: CompletedProcess,
	caller_line_number: u32,
	) -> ! {
	if output.status().success() {
	eprintln!("command unexpectedly succeeded at line {caller_line_number}");
	} else {
	eprintln!("command failed at line {caller_line_number}");
	}
	print_command_output(cmd, &output);
	std::process::exit(1)
	}

Uh oh!

Uh oh!

Conversation

notriddle commented Jul 17, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Jul 17, 2026

Uh oh!

notriddle commented Jul 17, 2026

Uh oh!

rustbot commented Jul 17, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rustbot commented Jul 26, 2026

Uh oh!

camelid left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

camelid Jul 27, 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 Jul 28, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustbot commented Jul 27, 2026

Uh oh!

This comment has been minimized.

weihanglo Jul 29, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

camelid commented Jul 29, 2026

Uh oh!

notriddle commented Jul 30, 2026

Uh oh!

rust-log-analyzer commented Jul 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

notriddle commented Jul 17, 2026 •

edited by rustbot

Loading

camelid left a comment •

edited by rustbot

Loading

camelid Jul 27, 2026 •

edited

Loading

notriddle Jul 28, 2026 •

edited

Loading

weihanglo Jul 29, 2026 •

edited by rustbot

Loading