From fcf5820837d0dd9f012b5d0cc411914855221015 Mon Sep 17 00:00:00 2001 From: FrancescoV1985 Date: Sun, 31 Aug 2025 12:42:34 +0200 Subject: [PATCH 1/4] document combination of flags --- CONTRIBUTING.md | 39 ++++++++++++++++++++++++++++++++++++++ build_system/src/build.rs | 4 +--- build_system/src/config.rs | 15 ++++++++++++--- 3 files changed, 52 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 54cba0e6de3..0e3c3b47f71 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,6 +25,45 @@ We encourage new contributors to join our communication channels and introduce t ## Understanding Core Concepts + + +### Sysroot & compilation flags + +#### What *is* the sysroot? +The **sysroot** is the directory that stores the compiled standard +library (`core`, `alloc`, `std`, `test`, …) and compiler built-ins. +Rustup ships these libraries **pre-compiled with LLVM**. + +Because **rustc_codegen_gcc** replaces LLVM with the GCC backend, the shipped +LLVM artefacts are **incompatible**. +Therefore the standard library must be **rebuilt with GCC** before ordinary Rust crates can be compiled. + +The freshly compiled sysroot ends up in +`build/build_sysroot/...`. + +A rebuild of sysroot is needed when + +* the backend changes in a way that affects code generation, or +* the user switches toolchains / updates submodules. + +Both backend and sysroot can be built using different [profiles](https://doc.rust-lang.org/cargo/reference/profiles.html#default-profiles). +That is exactly what the `--sysroot`, `--release-sysroot` and `--release` flag supported by the frontend script `y.sh` take care of. + + +#### Typical flag combinations + +| Command | Backend Profile | Sysroot Profile | Usage Scenario | +|--------------------------------------------|-------------------------------|----------------------------------|------------------------------------------------------------| +| `./y.sh build` |  dev (optimized + debuginfo) |  X |  Optimize backend with debug capabilities | +| `./y.sh build --release` |  release (optimized) |  X |  Optimize backend without rebuilding sysroot | +| `./y.sh build --release --release-sysroot`|  release (optimized) |  X |  Same as --release | +| `./y.sh build --release --sysroot` |  release (optimized) |  dev (unoptimized + debuginfo) |  Optimize backend for release without full sysroot rebuild | +| `./y.sh build --sysroot` |  dev (optimized + debuginfo) |  dev (unoptimized + debuginfo) |  Full debug capabilities with optimized backend | +| `./y.sh build --release-sysroot` |  dev (optimized + debuginfo) |  X |  Build only optimized backend with debug capabilities | +| `./y.sh build --release-sysroot --sysroot`|  dev (optimized + debuginfo) |  release (optimized) |  Build optimized backend and sysroot for debugging and release, respectively | + + + ### Common Development Tasks #### Running Specific Tests diff --git a/build_system/src/build.rs b/build_system/src/build.rs index 94b40319f4a..85f2c1a9df1 100644 --- a/build_system/src/build.rs +++ b/build_system/src/build.rs @@ -44,9 +44,7 @@ impl BuildArg { fn usage() { println!( r#" -`build` command help: - - --sysroot : Build with sysroot"# +`build` command help:"# ); ConfigInfo::show_usage(); println!(" --help : Show this help"); diff --git a/build_system/src/config.rs b/build_system/src/config.rs index a5f802e293a..e44a4716c46 100644 --- a/build_system/src/config.rs +++ b/build_system/src/config.rs @@ -472,13 +472,22 @@ impl ConfigInfo { pub fn show_usage() { println!( - "\ + " --features [arg] : Add a new feature [arg] --target-triple [arg] : Set the target triple to [arg] --target [arg] : Set the target to [arg] --out-dir : Location where the files will be generated - --release : Build in release mode - --release-sysroot : Build sysroot in release mode + --release : Build and optimize the backend in release mode + --sysroot : When used on its own, build both + sysroot and backend in dev. mode. Only the backend is optimized. + When used together with --release, build and optimize the backend + in release mode instead of in dev. mode. + When used together with --release-sysroot, + build and optimize the sysroot in release mode instead of in dev. mode + --release-sysroot : When used on its own, build and optimize only the backend in dev. mode. + When combined with --release, it has no effect. + When combined with --sysroot, additionally + build and optimize the sysroot in release mode --sysroot-panic-abort : Build the sysroot without unwinding support --config-file : Location of the config file to be used --gcc-path : Location of the GCC root folder From 6d92a198a64b291ba18078b6e04d162b6cd04b5a Mon Sep 17 00:00:00 2001 From: FrancescoV1985 Date: Thu, 25 Sep 2025 11:28:14 +0200 Subject: [PATCH 2/4] updated code according to review's feedback --- CONTRIBUTING.md | 20 +++++++++----------- build_system/src/build.rs | 12 +++++++++++- build_system/src/config.rs | 11 ----------- 3 files changed, 20 insertions(+), 23 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0e3c3b47f71..d5acc741d31 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,9 +34,7 @@ The **sysroot** is the directory that stores the compiled standard library (`core`, `alloc`, `std`, `test`, …) and compiler built-ins. Rustup ships these libraries **pre-compiled with LLVM**. -Because **rustc_codegen_gcc** replaces LLVM with the GCC backend, the shipped -LLVM artefacts are **incompatible**. -Therefore the standard library must be **rebuilt with GCC** before ordinary Rust crates can be compiled. +**rustc_codegen_gcc** replaces LLVM with the GCC backend. The freshly compiled sysroot ends up in `build/build_sysroot/...`. @@ -47,22 +45,22 @@ A rebuild of sysroot is needed when * the user switches toolchains / updates submodules. Both backend and sysroot can be built using different [profiles](https://doc.rust-lang.org/cargo/reference/profiles.html#default-profiles). -That is exactly what the `--sysroot`, `--release-sysroot` and `--release` flag supported by the frontend script `y.sh` take care of. +That is exactly what the `--sysroot`, `--release-sysroot` and `--release` flag supported by the build system script `y.sh` take care of. #### Typical flag combinations | Command | Backend Profile | Sysroot Profile | Usage Scenario | |--------------------------------------------|-------------------------------|----------------------------------|------------------------------------------------------------| -| `./y.sh build` |  dev (optimized + debuginfo) |  X |  Optimize backend with debug capabilities | -| `./y.sh build --release` |  release (optimized) |  X |  Optimize backend without rebuilding sysroot | -| `./y.sh build --release --release-sysroot`|  release (optimized) |  X |  Same as --release | -| `./y.sh build --release --sysroot` |  release (optimized) |  dev (unoptimized + debuginfo) |  Optimize backend for release without full sysroot rebuild | -| `./y.sh build --sysroot` |  dev (optimized + debuginfo) |  dev (unoptimized + debuginfo) |  Full debug capabilities with optimized backend | -| `./y.sh build --release-sysroot` |  dev (optimized + debuginfo) |  X |  Build only optimized backend with debug capabilities | -| `./y.sh build --release-sysroot --sysroot`|  dev (optimized + debuginfo) |  release (optimized) |  Build optimized backend and sysroot for debugging and release, respectively | +| `./y.sh build` |  dev (optimized + debuginfo) |  X |  Build backend in dev. mode with optimized dependencies without rebuilding sysroot | +| `./y.sh build --release` |  release (optimized) |  X |  Build backend in release mode with optimized dependencies without rebuilding sysroot | +| `./y.sh build --release --sysroot` |  release (optimized) |  dev (unoptimized + debuginfo) |  Build backend in release mode with optimized dependencies and sysroot in dev. mode (unoptimized) | +| `./y.sh build --sysroot` |  dev (optimized + debuginfo) |  dev (unoptimized + debuginfo) |  Build backend in dev. mode with optimized dependencies and sysroot in dev. mode (unoptimized) | +| `./y.sh build --release-sysroot --sysroot`|  dev (optimized + debuginfo) |  release (optimized) |  Build backend in dev. mode and sysroot in release mode, both with optimized dependencies | +Note: `--release-sysroot` should not be used without `--sysroot`. + ### Common Development Tasks diff --git a/build_system/src/build.rs b/build_system/src/build.rs index 85f2c1a9df1..9b30de7dfd5 100644 --- a/build_system/src/build.rs +++ b/build_system/src/build.rs @@ -44,7 +44,17 @@ impl BuildArg { fn usage() { println!( r#" -`build` command help:"# +`build` command help: + --release : Build backend in release mode with optimized dependencies without rebuilding sysroot + --sysroot : When used on its own, build backend in dev. mode with optimized dependencies + and sysroot in dev. mode (unoptimized) + When used together with --release, build backend in release mode with optimized dependencies + When used together with --release-sysroot, + build the sysroot in release mode with optimized dependencies instead of in dev. mode + --release-sysroot : When combined with --sysroot, additionally + build the sysroot in release mode with optimized dependencies. + When combined with --release, it has no effect. + It should not be used on itw own."# ); ConfigInfo::show_usage(); println!(" --help : Show this help"); diff --git a/build_system/src/config.rs b/build_system/src/config.rs index e44a4716c46..4104f2bab2b 100644 --- a/build_system/src/config.rs +++ b/build_system/src/config.rs @@ -477,17 +477,6 @@ impl ConfigInfo { --target-triple [arg] : Set the target triple to [arg] --target [arg] : Set the target to [arg] --out-dir : Location where the files will be generated - --release : Build and optimize the backend in release mode - --sysroot : When used on its own, build both - sysroot and backend in dev. mode. Only the backend is optimized. - When used together with --release, build and optimize the backend - in release mode instead of in dev. mode. - When used together with --release-sysroot, - build and optimize the sysroot in release mode instead of in dev. mode - --release-sysroot : When used on its own, build and optimize only the backend in dev. mode. - When combined with --release, it has no effect. - When combined with --sysroot, additionally - build and optimize the sysroot in release mode --sysroot-panic-abort : Build the sysroot without unwinding support --config-file : Location of the config file to be used --gcc-path : Location of the GCC root folder From dd341202cc15ee277e9c8ab3d465217bd6eac4b3 Mon Sep 17 00:00:00 2001 From: FrancescoV1985 Date: Thu, 25 Sep 2025 11:59:02 +0200 Subject: [PATCH 3/4] remove new line --- build_system/src/config.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/build_system/src/config.rs b/build_system/src/config.rs index 4104f2bab2b..37b0a77f621 100644 --- a/build_system/src/config.rs +++ b/build_system/src/config.rs @@ -472,8 +472,7 @@ impl ConfigInfo { pub fn show_usage() { println!( - " - --features [arg] : Add a new feature [arg] + " --features [arg] : Add a new feature [arg] --target-triple [arg] : Set the target triple to [arg] --target [arg] : Set the target to [arg] --out-dir : Location where the files will be generated From d0adbbde680b74b485c8e92954bc682189a17968 Mon Sep 17 00:00:00 2001 From: FrancescoV1985 Date: Thu, 25 Sep 2025 12:36:43 +0200 Subject: [PATCH 4/4] fix typo --- build_system/src/build.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build_system/src/build.rs b/build_system/src/build.rs index 9b30de7dfd5..b3bc1007529 100644 --- a/build_system/src/build.rs +++ b/build_system/src/build.rs @@ -54,7 +54,7 @@ impl BuildArg { --release-sysroot : When combined with --sysroot, additionally build the sysroot in release mode with optimized dependencies. When combined with --release, it has no effect. - It should not be used on itw own."# + It should not be used on its own."# ); ConfigInfo::show_usage(); println!(" --help : Show this help");