Enforce in bootstrap that doc must have stage at least 1 #145011

Kobzol · 2025-08-06T16:34:53Z

Following with the bootstrap cleanups, this time around doc steps. Should be pretty straightforward, because the supporting infrastructure was already there.

The only thing I found a bit fishy is using Mode::ToolBootstrap as a "catch-all" mode for non-rustc-private steps in tool_doc!, but I don't think that we need to distinguish the tools in some special way when documenting them, apart from supporting rustc_private.

Before, x doc more or less defaulted to what we call stage 2 now. Now it is properly stage 1, so e.g. x doc compiler documents the compiler using the stage0/beta rust(do)c.

r? @jieyouxu

bors · 2025-08-07T03:56:53Z

☔ The latest upstream changes (presumably #145020) made this pull request unmergeable. Please resolve the merge conflicts.

As they were previously.

rustbot · 2025-08-08T06:18:01Z

This PR modifies src/bootstrap/src/core/config.

If appropriate, please update CONFIG_CHANGE_HISTORY in src/bootstrap/src/utils/change_tracker.rs.

Kobzol · 2025-08-08T06:19:39Z

Rebased over the two merged PRs, should be ready now.

@rustbot ready

jieyouxu

Thanks for working on this! The changes look good in the general sense that it does feel more self-consistent. I do have some questions though that occurred to me when looking at the changes.

jieyouxu · 2025-08-10T03:55:08Z

src/bootstrap/src/core/config/config.rs

@@ -1076,11 +1076,15 @@ impl Config {
        // Now check that the selected stage makes sense, and if not, print a warning and end
        match (config.stage, &config.cmd) {
            (0, Subcommand::Build) => {
-                eprintln!("WARNING: cannot build anything on stage 0. Use at least stage 1.");
+                eprintln!("ERROR: cannot build anything on stage 0. Use at least stage 1.");


Remark: lol I didn't notice this

jieyouxu · 2025-08-10T03:55:56Z

src/bootstrap/src/core/build_steps/doc.rs

+fn prepare_doc_compiler(builder: &Builder<'_>, target: TargetSelection, stage: u32) -> Compiler {
+    let build_compiler = builder.compiler(stage - 1, builder.host_target);
+    builder.std(build_compiler, target);
+    build_compiler
+}


Question: maybe overkill, should this assert that the passed in stage is at least one?

jieyouxu · 2025-08-10T03:57:45Z

src/bootstrap/src/core/builder/tests.rs

    #[test]
+    #[should_panic]
    fn doc_compiler_stage_0() {
        let ctx = TestCtx::new();
-        insta::assert_snapshot!(
-            ctx.config("doc")
-                .path("compiler")
-                .stage(0)
-                .render_steps(), @r"
-        [build] rustdoc 0 <host>
-        [build] llvm <host>
-        [doc] rustc 0 <host>
-        ");
+        ctx.config("doc").path("compiler").stage(0).run();


Question: hm, would we regress any actual use cases of documenting the stage 0 compiler?

jieyouxu · 2025-08-10T04:00:25Z

src/bootstrap/src/core/build_steps/doc.rs

+/// It is always done using a stage 1+ compiler, because it references in-tree compiler/stdlib
+/// concepts.


Nit: "It is always done" -> "It must always be done" (stronger emphasis)?

jieyouxu · 2025-08-10T04:01:45Z

src/bootstrap/src/core/build_steps/doc.rs

+        // Bump the stage to 2, because the reference requires an in-tree compiler.
+        // At the same time, since this step is enabled by default, we don't want `x doc` to fail
+        // in stage 1.
+        // FIXME: create a shared method on builder for auto-bumping, and print some warning when
+        // it happens.
+        let stage = if run.builder.config.is_explicit_stage() || run.builder.top_stage >= 2 {
+            run.builder.top_stage
+        } else {
+            2
+        };


Remark: hmm, auto-bumping stages always feel a bit sad (because it can be quite surprising to the user), but I suppose this makes sense. Good call on the warning when it will happen.

jieyouxu · 2025-08-10T04:08:20Z

src/bootstrap/src/core/build_steps/doc.rs

+                    // Build rustc docs so that we generate relative links.
+                    run.builder.ensure(Rustc::from_build_compiler(run.builder, compilers.build_compiler(), target));


Remark: hah, this is not super obvious...

jieyouxu · 2025-08-10T04:10:29Z

src/bootstrap/src/core/builder/tests.rs

+        [build] rustdoc 0 <host>
+        [doc] rustc 0 <host> -> Compiletest 1 <host>


Question: hm, to clarify, the staging in ./x doc $thing --stage=N corresponds to "what gets built"

src/bootstrap/src/core/build_steps/dist.rs

jieyouxu · 2025-08-10T04:24:48Z

src/bootstrap/src/core/builder/tests.rs

+        [doc] rustc 2 <host> -> std 2 <host> crates=[]
+        [doc] rustc 2 <host> -> std 2 <target1> crates=[]


Remark: hm, this is always a bit funny, when we run a std doc step with

crates=[alloc,compiler_builtins,core,panic_abort,panic_unwind,proc_macro,rustc-std-workspace-core,std,std_detect,sysroot,test,unwind]

but then again later with

crates=[]

then I think we rely on the fact that they can unify to not have this invalidate the previous build cache (?)

jieyouxu · 2025-08-10T04:35:17Z

src/bootstrap/src/core/builder/tests.rs

+        [doc] book (book) <host>
+        [doc] book/first-edition (book) <host>
+        [doc] book/second-edition (book) <host>
+        [doc] book/2018-edition (book) <host>
+        [build] rustdoc 1 <host>
+        [doc] rustc 1 <host> -> standalone 2 <host>


Question: wait, are we building less than we should be? I.e. there are two hosts, $\text{host}_{1} := \text{"host"}$ and $\text{host}_{1} := \text{"TEST-TRIPLE-1"}$. Or is this an instance where the "host" is actually the build platform and not actually the host platform? I.e. under the scenario where bootstrap is ran on a different platform than where the stage 1 compiler would be ran (?)

Hm... or taking a step back, what does the "hosts" config actually mean in bootstrap?

jieyouxu · 2025-08-10T04:40:54Z

@rustbot author

rustbot assigned jieyouxu Aug 6, 2025

Kobzol added 8 commits August 8, 2025 08:00

Forbid documenting anything on stage 0

d8dca72

Fix staging for doc compiler

3d471c7

Update Reference doc step

abd1e28

Update RustcBook doc step

2824572

Update Standalone and Releases doc steps

db44fe7

Fix documentation of tools

2639a3a

Update Std doc step

bd620c9

Update doc CI steps stage 2

a3b3576

As they were previously.

Kobzol force-pushed the bootstrap-doc branch from ad1b0bc to a3b3576 Compare August 8, 2025 06:15

Update tests

9a68c5d

Kobzol marked this pull request as ready for review August 8, 2025 06:17

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 Aug 8, 2025

Add change tracker entry

0bd1b63

jieyouxu reviewed Aug 10, 2025

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 Aug 10, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Enforce in bootstrap that doc must have stage at least 1 #145011

Enforce in bootstrap that doc must have stage at least 1 #145011

Kobzol commented Aug 6, 2025 •

edited

Loading

Uh oh!

bors commented Aug 7, 2025

Uh oh!

rustbot commented Aug 8, 2025

Uh oh!

Kobzol commented Aug 8, 2025

Uh oh!

jieyouxu left a comment

Uh oh!

jieyouxu Aug 10, 2025

Uh oh!

jieyouxu Aug 10, 2025

Uh oh!

jieyouxu Aug 10, 2025

Uh oh!

jieyouxu Aug 10, 2025

Uh oh!

jieyouxu Aug 10, 2025

Uh oh!

jieyouxu Aug 10, 2025

Uh oh!

jieyouxu Aug 10, 2025

Uh oh!

Uh oh!

jieyouxu Aug 10, 2025

Uh oh!

jieyouxu Aug 10, 2025

Uh oh!

jieyouxu commented Aug 10, 2025

Uh oh!

Uh oh!

		/// It is always done using a stage 1+ compiler, because it references in-tree compiler/stdlib
		/// concepts.

		// Build rustc docs so that we generate relative links.
		run.builder.ensure(Rustc::from_build_compiler(run.builder, compilers.build_compiler(), target));

		[build] rustdoc 0 <host>
		[doc] rustc 0 <host> -> Compiletest 1 <host>

		[doc] rustc 2 <host> -> std 2 <host> crates=[]
		[doc] rustc 2 <host> -> std 2 <target1> crates=[]

Enforce in bootstrap that doc must have stage at least 1 #145011

Are you sure you want to change the base?

Enforce in bootstrap that doc must have stage at least 1 #145011

Conversation

Kobzol commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bors commented Aug 7, 2025

Uh oh!

rustbot commented Aug 8, 2025

Uh oh!

Kobzol commented Aug 8, 2025

Uh oh!

jieyouxu left a comment

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!

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jieyouxu commented Aug 10, 2025

Uh oh!

Uh oh!

Kobzol commented Aug 6, 2025 •

edited

Loading