Auto merge of #137215 - onur-ozkan:rustc-tool-build-stages, r=jieyouxu,Kobzol

stabilize stage management for rustc tools

https://github.com/rust-lang/rust/pull/135990 got out of control due to excessive complexity. This PR aims to achieve the same goal with a simpler approach, likely through multiple smaller PRs. I will keep the other one read-only and open as a reference for future work.

This work stabilizes the staging logic for `ToolRustc` programs, so you no longer need to handle build and target compilers separately in steps. Previously, most tools didn't do this correctly, which was causing the compiler to be built twice (e.g., `x test cargo --stage 1` would compile the stage 2 compiler before, but now it only compiles the stage 1 compiler).

I also tried to document how we should write `ToolRustc` steps as they are quite different and require more attention than other tools.

Next goal is to stabilize how stages are handled for the rustc itself. Currently, `x build --stage 1` builds the stage 1 compiler which is fine, but `x build compiler --stage 1` builds stage 2 compiler.

~~for now, r? ghost~~

2 files changed, 24 insertions, 0 deletions

diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md
index 91c4aeacbd7..106db508ebb 100644
--- a/src/doc/rustc-dev-guide/src/SUMMARY.md
+++ b/src/doc/rustc-dev-guide/src/SUMMARY.md
@@ -75,6 +75,7 @@
 - [Prologue](./building/bootstrapping/intro.md)
 - [What Bootstrapping does](./building/bootstrapping/what-bootstrapping-does.md)
 - [How Bootstrap does it](./building/bootstrapping/how-bootstrap-does-it.md)
+- [Writing tools in Bootstrap](./building/bootstrapping/writing-tools-in-bootstrap.md)
 - [Debugging bootstrap](./building/bootstrapping/debugging-bootstrap.md)
 
 # High-level Compiler Architecture
diff --git a/src/doc/rustc-dev-guide/src/building/bootstrapping/writing-tools-in-bootstrap.md b/src/doc/rustc-dev-guide/src/building/bootstrapping/writing-tools-in-bootstrap.md
new file mode 100644
index 00000000000..6046d5b133d
--- /dev/null
+++ b/src/doc/rustc-dev-guide/src/building/bootstrapping/writing-tools-in-bootstrap.md
@@ -0,0 +1,23 @@
+# Writing tools in Bootstrap
+
+There are three types of tools you can write in bootstrap:
+
+- **`Mode::ToolBootstrap`**
+  Use this for tools that don’t need anything from the in-tree compiler and can run with the stage0 `rustc`.
+  The output is placed in the "stage0-bootstrap-tools" directory. This mode is for general-purpose tools built
+  entirely with the stage0 compiler, including target libraries and only works for stage 0.
+
+- **`Mode::ToolStd`**
+  Use this for tools that rely on the locally built std. The output goes into the "stageN-tools" directory.
+  This mode is rarely used, mainly for `compiletest` which requires `libtest`.
+
+- **`Mode::ToolRustc`**
+  Use this for tools that depend on both the locally built `rustc` and the target `std`. This is more complex than
+  the other modes because the tool must be built with the same compiler used for `rustc` and placed in the "stageN-tools"
+  directory. When you choose `Mode::ToolRustc`, `ToolBuild` implementation takes care of this automatically.
+  If you need to use the builder’s compiler for something specific, you can get it from `ToolBuildResult`, which is
+  returned by the tool's [`Step`].
+
+Regardless of the tool type you must return `ToolBuildResult` from the tool’s [`Step`] implementation and use `ToolBuild` inside it.
+
+[`Step`]: https://doc.rust-lang.org/nightly/nightly-rustc/bootstrap/core/builder/trait.Step.html