extend bootstrap related documentations

Signed-off-by: ozkanonur <[email protected]>

Author: onur-ozkan

src/building/bootstrapping.md

@@ -411,17 +411,17 @@ you can tell the bootstrap shim to print all env variables by adding `-vvv` to y
 
 This is an incomplete reference for the outputs generated by bootstrap:
 
-| Stage 0 Action                                            | Output                                       |
-|-----------------------------------------------------------|----------------------------------------------|
-| `beta` extracted                                          | `build/HOST/stage0`                          |
-| `stage0` builds `bootstrap`                               | `build/bootstrap`                            |
-| `stage0` builds `test`/`std`                              | `build/HOST/stage0-std/TARGET`               |
-| copy `stage0-std` (HOST only)                             | `build/HOST/stage0-sysroot/lib/rustlib/HOST` |
-| `stage0` builds `rustc` with `stage0-sysroot`             | `build/HOST/stage0-rustc/HOST`               |
-| copy `stage0-rustc` (except executable)                   | `build/HOST/stage0-sysroot/lib/rustlib/HOST` |
-| build `llvm`                                              | `build/HOST/llvm`                            |
-| `stage0` builds `codegen` with `stage0-sysroot`           | `build/HOST/stage0-codegen/HOST`             |
-| `stage0` builds `rustdoc`, `clippy`, `miri`, with `stage0-sysroot` | `build/HOST/stage0-tools/HOST`      |
+| Stage 0 Action                                                     | Output                                       |
+| ------------------------------------------------------------------ | -------------------------------------------- |
+| `beta` extracted                                                   | `build/HOST/stage0`                          |
+| `stage0` builds `bootstrap`                                        | `build/bootstrap`                            |
+| `stage0` builds `test`/`std`                                       | `build/HOST/stage0-std/TARGET`               |
+| copy `stage0-std` (HOST only)                                      | `build/HOST/stage0-sysroot/lib/rustlib/HOST` |
+| `stage0` builds `rustc` with `stage0-sysroot`                      | `build/HOST/stage0-rustc/HOST`               |
+| copy `stage0-rustc` (except executable)                            | `build/HOST/stage0-sysroot/lib/rustlib/HOST` |
+| build `llvm`                                                       | `build/HOST/llvm`                            |
+| `stage0` builds `codegen` with `stage0-sysroot`                    | `build/HOST/stage0-codegen/HOST`             |
+| `stage0` builds `rustdoc`, `clippy`, `miri`, with `stage0-sysroot` | `build/HOST/stage0-tools/HOST`               |
 
 `--stage=0` stops here.
 
@@ -448,3 +448,45 @@ This is an incomplete reference for the outputs generated by bootstrap:
 | copy `rustdoc`                                         | `build/HOST/stage2/bin`                                         |
 
 `--stage=2` stops here.
+
+### Clarification of build command's stdout
+
+In this part, we will investigate the build command's stdout in an action
+(similar, but more detailed and complete documentation compare to topic above).
+When you execute `x.py build --dry-run` command, the build output will be something
+like the following:
+
+```text
+Building stage0 library artifacts (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
+Copying stage0 library from stage0 (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu / x86_64-unknown-linux-gnu)
+Building stage0 compiler artifacts (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
+Copying stage0 rustc from stage0 (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu / x86_64-unknown-linux-gnu)
+Assembling stage1 compiler (x86_64-unknown-linux-gnu)
+Building stage1 library artifacts (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
+Copying stage1 library from stage1 (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu / x86_64-unknown-linux-gnu)
+Building stage1 tool rust-analyzer-proc-macro-srv (x86_64-unknown-linux-gnu)
+Building rustdoc for stage1 (x86_64-unknown-linux-gnu)
+```
+
+#### Building stage0 {std,compiler} artifacts
+
+These steps use the provided (downloaded, usually) compiler to compile the
+local Rust source into libraries we can use.
+
+#### Copying stage0 {std,rustc}
+
+This copies the library and compiler artifacts from Cargo into
+`stage0-sysroot/lib/rustlib/{target-triple}/lib`
+
+#### Assembling stage1 compiler
+
+This copies the libraries we built in "building stage0 ... artifacts" into
+the stage1 compiler's lib directory. These are the host libraries that the
+compiler itself uses to run. These aren't actually used by artifacts the new
+compiler generates. This step also copies the rustc and rustdoc binaries we
+generated into `build/$HOST/stage/bin`.
+
+The stage1/bin/rustc is a fully functional compiler, but it doesn't yet have
+any libraries to link built binaries or libraries to. The next 3 steps will
+provide those libraries for it; they are mostly equivalent to constructing
+the stage1/bin compiler so we don't go through them individually.

src/building/suggested.md

@@ -175,6 +175,27 @@ You can also use `--keep-stage 1` when running tests. Something like this:
 - Initial test run: `./x.py test tests/ui`
 - Subsequent test run: `./x.py test tests/ui --keep-stage 1`
 
+## Using incremental compilation
+
+You can further enable the `--incremental` flag to save additional
+time in subsequent rebuilds:
+
+```bash
+./x.py test tests/ui --incremental --test-args issue-1234
+```
+
+If you don't want to include the flag with every command, you can
+enable it in the `config.toml`:
+
+```toml
+[rust]
+incremental = true
+```
+
+Note that incremental compilation will use more disk space than usual.
+If disk space is a concern for you, you might want to check the size
+of the `build` directory from time to time.
+
 ## Fine-tuning optimizations
 
 Setting `optimize = false` makes the compiler too slow for tests. However, to

src/getting-started.md

@@ -114,6 +114,10 @@ serious development work. In particular, `./x.py build` and `./x.py test`
 provide many ways to compile or test a subset of the code, which can save a lot
 of time.
 
+Also, note that `x.py` supports all kinds of path suffixes for `compiler`, `library`,
+and `src/tools` directories. So, you can simply run `x.py test tidy` instead of
+`x.py test src/tools/tidy`. Or, `x.py build std` instead of `x.py build library/std`.
+
 [rust-analyzer]: ./building/suggested.html#configuring-rust-analyzer-for-rustc
 
 See the chapters on [building](./building/how-to-build-and-run.md),

src/tests/compiletest.md

@@ -24,6 +24,11 @@ See the [Adding new tests](adding.md) chapter for a tutorial on creating a new
 test, and the [Running tests](running.md) chapter on how to run the test
 suite.
 
+Compiletest itself tries to avoid running tests when the artifacts
+that are involved (mainly the compiler) haven't changed. You can use
+`x test --test-args --force-rerun` to rerun a test even when none of the
+inputs have changed.
+
 ## Test suites
 
 All of the tests are in the [`tests`] directory.

src/tests/running.md

@@ -175,27 +175,6 @@ By passing `--pass $mode`, you can reduce the testing time. For each
 mode, please see [Controlling pass/fail
 expectations](ui.md#controlling-passfail-expectations).
 
-## Using incremental compilation
-
-You can further enable the `--incremental` flag to save additional
-time in subsequent rebuilds:
-
-```bash
-./x.py test tests/ui --incremental --test-args issue-1234
-```
-
-If you don't want to include the flag with every command, you can
-enable it in the `config.toml`:
-
-```toml
-[rust]
-incremental = true
-```
-
-Note that incremental compilation will use more disk space than usual.
-If disk space is a concern for you, you might want to check the size
-of the `build` directory from time to time.
-
 ## Running tests with different "compare modes"
 
 UI tests may have different output depending on certain "modes" that