document combination of flags

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 (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
 
 #### Running Specific Tests

build_system/src/build.rs

@@ -45,8 +45,16 @@ impl BuildArg {
         println!(
             r#"
 `build` command help:
-
-    --sysroot              : Build with sysroot"#
+    --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 its own."#
         );
         ConfigInfo::show_usage();
         println!("    --help                 : Show this help");

build_system/src/config.rs

@@ -472,13 +472,10 @@ 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
-    --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