Rewrite the section on passing flags to subcommands

- Move the reference for directories and actions to the very end; it's the most rare to need to know
- Add `RUSTDOCFLAGS*`, `CARGOFLAGS*`, `-vvv`, and `--test-args`
- Remove the incorrect `--on-fail` command

Author: jyn514

src/building/bootstrapping.md

@@ -370,9 +370,46 @@ You can find more discussion about sysroots in:
 
 [rustdoc PR]: https://github.com/rust-lang/rust/pull/76728
 
-### Directories and artifacts generated by `x.py`
+## Passing flags to commands invoked by `bootstrap`
 
-The following tables indicate the outputs of various stage actions:
+`x.py` allows you to pass stage-specific flags to `rustc` and `cargo` when bootstrapping.
+The `RUSTFLAGS_BOOTSTRAP` environment variable is passed as RUSTFLAGS to the bootstrap stage
+(stage0), and `RUSTFLAGS_NOT_BOOTSTRAP` is passed when building artifacts for later stages.
+`RUSTFLAGS` will work, but also affects the build of `bootstrap` itself, so it will be rare to want
+to use it.
+Finally, `MAGIC_EXTRA_RUSTFLAGS` bypasses the `cargo` cache to pass flags to rustc without
+recompiling all dependencies.
+
+`RUSTDOCFLAGS`, `RUSTDOCFLAGS_BOOTSTRAP`, and `RUSTDOCFLAGS_NOT_BOOTSTRAP` are anologous to
+`RUSTFLAGS`, but for rustdoc.
+
+`CARGOFLAGS` will pass arguments to cargo itself (e.g. `--timings`). `CARGOFLAGS_BOOTSTRAP` and
+`CARGOFLAGS_NOT_BOOTSTRAP` work anologously to `RUSTFLAGS_BOOTSTRAP`.
+
+`--test-args` will pass arguments through to the test runner. For `src/test/ui`, this is
+compiletest; for unit tests and doctests this is the `libtest` runner. Most test runner accept
+`--help`, which you can use to find out the options accepted by the runner.
+
+## Environment Variables
+
+During bootstrapping, there are a bunch of compiler-internal environment
+variables that are used. If you are trying to run an intermediate version of
+`rustc`, sometimes you may need to set some of these environment variables
+manually. Otherwise, you get an error like the following:
+
+```text
+thread 'main' panicked at 'RUSTC_STAGE was not set: NotPresent', library/core/src/result.rs:1165:5
+```
+
+If `./stageN/bin/rustc` gives an error about environment variables, that
+usually means something is quite wrong -- or you're trying to compile e.g.
+`rustc` or `std` or something that depends on environment variables. In
+the unlikely case that you actually need to invoke rustc in such a situation,
+you can tell the bootstrap shim to print all env variables by adding `-vvv` to your `x.py` command.
+
+### Directories and artifacts generated by `bootstrap`
+
+This is an incomplete reference for the outputs generated by bootstrap:
 
 | Stage 0 Action                                            | Output                                       |
 |-----------------------------------------------------------|----------------------------------------------|
@@ -411,27 +448,3 @@ The following tables indicate the outputs of various stage actions:
 | copy `rustdoc`                                         | `build/HOST/stage2/bin`                                         |
 
 `--stage=2` stops here.
-
-## Passing stage-specific flags to `rustc`
-
-`x.py` allows you to pass stage-specific flags to `rustc` when bootstrapping.
-The `RUSTFLAGS_BOOTSTRAP` environment variable is passed as RUSTFLAGS to the bootstrap stage
-(stage0), and `RUSTFLAGS_NOT_BOOTSTRAP` is passed when building artifacts for later stages.
-
-## Environment Variables
-
-During bootstrapping, there are a bunch of compiler-internal environment
-variables that are used. If you are trying to run an intermediate version of
-`rustc`, sometimes you may need to set some of these environment variables
-manually. Otherwise, you get an error like the following:
-
-```text
-thread 'main' panicked at 'RUSTC_STAGE was not set: NotPresent', library/core/src/result.rs:1165:5
-```
-
-If `./stageN/bin/rustc` gives an error about environment variables, that
-usually means something is quite wrong -- or you're trying to compile e.g.
-`rustc` or `std` or something that depends on environment variables. In
-the unlikely case that you actually need to invoke rustc in such a situation,
-you can find the environment variable values by adding the following flag to
-your `x.py` command: `--on-fail=print-env`.