From fcf5820837d0dd9f012b5d0cc411914855221015 Mon Sep 17 00:00:00 2001 From: FrancescoV1985 Date: Sun, 31 Aug 2025 12:42:34 +0200 Subject: [PATCH 1/7] 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/7] 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/7] 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/7] 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"); From 16f4d4105b663347ab0d65a83bd09f25b1aa8d70 Mon Sep 17 00:00:00 2001 From: FrancescoV1985 <62872737+FrancescoV1985@users.noreply.github.com> Date: Mon, 27 Oct 2025 09:47:40 +0100 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: antoyo --- CONTRIBUTING.md | 2 -- build_system/src/build.rs | 4 ++-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d5acc741d31..205eb9771d3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,8 +25,6 @@ We encourage new contributors to join our communication channels and introduce t ## Understanding Core Concepts - - ### Sysroot & compilation flags #### What *is* the sysroot? diff --git a/build_system/src/build.rs b/build_system/src/build.rs index b3bc1007529..bf56fb80365 100644 --- a/build_system/src/build.rs +++ b/build_system/src/build.rs @@ -45,7 +45,7 @@ impl BuildArg { println!( r#" `build` command help: - --release : Build backend in release mode with optimized dependencies without rebuilding sysroot + --release : Build backend in release mode with optimized dependencies --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 @@ -53,7 +53,7 @@ impl BuildArg { 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 has no effect if `--sysroot` is not specified. It should not be used on its own."# ); ConfigInfo::show_usage(); From 91a6e04da92af08281ac154d1bebc91af717020e Mon Sep 17 00:00:00 2001 From: Harin Date: Wed, 26 Nov 2025 00:20:54 +0530 Subject: [PATCH 6/7] updated document --- CONTRIBUTING.md | 10 ++++++---- build_system/src/build.rs | 4 ++-- build_system/src/config.rs | 2 +- build_system/src/test.rs | 6 ------ 4 files changed, 9 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 205eb9771d3..3f8abc0c2fa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,11 +50,13 @@ That is exactly what the `--sysroot`, `--release-sysroot` and `--release` flag s | Command | Backend Profile | Sysroot Profile | Usage Scenario | |--------------------------------------------|-------------------------------|----------------------------------|------------------------------------------------------------| -| `./y.sh build` |  dev (optimized + debuginfo) |  X |  Build backend in dev. mode with optimized dependencies without rebuilding sysroot | +| `./y.sh build` |  dev* |  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 | +| `./y.sh build --release --sysroot` |  release (optimized) |  dev* |  Build backend in release mode with optimized dependencies and sysroot in dev mode (unoptimized) | +| `./y.sh build --sysroot` |  dev* |  dev* |  Build backend in dev mode with optimized dependencies and sysroot in dev mode (unoptimized) | +| `./y.sh build --release-sysroot --sysroot`|  dev* |  release (optimized) |  Build backend in dev mode and sysroot in release mode, both with optimized dependencies | + +\* In `dev` mode, dependencies are compiled with optimizations, while the code of the backend itself is not. Note: `--release-sysroot` should not be used without `--sysroot`. diff --git a/build_system/src/build.rs b/build_system/src/build.rs index bf56fb80365..85b72bf5f61 100644 --- a/build_system/src/build.rs +++ b/build_system/src/build.rs @@ -45,7 +45,6 @@ impl BuildArg { println!( r#" `build` command help: - --release : Build backend in release mode with optimized dependencies --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 @@ -54,7 +53,8 @@ impl BuildArg { --release-sysroot : When combined with --sysroot, additionally build the sysroot in release mode with optimized dependencies. It has no effect if `--sysroot` is not specified. - It should not be used on its own."# + It should not be used on its own. + --sysroot-panic-abort : Build the sysroot without unwinding support"# ); ConfigInfo::show_usage(); println!(" --help : Show this help"); diff --git a/build_system/src/config.rs b/build_system/src/config.rs index 37b0a77f621..817949cfe30 100644 --- a/build_system/src/config.rs +++ b/build_system/src/config.rs @@ -475,8 +475,8 @@ impl ConfigInfo { " --features [arg] : Add a new feature [arg] --target-triple [arg] : Set the target triple to [arg] --target [arg] : Set the target to [arg] + --release : Build backend in release mode with optimized dependencies --out-dir : Location where the files will be generated - --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 --cg_gcc-path : Location of the rustc_codegen_gcc root folder (used diff --git a/build_system/src/test.rs b/build_system/src/test.rs index 3dd3fce2eec..f7a12f78bcf 100644 --- a/build_system/src/test.rs +++ b/build_system/src/test.rs @@ -64,8 +64,6 @@ fn show_usage() { r#" `test` command help: - --release : Build codegen in release mode - --sysroot-panic-abort : Build the sysroot without unwinding support. --features [arg] : Add a new feature [arg] --use-system-gcc : Use system installed libgccjit --build-only : Only build rustc_codegen_gcc then exits @@ -92,7 +90,6 @@ struct TestArg { test_args: Vec, nb_parts: Option, current_part: Option, - sysroot_panic_abort: bool, config_info: ConfigInfo, sysroot_features: Vec, keep_lto_tests: bool, @@ -128,9 +125,6 @@ impl TestArg { test_arg.current_part = Some(get_number_after_arg(&mut args, "--current-part")?); } - "--sysroot-panic-abort" => { - test_arg.sysroot_panic_abort = true; - } "--keep-lto-tests" => { test_arg.keep_lto_tests = true; } From 34e96dc1159cb0867b1af0396f995f6c943419d6 Mon Sep 17 00:00:00 2001 From: Harin Date: Thu, 27 Nov 2025 22:01:26 +0530 Subject: [PATCH 7/7] updated documentation --- CONTRIBUTING.md | 10 +++++----- build_system/src/build.rs | 6 +++--- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3f8abc0c2fa..8f81ecca445 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,16 +50,16 @@ That is exactly what the `--sysroot`, `--release-sysroot` and `--release` flag s | Command | Backend Profile | Sysroot Profile | Usage Scenario | |--------------------------------------------|-------------------------------|----------------------------------|------------------------------------------------------------| -| `./y.sh build` |  dev* |  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* |  Build backend in release mode with optimized dependencies and sysroot in dev mode (unoptimized) | -| `./y.sh build --sysroot` |  dev* |  dev* |  Build backend in dev mode with optimized dependencies and sysroot in dev mode (unoptimized) | +| `./y.sh build` |  dev* |  n/a |  Build backend in dev mode with optimized dependencies without rebuilding sysroot | +| `./y.sh build --release` |  release (optimized) |  n/a |  Build backend in release mode with optimized dependencies without rebuilding sysroot | +| `./y.sh build --release --sysroot` |  release (optimized) |  dev |  Build backend in release mode with optimized dependencies and sysroot in dev mode (unoptimized) | +| `./y.sh build --sysroot` |  dev* |  dev |  Build backend in dev mode with optimized dependencies and sysroot in dev mode (unoptimized) | | `./y.sh build --release-sysroot --sysroot`|  dev* |  release (optimized) |  Build backend in dev mode and sysroot in release mode, both with optimized dependencies | \* In `dev` mode, dependencies are compiled with optimizations, while the code of the backend itself is not. -Note: `--release-sysroot` should not be used without `--sysroot`. +Note: `--release-sysroot` must be used together with `--sysroot`. ### Common Development Tasks diff --git a/build_system/src/build.rs b/build_system/src/build.rs index 85b72bf5f61..e4445ad7108 100644 --- a/build_system/src/build.rs +++ b/build_system/src/build.rs @@ -45,11 +45,11 @@ impl BuildArg { println!( r#" `build` command help: - --sysroot : When used on its own, build backend in dev. mode with optimized dependencies - and sysroot in dev. mode (unoptimized) + --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 + 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. It has no effect if `--sysroot` is not specified.