document combination of flags

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

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");

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