write x.py's help for saving output time

Currently x.py help (or x.py --help) builds bootstrap binary everytime, but it delays printing help.
This change saves the current help text into a file. x.py help prints the file and doesn't touch bootstrap binary.
x.py test bootstrap checks if the file is up to date.

Author: Shunpoco

src/bootstrap/bootstrap.py

@@ -1375,13 +1375,17 @@ def main():
     args = parse_args(sys.argv)
     help_triggered = args.help or len(sys.argv) == 1
 
-    # If the user is asking for help, let them know that the whole download-and-build
-    # process has to happen before anything is printed out.
+    # If the user is asking for help, it prints commands from the saved file.
     if help_triggered:
-        eprint(
-            "INFO: Downloading and building bootstrap before processing --help command.\n"
-            "      See src/bootstrap/README.md for help with common commands."
-        )
+        try:
+            with open(os.path.join(os.path.dirname(__file__), "../etc/xhelp"), "r") as f:
+                # The file from bootstrap func already has newline.
+                print(f.read(), end="")
+                sys.exit(0)
+        except Exception as error:
+            eprint(f"ERROR: unable to run help: {error}")
+            eprint("x.py run generate-help may solve the problem.")
+            sys.exit(1)
 
     exit_code = 0
     success_word = "successfully"
@@ -1395,13 +1399,13 @@ def main():
             eprint(error)
         success_word = "unsuccessfully"
 
-    if not help_triggered:
-        eprint(
-            "Build completed",
-            success_word,
-            "in",
-            format_build_time(time() - start_time),
-        )
+    eprint(
+        "Build completed",
+        success_word,
+        "in",
+        format_build_time(time() - start_time),
+    )
+
     sys.exit(exit_code)
 
 

src/bootstrap/src/core/build_steps/run.rs

@@ -14,7 +14,7 @@ use crate::core::build_steps::tool::{self, RustcPrivateCompilers, SourceType, To
 use crate::core::build_steps::vendor::{Vendor, default_paths_to_vendor};
 use crate::core::builder::{Builder, Kind, RunConfig, ShouldRun, Step, StepMetadata};
 use crate::core::config::TargetSelection;
-use crate::core::config::flags::get_completion;
+use crate::core::config::flags::{get_completion, get_help};
 use crate::utils::exec::command;
 use crate::{Mode, t};
 
@@ -501,3 +501,31 @@ impl Step for Rustfmt {
         rustfmt.into_cmd().run(builder);
     }
 }
+
+/// Return the path of x.py's help.
+pub fn get_help_path(builder: &Builder<'_>) -> PathBuf {
+    builder.src.join("src/etc/xhelp")
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct GenerateHelp;
+
+impl Step for GenerateHelp {
+    type Output = ();
+
+    fn run(self, builder: &Builder<'_>) {
+        let path = get_help_path(builder);
+        if let Some(help) = get_help(&path) {
+            std::fs::write(&path, help)
+                .unwrap_or_else(|e| panic!("writing help into {} failed: {e:?}", path.display()));
+        }
+    }
+
+    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
+        run.alias("generate-help")
+    }
+
+    fn make_run(run: RunConfig<'_>) {
+        run.builder.ensure(GenerateHelp)
+    }
+}

src/bootstrap/src/core/build_steps/test.rs

@@ -15,7 +15,7 @@ use crate::core::build_steps::compile::{Std, run_cargo};
 use crate::core::build_steps::doc::{DocumentationFormat, prepare_doc_compiler};
 use crate::core::build_steps::gcc::{Gcc, add_cg_gcc_cargo_flags};
 use crate::core::build_steps::llvm::get_llvm_version;
-use crate::core::build_steps::run::get_completion_paths;
+use crate::core::build_steps::run::{get_completion_paths, get_help_path};
 use crate::core::build_steps::synthetic_targets::MirOptPanicAbortSyntheticTarget;
 use crate::core::build_steps::tool::{
     self, COMPILETEST_ALLOW_FEATURES, RustcPrivateCompilers, SourceType,
@@ -28,7 +28,7 @@ use crate::core::builder::{
     crate_description,
 };
 use crate::core::config::TargetSelection;
-use crate::core::config::flags::{Subcommand, get_completion};
+use crate::core::config::flags::{Subcommand, get_completion, get_help};
 use crate::utils::build_stamp::{self, BuildStamp};
 use crate::utils::exec::{BootstrapCommand, command};
 use crate::utils::helpers::{
@@ -1293,6 +1293,15 @@ HELP: to skip test's attempt to check tidiness, pass `--skip src/tools/tidy` to
             );
             crate::exit!(1);
         }
+
+        builder.info("x.py help check");
+        let help_path = get_help_path(builder);
+        if builder.config.cmd.bless() {
+            builder.ensure(crate::core::build_steps::run::GenerateHelp);
+        } else if get_help(&help_path).is_some() {
+            eprintln!("x.py help was changed; run `x.py run generate-help` to update them");
+            crate::exit!(1);
+        }
     }
 
     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {

src/bootstrap/src/core/builder/mod.rs

@@ -1224,6 +1224,7 @@ impl<'a> Builder<'a> {
                 run::CyclicStep,
                 run::CoverageDump,
                 run::Rustfmt,
+                run::GenerateHelp,
             ),
             Kind::Setup => {
                 describe!(setup::Profile, setup::Hook, setup::Link, setup::Editor)

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

@@ -701,3 +701,25 @@ pub fn get_completion(shell: &dyn Generator, path: &Path) -> Option<String> {
     }
     Some(String::from_utf8(buf).expect("completion script should be UTF-8"))
 }
+
+/// Return the help of the bootstrap if the result differs from the current
+/// help in `path`. It always returns the help if `path` does not exist.
+pub fn get_help(path: &Path) -> Option<String> {
+    let mut cmd = Flags::command();
+    let cur_help = if !path.exists() {
+        String::new()
+    } else {
+        std::fs::read_to_string(path).unwrap_or_else(|_| {
+            eprintln!("couldn't read {}", path.display());
+            crate::exit!(1)
+        })
+    };
+
+    let new_help: clap::builder::StyledStr = cmd.render_help();
+
+    if new_help.to_string() == cur_help {
+        return None;
+    }
+
+    Some(new_help.to_string())
+}

src/etc/xhelp

@@ -0,0 +1,96 @@
+
+Usage: x.py <subcommand> [options] [<paths>...]
+
+Commands:
+  build    Compile either the compiler or libraries
+  check    Compile either the compiler or libraries, using cargo check
+  clippy   Run Clippy (uses rustup/cargo-installed clippy binary)
+  fix      Run cargo fix
+  fmt      Run rustfmt
+  doc      Build documentation
+  test     Build and run some test suites
+  miri     Build and run some test suites *in Miri*
+  bench    Build and run some benchmarks
+  clean    Clean out build directories
+  dist     Build distribution artifacts
+  install  Install distribution artifacts
+  run      Run tools contained in this repository
+  setup    Set up the environment for development
+  vendor   Vendor dependencies
+  perf     Perform profiling and benchmarking of the compiler using `rustc-perf`
+
+Arguments:
+  [PATHS]...  paths for the subcommand
+  [ARGS]...   arguments passed to subcommands
+
+Options:
+  -v, --verbose...
+          use verbose output (-vv for very verbose)
+  -i, --incremental
+          use incremental compilation
+      --config <FILE>
+          TOML configuration file for build
+      --build-dir <DIR>
+          Build directory, overrides `build.build-dir` in `bootstrap.toml`
+      --build <BUILD>
+          host target of the stage0 compiler
+      --host <HOST>
+          host targets to build
+      --target <TARGET>
+          target targets to build
+      --exclude <PATH>
+          build paths to exclude
+      --skip <PATH>
+          build paths to skip
+      --include-default-paths
+          include default paths in addition to the provided ones
+      --rustc-error-format <RUSTC_ERROR_FORMAT>
+          rustc error format
+      --on-fail <CMD>
+          command to run on failure
+      --dry-run
+          dry run; don't build anything
+      --dump-bootstrap-shims
+          Indicates whether to dump the work done from bootstrap shims
+      --stage <N>
+          stage to build (indicates compiler to use/test, e.g., stage 0 uses the bootstrap compiler, stage 1 the stage 0 rustc artifacts, etc.)
+      --keep-stage <N>
+          stage(s) to keep without recompiling (pass multiple times to keep e.g., both stages 0 and 1)
+      --keep-stage-std <N>
+          stage(s) of the standard library to keep without recompiling (pass multiple times to keep e.g., both stages 0 and 1)
+      --src <DIR>
+          path to the root of the rust checkout
+  -j, --jobs <JOBS>
+          number of jobs to run in parallel
+      --warnings <deny|warn>
+          if value is deny, will deny warnings if value is warn, will emit warnings otherwise, use the default configured behaviour [default: default] [possible values: deny, warn, default]
+      --json-output
+          use message-format=json
+      --compile-time-deps
+          only build proc-macros and build scripts (for rust-analyzer)
+      --color <STYLE>
+          whether to use color in cargo and rustc output [default: auto] [possible values: always, never, auto]
+      --bypass-bootstrap-lock
+          Bootstrap uses this value to decide whether it should bypass locking the build process. This is rarely needed (e.g., compiling the std library for different targets in parallel)
+      --rust-profile-generate <PROFILE>
+          generate PGO profile with rustc build
+      --rust-profile-use <PROFILE>
+          use PGO profile for rustc build
+      --llvm-profile-use <PROFILE>
+          use PGO profile for LLVM build
+      --llvm-profile-generate
+          generate PGO profile with llvm built for rustc
+      --enable-bolt-settings
+          Enable BOLT link flags
+      --skip-stage0-validation
+          Skip stage0 compiler validation
+      --reproducible-artifact <REPRODUCIBLE_ARTIFACT>
+          Additional reproducible artifacts that should be added to the reproducible artifacts archive
+      --set <section.option=value>
+          override options in bootstrap.toml
+      --ci <bool>
+          Make bootstrap to behave as it's running on the CI environment or not [possible values: true, false]
+      --skip-std-check-if-no-download-rustc
+          Skip checking the standard library if `rust.download-rustc` isn't available. This is mostly for RA as building the stage1 compiler to check the library tree on each code change might be too much for some computers
+  -h, --help
+          Print help (see more with '--help')