diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 54cba0e6de3..d5acc741d31 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/build_system/src/build.rs b/build_system/src/build.rs index 94b40319f4a..b3bc1007529 100644 --- a/build_system/src/build.rs +++ b/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"); diff --git a/build_system/src/config.rs b/build_system/src/config.rs index a5f802e293a..37b0a77f621 100644 --- a/build_system/src/config.rs +++ b/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