Better document some combinations of flags (#808)

---------

Co-authored-by: FrancescoV1985 <franci.vi@tiscali.it>
Co-authored-by: FrancescoV1985 <62872737+FrancescoV1985@users.noreply.github.com>
Co-authored-by: antoyo <antoyo@users.noreply.github.com>

CONTRIBUTING.md

@@ -25,6 +25,43 @@ 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**.
+
+**rustc_codegen_gcc** replaces LLVM with the GCC backend.
+
+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 build system script `y.sh` take care of.
+
+
+#### Typical flag combinations
+
+| Command                                   | Backend Profile               | Sysroot Profile                  | Usage Scenario                                              |
+|--------------------------------------------|-------------------------------|----------------------------------|------------------------------------------------------------|
+| `./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` must be used together with `--sysroot`.
+
+
 ### Common Development Tasks
 
 #### Running Specific Tests

build_system/src/build.rs

@@ -46,8 +46,16 @@ impl BuildArg {
         println!(
             r#"
 `build` command help:
-
-    --sysroot              : Build with 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.
+                             It has no effect if `--sysroot` is not specified.
+                             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");

build_system/src/config.rs

@@ -459,14 +459,11 @@ 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]
+    --release              : Build backend in release mode with optimized dependencies
     --out-dir              : Location where the files will be generated
-    --release              : Build in release mode
-    --release-sysroot      : Build 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
     --cg_gcc-path          : Location of the rustc_codegen_gcc root folder (used

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<String>,
     nb_parts: Option<usize>,
     current_part: Option<usize>,
-    sysroot_panic_abort: bool,
     config_info: ConfigInfo,
     sysroot_features: Vec<String>,
     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;
                 }