From b5f2a71f55efefcd2560f774b5f157e626630180 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Ber=C3=A1nek?= Date: Thu, 4 Sep 2025 14:17:55 +0200 Subject: [PATCH 1/6] Document Cargo with in-tree rustdoc --- src/bootstrap/src/core/build_steps/doc.rs | 70 +++++++++++++++-------- src/bootstrap/src/core/builder/cargo.rs | 2 +- src/bootstrap/src/core/builder/tests.rs | 15 +++++ 3 files changed, 63 insertions(+), 24 deletions(-) diff --git a/src/bootstrap/src/core/build_steps/doc.rs b/src/bootstrap/src/core/build_steps/doc.rs index eb198a0051abe..33a0f617b4a6a 100644 --- a/src/bootstrap/src/core/build_steps/doc.rs +++ b/src/bootstrap/src/core/build_steps/doc.rs @@ -965,7 +965,7 @@ macro_rules! tool_doc { ( $tool: ident, $path: literal, - $(rustc_private_tool = $rustc_private_tool:literal, )? + mode = $mode:expr, $(is_library = $is_library:expr,)? $(crates = $crates:expr)? ) => { @@ -988,20 +988,29 @@ macro_rules! tool_doc { fn make_run(run: RunConfig<'_>) { let target = run.target; - let (build_compiler, mode) = if true $(&& $rustc_private_tool)? { - // Rustdoc needs the rustc sysroot available to build. - let compilers = RustcPrivateCompilers::new(run.builder, run.builder.top_stage, target); - - // Build rustc docs so that we generate relative links. - run.builder.ensure(Rustc::from_build_compiler(run.builder, compilers.build_compiler(), target)); - - (compilers.build_compiler(), Mode::ToolRustcPrivate) - } else { - // bootstrap/host tools have to be documented with the stage 0 compiler - (prepare_doc_compiler(run.builder, run.builder.host_target, 1), Mode::ToolBootstrap) + let build_compiler = match $mode { + Mode::ToolRustcPrivate => { + // Rustdoc needs the rustc sysroot available to build. + let compilers = RustcPrivateCompilers::new(run.builder, run.builder.top_stage, target); + + // Build rustc docs so that we generate relative links. + run.builder.ensure(Rustc::from_build_compiler(run.builder, compilers.build_compiler(), target)); + compilers.build_compiler() + } + Mode::ToolBootstrap => { + // bootstrap/host tools should be documented with the stage 0 compiler + prepare_doc_compiler(run.builder, run.builder.host_target, 1) + } + Mode::ToolTarget => { + // target tools should be documented with the in-tree compiler + prepare_doc_compiler(run.builder, run.builder.host_target, 2) + } + _ => { + panic!("Unexpected tool mode for documenting: {:?}", $mode); + } }; - run.builder.ensure($tool { build_compiler, mode, target }); + run.builder.ensure($tool { build_compiler, mode: $mode, target }); } /// Generates documentation for a tool. @@ -1087,18 +1096,33 @@ macro_rules! tool_doc { tool_doc!( BuildHelper, "src/build_helper", - rustc_private_tool = false, + mode = Mode::ToolBootstrap, is_library = true, crates = ["build_helper"] ); -tool_doc!(Rustdoc, "src/tools/rustdoc", crates = ["rustdoc", "rustdoc-json-types"]); -tool_doc!(Rustfmt, "src/tools/rustfmt", crates = ["rustfmt-nightly", "rustfmt-config_proc_macro"]); -tool_doc!(Clippy, "src/tools/clippy", crates = ["clippy_config", "clippy_utils"]); -tool_doc!(Miri, "src/tools/miri", crates = ["miri"]); +tool_doc!( + Rustdoc, + "src/tools/rustdoc", + mode = Mode::ToolRustcPrivate, + crates = ["rustdoc", "rustdoc-json-types"] +); +tool_doc!( + Rustfmt, + "src/tools/rustfmt", + mode = Mode::ToolRustcPrivate, + crates = ["rustfmt-nightly", "rustfmt-config_proc_macro"] +); +tool_doc!( + Clippy, + "src/tools/clippy", + mode = Mode::ToolRustcPrivate, + crates = ["clippy_config", "clippy_utils"] +); +tool_doc!(Miri, "src/tools/miri", mode = Mode::ToolRustcPrivate, crates = ["miri"]); tool_doc!( Cargo, "src/tools/cargo", - rustc_private_tool = false, + mode = Mode::ToolTarget, crates = [ "cargo", "cargo-credential", @@ -1112,25 +1136,25 @@ tool_doc!( "rustfix", ] ); -tool_doc!(Tidy, "src/tools/tidy", rustc_private_tool = false, crates = ["tidy"]); +tool_doc!(Tidy, "src/tools/tidy", mode = Mode::ToolBootstrap, crates = ["tidy"]); tool_doc!( Bootstrap, "src/bootstrap", - rustc_private_tool = false, + mode = Mode::ToolBootstrap, is_library = true, crates = ["bootstrap"] ); tool_doc!( RunMakeSupport, "src/tools/run-make-support", - rustc_private_tool = false, + mode = Mode::ToolBootstrap, is_library = true, crates = ["run_make_support"] ); tool_doc!( Compiletest, "src/tools/compiletest", - rustc_private_tool = false, + mode = Mode::ToolBootstrap, is_library = true, crates = ["compiletest"] ); diff --git a/src/bootstrap/src/core/builder/cargo.rs b/src/bootstrap/src/core/builder/cargo.rs index a9a74b9bb0731..947147cdcbf21 100644 --- a/src/bootstrap/src/core/builder/cargo.rs +++ b/src/bootstrap/src/core/builder/cargo.rs @@ -533,7 +533,7 @@ impl Builder<'_> { if cmd_kind == Kind::Doc { let my_out = match mode { // This is the intended out directory for compiler documentation. - Mode::Rustc | Mode::ToolRustcPrivate | Mode::ToolBootstrap => { + Mode::Rustc | Mode::ToolRustcPrivate | Mode::ToolBootstrap | Mode::ToolTarget => { self.compiler_doc_out(target) } Mode::Std => { diff --git a/src/bootstrap/src/core/builder/tests.rs b/src/bootstrap/src/core/builder/tests.rs index 9e8c13eb4dec7..da9e1ecad7b98 100644 --- a/src/bootstrap/src/core/builder/tests.rs +++ b/src/bootstrap/src/core/builder/tests.rs @@ -2462,6 +2462,21 @@ mod snapshot { "); } + #[test] + fn doc_cargo() { + let ctx = TestCtx::new(); + insta::assert_snapshot!( + ctx.config("doc") + .path("cargo") + .render_steps(), @r" + [build] llvm + [build] rustc 0 -> rustc 1 + [build] rustc 1 -> std 1 + [build] rustdoc 1 + [doc] rustc 1 -> Cargo 2 + "); + } + #[test] fn doc_core() { let ctx = TestCtx::new(); From 9f9473f201e73a74c87ff5532828ad82b42b508e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Ber=C3=A1nek?= Date: Fri, 5 Sep 2025 16:20:53 +0200 Subject: [PATCH 2/6] Allow `specialization` feature when documenting Cargo --- src/bootstrap/src/core/build_steps/doc.rs | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/src/bootstrap/src/core/build_steps/doc.rs b/src/bootstrap/src/core/build_steps/doc.rs index 33a0f617b4a6a..6aa2b75d5baf9 100644 --- a/src/bootstrap/src/core/build_steps/doc.rs +++ b/src/bootstrap/src/core/build_steps/doc.rs @@ -965,9 +965,11 @@ macro_rules! tool_doc { ( $tool: ident, $path: literal, - mode = $mode:expr, - $(is_library = $is_library:expr,)? - $(crates = $crates:expr)? + mode = $mode:expr + $(, is_library = $is_library:expr )? + $(, crates = $crates:expr )? + // Subset of nightly features that are allowed to be used when documenting + $(, allow_features: $allow_features:expr )? ) => { #[derive(Debug, Clone, Hash, PartialEq, Eq)] pub struct $tool { @@ -1041,6 +1043,15 @@ macro_rules! tool_doc { source_type, &[], ); + let allow_features = { + let mut _value = ""; + $( _value = $allow_features; )? + _value + }; + + if allow_features.is_empty() { + cargo.allow_features(allow_features); + } cargo.arg("-Zskip-rustdoc-fingerprint"); // Only include compiler crates, no dependencies of those, such as `libc`. @@ -1134,7 +1145,8 @@ tool_doc!( "crates-io", "mdman", "rustfix", - ] + ], + allow_features: "specialization" ); tool_doc!(Tidy, "src/tools/tidy", mode = Mode::ToolBootstrap, crates = ["tidy"]); tool_doc!( From a6aa509687a125e9a3cac3da229369edb67e3205 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Ber=C3=A1nek?= Date: Fri, 5 Sep 2025 16:22:52 +0200 Subject: [PATCH 3/6] Respect top stage when documenting Cargo --- src/bootstrap/src/core/build_steps/doc.rs | 2 +- src/bootstrap/src/core/builder/tests.rs | 15 ++++++++++++++- 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/src/bootstrap/src/core/build_steps/doc.rs b/src/bootstrap/src/core/build_steps/doc.rs index 6aa2b75d5baf9..a1a16980be69e 100644 --- a/src/bootstrap/src/core/build_steps/doc.rs +++ b/src/bootstrap/src/core/build_steps/doc.rs @@ -1005,7 +1005,7 @@ macro_rules! tool_doc { } Mode::ToolTarget => { // target tools should be documented with the in-tree compiler - prepare_doc_compiler(run.builder, run.builder.host_target, 2) + prepare_doc_compiler(run.builder, run.builder.host_target, run.builder.top_stage) } _ => { panic!("Unexpected tool mode for documenting: {:?}", $mode); diff --git a/src/bootstrap/src/core/builder/tests.rs b/src/bootstrap/src/core/builder/tests.rs index da9e1ecad7b98..e7b92dbc18f68 100644 --- a/src/bootstrap/src/core/builder/tests.rs +++ b/src/bootstrap/src/core/builder/tests.rs @@ -2463,12 +2463,25 @@ mod snapshot { } #[test] - fn doc_cargo() { + fn doc_cargo_stage_1() { let ctx = TestCtx::new(); insta::assert_snapshot!( ctx.config("doc") .path("cargo") .render_steps(), @r" + [build] rustdoc 0 + [doc] rustc 0 -> Cargo 1 + "); + } + + #[test] + fn doc_cargo_stage_2() { + let ctx = TestCtx::new(); + insta::assert_snapshot!( + ctx.config("doc") + .path("cargo") + .stage(2) + .render_steps(), @r" [build] llvm [build] rustc 0 -> rustc 1 [build] rustc 1 -> std 1 From 4375e9d313aa3b236c8537e7ceeb89f6415fc05a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Ber=C3=A1nek?= Date: Fri, 5 Sep 2025 16:24:43 +0200 Subject: [PATCH 4/6] Add snapshot test for disting compiler docs --- src/bootstrap/src/core/builder/tests.rs | 54 ++++++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) diff --git a/src/bootstrap/src/core/builder/tests.rs b/src/bootstrap/src/core/builder/tests.rs index e7b92dbc18f68..19cfe79be5dba 100644 --- a/src/bootstrap/src/core/builder/tests.rs +++ b/src/bootstrap/src/core/builder/tests.rs @@ -1130,6 +1130,59 @@ mod snapshot { ); } + #[test] + fn dist_compiler_docs() { + let ctx = TestCtx::new(); + insta::assert_snapshot!( + ctx.config("dist") + .path("rustc-docs") + .args(&["--set", "build.compiler-docs=true"]) + .render_steps(), @r" + [build] rustc 0 -> UnstableBookGen 1 + [build] rustc 0 -> Rustbook 1 + [doc] unstable-book (book) + [build] llvm + [build] rustc 0 -> rustc 1 + [build] rustc 1 -> std 1 + [doc] book (book) + [doc] book/first-edition (book) + [doc] book/second-edition (book) + [doc] book/2018-edition (book) + [build] rustdoc 1 + [doc] rustc 1 -> standalone 2 + [doc] rustc 1 -> std 1 crates=[alloc,compiler_builtins,core,panic_abort,panic_unwind,proc_macro,rustc-std-workspace-core,std,std_detect,sysroot,test,unwind] + [doc] rustc 1 -> rustc 2 + [build] rustc 1 -> rustc 2 + [doc] rustc 1 -> Rustdoc 2 + [doc] rustc 1 -> Rustfmt 2 + [build] rustc 1 -> error-index 2 + [doc] rustc 1 -> error-index 2 + [doc] nomicon (book) + [doc] rustc 1 -> reference (book) 2 + [doc] rustdoc (book) + [doc] rust-by-example (book) + [build] rustc 0 -> LintDocs 1 + [doc] rustc (book) + [doc] rustc 1 -> Cargo 2 + [doc] cargo (book) + [doc] rustc 1 -> Clippy 2 + [doc] clippy (book) + [doc] rustc 1 -> Miri 2 + [doc] embedded-book (book) + [doc] edition-guide (book) + [doc] style-guide (book) + [build] rustdoc 0 + [doc] rustc 0 -> Tidy 1 + [doc] rustc 0 -> Bootstrap 1 + [doc] rustc 1 -> releases 2 + [doc] rustc 0 -> RunMakeSupport 1 + [doc] rustc 0 -> BuildHelper 1 + [doc] rustc 0 -> Compiletest 1 + [build] rustc 0 -> RustInstaller 1 + " + ); + } + #[test] fn dist_extended() { let ctx = TestCtx::new(); @@ -2473,7 +2526,6 @@ mod snapshot { [doc] rustc 0 -> Cargo 1 "); } - #[test] fn doc_cargo_stage_2() { let ctx = TestCtx::new(); From 8c93cdc8e0ad3c443755a88af3c0367894614178 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Ber=C3=A1nek?= Date: Fri, 5 Sep 2025 17:02:12 +0200 Subject: [PATCH 5/6] Add a comment about the "specialization" feature required because of `im-rc` --- src/bootstrap/src/core/build_steps/doc.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/bootstrap/src/core/build_steps/doc.rs b/src/bootstrap/src/core/build_steps/doc.rs index a1a16980be69e..295d8b55eff71 100644 --- a/src/bootstrap/src/core/build_steps/doc.rs +++ b/src/bootstrap/src/core/build_steps/doc.rs @@ -1146,6 +1146,8 @@ tool_doc!( "mdman", "rustfix", ], + // Required because of the im-rc dependency of Cargo, which automatically opts into the + // "specialization" feature in its build script when it detects a nightly toolchain. allow_features: "specialization" ); tool_doc!(Tidy, "src/tools/tidy", mode = Mode::ToolBootstrap, crates = ["tidy"]); From b5c139baed5991870267bfa1d82e980d5051d2ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Ber=C3=A1nek?= Date: Fri, 5 Sep 2025 19:57:08 +0200 Subject: [PATCH 6/6] Fix condition --- src/bootstrap/src/core/build_steps/doc.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/bootstrap/src/core/build_steps/doc.rs b/src/bootstrap/src/core/build_steps/doc.rs index 295d8b55eff71..378c9c19ba5da 100644 --- a/src/bootstrap/src/core/build_steps/doc.rs +++ b/src/bootstrap/src/core/build_steps/doc.rs @@ -1049,7 +1049,7 @@ macro_rules! tool_doc { _value }; - if allow_features.is_empty() { + if !allow_features.is_empty() { cargo.allow_features(allow_features); }