Streamline "Getting Started" some more.

src/building/how-to-build-and-run.md

@@ -125,8 +125,8 @@ Options:
     -h, --help          print this help message
 ```
 
-For hacking, often building the stage 1 compiler is enough, but for
-final testing and release, the stage 2 compiler is used.
+For hacking, often building the stage 1 compiler is enough, which saves a lot
+of time. But for final testing and release, the stage 2 compiler is used.
 
 `./x.py check` is really fast to build the rust compiler.
 It is, in particular, very useful when you're doing some kind of
@@ -168,28 +168,24 @@ there is a (hacky) workaround.  See [the section on "recommended
 workflows"](./suggested.md) below.
 
 Note that this whole command just gives you a subset of the full `rustc`
-build. The **full** `rustc` build (what you get if you say `./x.py build
+build. The **full** `rustc` build (what you get with `./x.py build
 --stage 2 compiler/rustc`) has quite a few more steps:
 
 - Build `rustc` with the stage1 compiler.
   - The resulting compiler here is called the "stage2" compiler.
 - Build `std` with stage2 compiler.
 - Build `librustdoc` and a bunch of other things with the stage2 compiler.
 
-<a name=toolchain></a>
+You almost never need to do this.
 
 ## Build specific components
 
-- Build only the core library
+If you are working on the standard library, you probably don't need to build
+the compiler unless you are planning to use a recently added nightly feature.
+Instead, you can just build stage 0, which uses the current beta compiler.
 
 ```bash
-./x.py build --stage 0 library/core
-```
-
-- Build only the core and `proc_macro` libraries
-
-```bash
-./x.py build --stage 0 library/core library/proc_macro
+./x.py build --stage 0 library/std
 ```
 
 Sometimes you might just want to test if the part you’re working on can
@@ -245,7 +241,8 @@ in other sections:
 - Building things:
   - `./x.py build` – builds everything using the stage 1 compiler,
     not just up to `std`
