From a2fa934927a3d39860572f722bbe5f3cb691cf19 Mon Sep 17 00:00:00 2001 From: Jubilee Young Date: Sun, 21 Apr 2024 13:21:36 -0700 Subject: [PATCH 1/9] bootstrap: Describe build_steps::test for 2024 The description was most accurate when it was still called rustbuild, and I presume indeed did mostly run in CI. It has become something more so try to describe it better for current-day usage. --- src/bootstrap/src/core/build_steps/test.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/bootstrap/src/core/build_steps/test.rs b/src/bootstrap/src/core/build_steps/test.rs index 1980980b6d05c..867b359ccb133 100644 --- a/src/bootstrap/src/core/build_steps/test.rs +++ b/src/bootstrap/src/core/build_steps/test.rs @@ -1,7 +1,7 @@ -//! Implementation of the test-related targets of the build system. +//! Build-and-run steps for `./x.py test` test fixtures //! -//! This file implements the various regression test suites that we execute on -//! our CI. +//! `./x.py test` (aka [`Kind::Test`]) is currently allowed to reach build steps in other modules. +//! However, this contains ~all test parts we expect people to be able to build and run locally. use std::env; use std::ffi::OsStr; From 2042616134048f5226a97e405cb8357cde355e36 Mon Sep 17 00:00:00 2001 From: Jubilee Young Date: Sun, 21 Apr 2024 13:32:46 -0700 Subject: [PATCH 2/9] bootstrap: Describe build_steps::run --- src/bootstrap/src/core/build_steps/run.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/bootstrap/src/core/build_steps/run.rs b/src/bootstrap/src/core/build_steps/run.rs index 7028bffea5442..0a428ec5ca0a2 100644 --- a/src/bootstrap/src/core/build_steps/run.rs +++ b/src/bootstrap/src/core/build_steps/run.rs @@ -1,3 +1,8 @@ +//! Build-and-run steps for in-repo tools +//! +//! A bit of a hodge-podge as e.g. if a tool's a test fixture it should be in `build_steps::test`. +//! If it can be reached from `./x.py run` it can go here. + use std::path::PathBuf; use std::process::Command; From 35ed725cd2c586b0aa5ebf3d2182c69e1cb0e392 Mon Sep 17 00:00:00 2001 From: Jubilee Young Date: Sun, 21 Apr 2024 13:31:41 -0700 Subject: [PATCH 3/9] bootstrap: Describe build_steps::toolstate --- src/bootstrap/src/core/build_steps/toolstate.rs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/bootstrap/src/core/build_steps/toolstate.rs b/src/bootstrap/src/core/build_steps/toolstate.rs index deb782cad0ce4..6065aa1414fe1 100644 --- a/src/bootstrap/src/core/build_steps/toolstate.rs +++ b/src/bootstrap/src/core/build_steps/toolstate.rs @@ -1,3 +1,7 @@ +//! Toolstate checks to keep tools building +//! +//! Reachable via `./x.py test` but mostly relevant for CI, since it isn't run locally by default. + use crate::core::builder::{Builder, RunConfig, ShouldRun, Step}; use crate::utils::helpers::t; use serde_derive::{Deserialize, Serialize}; From 8c40d0efa7881d49895398c8536c212c1e9e93cf Mon Sep 17 00:00:00 2001 From: Jubilee Young Date: Sun, 21 Apr 2024 13:39:11 -0700 Subject: [PATCH 4/9] bootstrap: Describe build_steps::suggest --- src/bootstrap/src/core/build_steps/suggest.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/bootstrap/src/core/build_steps/suggest.rs b/src/bootstrap/src/core/build_steps/suggest.rs index c057fa9a5667b..754d1e61da8c6 100644 --- a/src/bootstrap/src/core/build_steps/suggest.rs +++ b/src/bootstrap/src/core/build_steps/suggest.rs @@ -1,3 +1,5 @@ +//! Attempt to magically identify good tests to run + #![cfg_attr(feature = "build-metrics", allow(unused))] use clap::Parser; From bc37f9e2040235a4e6b8bed6c6db4f064fea15cc Mon Sep 17 00:00:00 2001 From: Jubilee Young Date: Sun, 21 Apr 2024 13:32:59 -0700 Subject: [PATCH 5/9] bootstrap: Describe build_steps::setup --- src/bootstrap/src/core/build_steps/setup.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/bootstrap/src/core/build_steps/setup.rs b/src/bootstrap/src/core/build_steps/setup.rs index 7bc68b5aec11f..6b2b7e5dcaca2 100644 --- a/src/bootstrap/src/core/build_steps/setup.rs +++ b/src/bootstrap/src/core/build_steps/setup.rs @@ -1,3 +1,9 @@ +//! First time setup of a dev environment +//! +//! These are build-and-run steps for `./x.py setup`, which allows quickly setting up the directory +//! for modifying, building, and running the compiler and library. The main convenience is to allow +//! not having to painstakingly set every single option in config.toml. + use crate::core::builder::{Builder, RunConfig, ShouldRun, Step}; use crate::t; use crate::utils::change_tracker::CONFIG_CHANGE_HISTORY; From ce27ea935edd4cc04455e6abfdc8ba8ed86be451 Mon Sep 17 00:00:00 2001 From: Jubilee Young Date: Sun, 21 Apr 2024 13:52:42 -0700 Subject: [PATCH 6/9] bootstrap: Demagic a repeating path --- src/bootstrap/src/core/build_steps/setup.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/bootstrap/src/core/build_steps/setup.rs b/src/bootstrap/src/core/build_steps/setup.rs index 6b2b7e5dcaca2..a01d20e8c21ad 100644 --- a/src/bootstrap/src/core/build_steps/setup.rs +++ b/src/bootstrap/src/core/build_steps/setup.rs @@ -31,6 +31,8 @@ pub enum Profile { None, } +static PROFILE_DIR: &str = "src/bootstrap/defaults"; + /// A list of historical hashes of `src/etc/rust_analyzer_settings.json`. /// New entries should be appended whenever this is updated so we can detect /// outdated vs. user-modified settings files. @@ -47,7 +49,7 @@ static RUST_ANALYZER_SETTINGS: &str = include_str!("../../../../etc/rust_analyze impl Profile { fn include_path(&self, src_path: &Path) -> PathBuf { - PathBuf::from(format!("{}/src/bootstrap/defaults/config.{}.toml", src_path.display(), self)) + PathBuf::from(format!("{}/{PROFILE_DIR}/config.{}.toml", src_path.display(), self)) } pub fn all() -> impl Iterator { @@ -227,7 +229,7 @@ fn setup_config_toml(path: &PathBuf, profile: Profile, config: &Config) { let latest_change_id = CONFIG_CHANGE_HISTORY.last().unwrap().change_id; let settings = format!( - "# Includes one of the default files in src/bootstrap/defaults\n\ + "# Includes one of the default files in {PROFILE_DIR}\n\ profile = \"{profile}\"\n\ change-id = {latest_change_id}\n" ); From b756b11ae399413ec728e3a01393a4eba00be2fc Mon Sep 17 00:00:00 2001 From: Jubilee Young Date: Sun, 21 Apr 2024 18:39:48 -0700 Subject: [PATCH 7/9] bootstrap: Describe build_steps::clean how 2024 knows it --- src/bootstrap/src/core/build_steps/clean.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/bootstrap/src/core/build_steps/clean.rs b/src/bootstrap/src/core/build_steps/clean.rs index 9e103a350e654..10303f6af9e18 100644 --- a/src/bootstrap/src/core/build_steps/clean.rs +++ b/src/bootstrap/src/core/build_steps/clean.rs @@ -1,4 +1,4 @@ -//! Implementation of `make clean` in rustbuild. +//! `./x.py clean` //! //! Responsible for cleaning out a build directory of all old and stale //! artifacts to prepare for a fresh build. Currently doesn't remove the From 32aadc516bb2dad9913d2600da5dd1d4478e552f Mon Sep 17 00:00:00 2001 From: Jubilee Young Date: Wed, 24 Apr 2024 16:47:47 -0700 Subject: [PATCH 8/9] bootstrap: link to the forge about toolstate --- src/bootstrap/src/core/build_steps/toolstate.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/bootstrap/src/core/build_steps/toolstate.rs b/src/bootstrap/src/core/build_steps/toolstate.rs index 6065aa1414fe1..c123bc764ffe5 100644 --- a/src/bootstrap/src/core/build_steps/toolstate.rs +++ b/src/bootstrap/src/core/build_steps/toolstate.rs @@ -1,6 +1,8 @@ -//! Toolstate checks to keep tools building +//! [Toolstate] checks to keep tools building //! //! Reachable via `./x.py test` but mostly relevant for CI, since it isn't run locally by default. +//! +//! [Toolstate]: https://forge.rust-lang.org/infra/toolstate.html use crate::core::builder::{Builder, RunConfig, ShouldRun, Step}; use crate::utils::helpers::t; From f4e02a193e39958df1cee6abeefc62e50354fdea Mon Sep 17 00:00:00 2001 From: Jubilee Young Date: Wed, 24 Apr 2024 16:56:41 -0700 Subject: [PATCH 9/9] bootstrap: reinterpret the main advantage of x.py setup --- src/bootstrap/src/core/build_steps/setup.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/bootstrap/src/core/build_steps/setup.rs b/src/bootstrap/src/core/build_steps/setup.rs index a01d20e8c21ad..6200941458025 100644 --- a/src/bootstrap/src/core/build_steps/setup.rs +++ b/src/bootstrap/src/core/build_steps/setup.rs @@ -1,8 +1,9 @@ //! First time setup of a dev environment //! //! These are build-and-run steps for `./x.py setup`, which allows quickly setting up the directory -//! for modifying, building, and running the compiler and library. The main convenience is to allow -//! not having to painstakingly set every single option in config.toml. +//! for modifying, building, and running the compiler and library. Running arbitrary configuration +//! allows setting up things that cannot be simply captured inside the config.toml, in addition to +//! leading people away from manually editing most of the config.toml values. use crate::core::builder::{Builder, RunConfig, ShouldRun, Step}; use crate::t;