-  - `./x.py build --stage 2` – builds the stage2 compiler
+  - `./x.py build --stage 2` – builds the stage2 compiler, along with `std` and
+    `rustdoc` (which doesn't take too long)
 - Running tests (see the [section on running tests](../tests/running.html) for
   more details):
   - `./x.py test library/std` – runs the `#[test]` tests from `std`

src/conventions.md

@@ -8,17 +8,25 @@ chapter covers [formatting](#formatting), [coding for correctness](#cc),
 # Formatting and the tidy script
 
 rustc is moving towards the [Rust standard coding style][fmt].
-This is enforced by the "tidy" script and can be mostly
-automated using `./x.py fmt`.
 
-As the output of [rustfmt] is not completely stable,
-formatting this repository using `cargo fmt` is not recommended.
+However, for now we don't use stable `rustfmt`; we use a pinned version with a
+special config, so this may result in different style from normal [`rustfmt`].
+Therefore, formatting this repository using `cargo fmt` is not recommended.
 
-The tidy script runs automatically when you do `./x.py test` and can be run
-in isolation with `./x.py test tidy`.
+Instead, formatting should be done using `./x.py fmt`. It's a good habit to run
+`./x.py fmt` before every commit, as this reduces conflicts later. 
+
+Formatting is checked by the "tidy" script. It runs automatically when you do
+`./x.py test` and can be run in isolation with `./x.py test tidy`. `./x.py fmt
+--check` also works.
+
+If you want to use format-on-save in your editor, the pinned version of
+`rustfmt` is built under `build/<target>/stage0/bin/rustfmt`. You'll have to
+pass the <!-- date: 2021-09 --> `--edition=2021` argument yourself when calling
+`rustfmt` directly.
 
 [fmt]: https://github.com/rust-dev-tools/fmt-rfcs
-[rustfmt]:https://github.com/rust-lang/rustfmt
+[`rustfmt`]:https://github.com/rust-lang/rustfmt
 
 <a name="copyright"></a>
 

src/getting-started.md

@@ -96,174 +96,28 @@ See [this chapter][config] for more info about configuration.
 
 [config]: ./building/how-to-build-and-run.md#create-a-configtoml
 
-### Building and Testing `rustc`
+### Common `x.py` commands
 
-Here is a summary of the different commands for reference, but you probably
-should still read the rest of the section:
+Here are the basic invocations of the `x.py` commands most commonly used when
+working on `rustc`, `std`, `rustdoc`, and other tools.
 
 | Command | When to use it |
 | --- | --- |
-| `./x.py check` | Quick check to see if things compile; [rust-analyzer can run this automatically for you][rust-analyzer] |
-| `./x.py build --stage 0 [library/std]` | Build only the standard library, without building the compiler |
-| `./x.py build library/std` | Build just the 1st stage of the compiler, along with the standard library; this is faster than building stage 2 and usually good enough |
-| `./x.py build --keep-stage 1 library/std` | Build the 1st stage of the compiler and skips rebuilding the standard library; this is useful after you've done an ordinary stage1 build to skip compilation time, but it can cause weird problems. (Just do a regular build to resolve.) |
-| `./x.py test [--keep-stage 1]` | Run the test suite using the stage1 compiler |
-| `./x.py test --bless [--keep-stage 1]` | Run the test suite using the stage1 compiler _and_ update expected test output. |
-| `./x.py build --stage 2 compiler/rustc` | Do a full 2-stage build. You almost never want to do this. |
-| `./x.py test --stage 2` | Do a full 2-stage build and run all tests. You almost never want to do this. |
-
-To do a full 2-stage build of the whole compiler, you should run this (after
-updating `config.toml` as mentioned above):
+| `./x.py check` | Quick check to see if most things compile; [rust-analyzer can run this automatically for you][rust-analyzer] |
+| `./x.py build` | Builds `rustc`, `std`, and `rustdoc` |
+| `./x.py test` | Runs all tests |
+| `./x.py fmt` | Formats all code |
 
-```sh
-./x.py build --stage 2 compiler/rustc
-```
-
-In the process, this will also necessarily build the standard libraries, and it
-will build `rustdoc` (which doesn't take too long).
-
-To build and test everything:
-
-```sh
-./x.py test
-```
-
-For most contributions, you only need to build stage 1, which saves a lot of time:
-
-```sh
-# Build the compiler (stage 1)
-./x.py build library/std
-
-# Subsequent builds
-./x.py build --keep-stage 1 library/std
-```
-
-This will take a while, especially the first time. Be wary of accidentally
-touching or formatting the compiler, as `x.py` will try to recompile it.
-
-**NOTE**: The `--keep-stage 1` will _assume_ that the stage 0 standard library
-does not need to be rebuilt, which is usually true, which will save some time.
-However, if you are changing certain parts of the compiler, this may lead to
-weird errors. Feel free to ask on [zulip][z] if you are running into issues.
-
-This runs a ton of tests and takes a long time to complete. If you are
-working on `rustc`, you can usually get by with only the [UI tests][uitests]. These
-test are mostly for the frontend of the compiler, so if you are working on LLVM
-or codegen, this shortcut will _not_ test your changes. You can read more about the
-different test suites [in this chapter][testing].
+As written, these commands are reasonable starting points. However, there are
+additional options and arguments for each of them that are worth learning for
+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.
 
 [rust-analyzer]: ./building/suggested.html#configuring-rust-analyzer-for-rustc
-[uitests]: ./tests/adding.html#ui
-[testing]: https://rustc-dev-guide.rust-lang.org/tests/intro.html
-
-```sh
-# First build
-./x.py test src/test/ui
-
-# Subsequent builds
-./x.py test src/test/ui --keep-stage 1
-```
-
-If your changes impact test output, you can use `--bless` to automatically
-update the `.stderr` files of the affected tests:
-
-```sh
-./x.py test src/test/ui --keep-stage 1 --bless
-```
-
-While working on the compiler, it can be helpful to see if the code just
-compiles (similar to `cargo check`) without actually building it. You can do
-this with:
-
-```sh
-./x.py check
-```
-
-This command is really fast (relative to the other commands). It usually
-completes in a couple of minutes on my laptop. **A common workflow when working
-on the compiler is to make changes and repeatedly check with `./x.py check`.
-Then, run the tests as shown above when you think things should work.**
-
-Finally, the CI ensures that the codebase is using consistent style. To format
-the code:
-
-```sh
-# Actually format
-./x.py fmt
 
-# Just check formatting, exit with error
-./x.py fmt --check
-```
-
-*Note*: we don't use stable `rustfmt`; we use a pinned version with a special
-config, so this may result in different style from normal `rustfmt` if you have
-format-on-save turned on. It's a good habit to run `./x.py fmt` before every
-commit, as this reduces conflicts later. The pinned version is built under
-`build/<target>/stage0/bin/rustfmt`, so if you want, you can use it for a
-single file or for format-on-save in your editor, which can be faster than `./x.py fmt`.
-You'll have to pass the <!-- date: 2021-09 --> `--edition=2021` argument
-yourself when calling `rustfmt` directly.
-
-One last thing: you can use `RUSTC_LOG=XXX` to get debug logging. [Read more
-here][logging]. Notice the `C` in `RUSTC_LOG`. Other than that, it uses normal
-[`env_logger`][envlog]  or `tracing` syntax.
-
-[envlog]: https://crates.io/crates/env_logger
-[logging]: ./tracing.md
-
-### Building and Testing `std`/`core`/`alloc`/`test`/`proc_macro`/etc.
-
-As before, technically the proper way to build one of these libraries is to use
-the stage-2 compiler, which of course requires a 2-stage build, described above
-(`./x.py build`).
-
-In practice, though, you don't need to build the compiler unless you are
-planning to use a recently added nightly feature. Instead, you can just build
-stage 0, which uses the current beta compiler.
-
-```sh
-./x.py build --stage 0
-```
-
-```sh
-./x.py test --stage 0 library/std
-```
-
-(The same works for `library/alloc`, `library/core`, etc.)
-
-### Building and Testing `rustdoc`
-
-`rustdoc` uses `rustc` internals (and, of course, the standard library), so you
-will have to build the compiler and `std` once before you can build `rustdoc`.
-As before, you can use `./x.py build` to do this. The first time you build,
-the stage-1 compiler will also be built.
-
-```sh
-# First build
-./x.py build
-
-# Subsequent builds
-./x.py build --keep-stage 1
-```
-
-As with the compiler, you can do a fast check build:
-
-```sh
-./x.py check
-```
-
-Rustdoc has two types of tests: content tests and UI tests.
-
-```sh
-# Content tests
-./x.py test src/test/rustdoc
-
-# UI tests
-./x.py test src/test/rustdoc-ui
-
-# Both at once
-./x.py test src/test/rustdoc src/test/rustdoc-ui
-```
+See the chapters on [building](./building/how-to-build-and-run.md) and
+[testing](./tests/intro.md) for more details.
 
 ### Contributing code to other Rust projects
 

src/rustdoc.md

@@ -1,6 +1,9 @@
 # Rustdoc overview
 
-Rustdoc actually uses the rustc internals directly. It lives in-tree with the
+`rustdoc` uses `rustc` internals (and, of course, the standard library), so you
+will have to build the compiler and `std` once before you can build `rustdoc`.
+
+`rustdoc` lives in-tree with the
 compiler and standard library. This chapter is about how it works.
 For information about Rustdoc's features and how to use them, see
 the [Rustdoc book](https://doc.rust-lang.org/nightly/rustdoc/).
@@ -39,9 +42,11 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
 * Run `./x.py setup tools` before getting started. This will configure `x.py`
   with nice settings for developing rustdoc and other tools, including
   downloading a copy of rustc rather than building it.
+* Use `./x.py check` to quickly check for compile errors.
 * Use `./x.py build` to make a usable
   rustdoc you can run on other projects.
   * Add `library/test` to be able to use `rustdoc --test`.
+  * Add `--keep-stage 1` on subsequent runs to avoid rebuilding some things.
   * Run `rustup toolchain link stage2 build/$TARGET/stage2` to add a
     custom toolchain called `stage2` to your rustup environment. After
     running that, `cargo +stage2 doc` in any directory will build with
@@ -52,7 +57,8 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
   * If you want to copy those docs to a webserver, copy all of
     `build/$TARGET/doc`, since that's where the CSS, JS, fonts, and landing
     page are.
-* Use `./x.py test src/test/rustdoc*` to run the tests using a stage1 rustdoc.
+* Use `./x.py test src/test/rustdoc*` to run the tests using a stage1
+  rustdoc.
   * See [Rustdoc internals] for more information about tests.
 
 ## Code structure

src/tests/running.md

@@ -36,7 +36,11 @@ modifying rustc to see if things are generally working correctly would be the
 following:
 
 ```bash
+# First build
 ./x.py test src/test/ui
+
+# Subsequent builds (optional, but can save time)
+./x.py test src/test/ui --keep-stage 1
 ```
 
 This will run the `ui` test suite. Of course, the choice
@@ -92,6 +96,13 @@ tests for components you did not change at all.
 build; therefore, while the tests **usually** work fine with stage 1,
 there are some limitations.
 
+### Run all tests using a stage 2 compiler
+
+```bash
+./x.py test --stage 2
+```
+You almost never need to do this.
+
 ## Run unit tests on the compiler/library
 
 You may want to run unit tests on a specific file with following: