Update the build instructions for the standard library

Since rust-lang/rust#95503, `library/std` means
"build just std and its dependencies"; to get the old behavior that built
`proc_macro` and `test`, you need `x build library`.

- Update `library/std` to `library`
- Remove the `-i` suggestions; `incremental = true` is already the default for most profiles, in
  which case `-i` does nothing. If you don't have incremental enabled, I still think suggesting `-i`
  is bad idea, because it's easy to forget once, at which point you'll end up rebuilding the whole
  compiler / standard library.
- Remove a few repetitive sections and don't discuss incremental in such detail
  Incremental works well enough that it should "just work" for most people;
  I don't think it needs multiple paragraphs of explanation so early in the guide.
- Clarify that `test library/std` *only* tests libstd in a few places

Author: jyn514

Diff for: src/building/bootstrapping.md

@@ -55,7 +55,7 @@ However, it takes a very long time to build
 because one must first build the new compiler with an older compiler
 and then use that to build the new compiler with itself.
 For development, you usually only want the `stage1` compiler,
-which you can build with `./x.py build library/std`.
+which you can build with `./x.py build library`.
 See [Building the Compiler](./how-to-build-and-run.html#building-the-compiler).
 
 ### Stage 3
@@ -169,15 +169,15 @@ Build artifacts include, but are not limited to:
 
 #### Examples of what *not* to do
 
-- `./x.py test --stage 0 src/test/ui` is not meaningful: it runs tests on the
+- `./x.py test --stage 0 src/test/ui` is not useful: it runs tests on the
   _beta_ compiler and doesn't build `rustc` from source. Use `test src/test/ui`
   instead, which builds stage 1 from source.
 - `./x.py test --stage 0 compiler/rustc` builds the compiler but runs no tests:
   it's running `cargo test -p rustc`, but cargo doesn't understand Rust's
   tests. You shouldn't need to use this, use `test` instead (without arguments).
 - `./x.py build --stage 0 compiler/rustc` builds the compiler, but does not build
   libstd or even libcore. Most of the time, you'll want `./x.py build
-  library/std` instead, which allows compiling programs without needing to define
+  library` instead, which allows compiling programs without needing to define
   lang items.
 
 ### Building vs. running

Diff for: src/building/compiler-documenting.md

@@ -30,7 +30,7 @@ and then it documents the files.
 ```bash
 ./x.py doc src/doc/book
 ./x.py doc src/doc/nomicon
-./x.py doc src/doc/book library/std
+./x.py doc src/doc/book library
 ```
 
 Much like individual tests or building certain components you can build only

Diff for: src/building/how-to-build-and-run.md

@@ -138,34 +138,23 @@ Once you've created a `config.toml`, you are now ready to run
 probably the best "go to" command for building a local rust:
 
 ```bash
-./x.py build -i library/std
+./x.py build library
 ```
 
-This may *look* like it only builds `std`, but that is not the case.
+This may *look* like it only builds the standard library, but that is not the case.
 What this command does is the following:
 
-- Build `std` using the stage0 compiler (using incremental)
-- Build `rustc` using the stage0 compiler (using incremental)
+- Build `std` using the stage0 compiler
+- Build `rustc` using the stage0 compiler
   - This produces the stage1 compiler
-- Build `std` using the stage1 compiler (cannot use incremental)
+- Build `std` using the stage1 compiler
 
 This final product (stage1 compiler + libs built using that compiler)
 is what you need to build other Rust programs (unless you use `#![no_std]` or
 `#![no_core]`).
 
-The command includes the `-i` switch which enables incremental compilation.
-This will be used to speed up the first two steps of the process:
-in particular, if you make a small change, we ought to be able to use your old
-results to make producing the stage1 **compiler** faster.
-
-Unfortunately, incremental cannot be used to speed up making the
-stage1 libraries.  This is because incremental only works when you run
-the *same compiler* twice in a row.  In this case, we are building a
-*new stage1 compiler* every time. Therefore, the old incremental
-results may not apply. **As a result, you will probably find that
-building the stage1 `std` is a bottleneck for you** -- but fear not,
-there is a (hacky) workaround.  See [the section on "recommended
-workflows"](./suggested.md) below.
+You will probably find that building the stage1 `std` is a bottleneck for you** -- but fear not,
+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 with `./x.py build
@@ -185,14 +174,9 @@ the compiler unless you are planning to use a recently added nightly feature.
 Instead, you can just build using the bootstrap compiler.
 
 ```bash
-./x.py build --stage 0 library/std
+./x.py build --stage 0 library
 ```
 
-Sometimes you might just want to test if the part you’re working on can
-compile. Using these commands you can test that it compiles before doing
-a bigger build to make sure it works with the compiler. As shown before
-you can also pass flags at the end such as `--stage`.
-
 ## Creating a rustup toolchain
 
 Once you have successfully built `rustc`, you will have created a bunch
@@ -251,7 +235,7 @@ in other sections:
     `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`
+  - `./x.py test library/std` – runs the unit tests and integration tests from `std`
   - `./x.py test src/test/ui` – runs the `ui` test suite
   - `./x.py test src/test/ui/const-generics` - runs all the tests in
   the `const-generics/` subdirectory of the `ui` test suite

Diff for: src/building/suggested.md

@@ -144,13 +144,13 @@ don't work (but that is easily detected and fixed).
 
 The sequence of commands you want is as follows:
 
-- Initial build: `./x.py build -i library/std`
+- Initial build: `./x.py build library`
   - As [documented previously], this will build a functional
     stage1 compiler as part of running all stage0 commands (which include
     building a `std` compatible with the stage1 compiler) as well as the
     first few steps of the "stage 1 actions" up to "stage1 (sysroot stage1)
     builds std".
-- Subsequent builds: `./x.py build -i library/std --keep-stage 1`
+- Subsequent builds: `./x.py build library --keep-stage 1`
   - Note that we added the `--keep-stage 1` flag here
 
 [documented previously]: ./how-to-build-and-run.md#building-the-compiler
@@ -172,8 +172,8 @@ rebuild. That ought to fix the problem.
 
 You can also use `--keep-stage 1` when running tests. Something like this:
 
-- Initial test run: `./x.py test -i src/test/ui`
-- Subsequent test run: `./x.py test -i src/test/ui --keep-stage 1`
+- Initial test run: `./x.py test src/test/ui`
+- Subsequent test run: `./x.py test src/test/ui --keep-stage 1`
 
 ## Fine-tuning optimizations
 

Diff for: src/contributing.md

@@ -408,7 +408,7 @@ You can find documentation style guidelines in [RFC 1574][rfc1574].
 In many cases, you don't need a full `./x.py doc --stage 2`, which will build
 the entire stage 2 compiler and compile the various books published on
 [doc.rust-lang.org][docs]. When updating documentation for the standard library,
-first try `./x.py doc library/std`. If that fails, or if you need to
+first try `./x.py doc library`. If that fails, or if you need to
 see the output from the latest version of `rustdoc`, add `--stage 1`.
 Results should appear in `build/$TARGET/doc`.
 

Diff for: src/profiling/wpa_profiling.md

@@ -47,11 +47,11 @@ we'll need to build a stage 1 compiler and then a stage 2 compiler ourselves.
 To do this, make sure you have set `debuginfo-level = 1` in your `config.toml` file. This tells
 rustc to generate debug information which includes stack frames when bootstrapping.
 
-Now you can build the stage 1 compiler: `python x.py build --stage 1 -i library/std` or however
+Now you can build the stage 1 compiler: `python x.py build --stage 1 -i library` or however
 else you want to build the stage 1 compiler.
 
 Now that the stage 1 compiler is built, we can record the stage 2 build. Go back to WPR, click the
-"start" button and build the stage 2 compiler (e.g., `python x build --stage=2 -i library/std `).
+"start" button and build the stage 2 compiler (e.g., `python x build --stage=2 -i library`).
 When this process finishes, stop the recording.
 
 Click the Save button and once that process is complete, click the "Open in WPA" button which

Diff for: src/rustdoc-internals.md

@@ -224,7 +224,7 @@ server. To test these features locally, you can run a local HTTP server, like
 this:
 
 ```bash
-$ ./x.py doc library/std
+$ ./x.py doc library
 # The documentation has been generated into `build/[YOUR ARCH]/doc`.
 $ python3 -m http.server -d build/[YOUR ARCH]/doc
 ```

Diff for: src/rustdoc.md

@@ -50,9 +50,9 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
     custom toolchain called `stage2` to your rustup environment. After
     running that, `cargo +stage2 doc` in any directory will build with
     your locally-compiled rustdoc.
-* Use `./x.py doc library/std` to use this rustdoc to generate the
+* Use `./x.py doc library` to use this rustdoc to generate the
   standard library docs.
-  * The completed docs will be available in `build/$TARGET/doc/std`.
+  * The completed docs will be available in `build/$TARGET/doc` (under `core`, `alloc`, and `std`).
   * 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.

Diff for: src/tests/intro.md

@@ -35,8 +35,8 @@ Examples:
 
 | Command | Description |
 |---------|-------------|
-| `./x.py test library/std` | Runs tests on `std` |
-| `./x.py test library/core` | Runs tests on `core` |
+| `./x.py test library/std` | Runs tests on `std` only |
+| `./x.py test library/core` | Runs tests on `core` only |
 | `./x.py test compiler/rustc_data_structures` | Runs tests on `rustc_data_structures` |
 
 The standard library relies very heavily on documentation tests to cover its functionality.

Diff for: src/tests/running.md

@@ -74,6 +74,9 @@ Likewise, you can test a single file by passing its path:
 ./x.py test --stage 0 library/std
 ```
 
+Note that this only runs tests on `std`; if you want to test `core` or other crates,
+you have to specify those explicitly.
+
 ### Run the tidy script and tests on the standard library
 
 ```bash
@@ -83,7 +86,7 @@ Likewise, you can test a single file by passing its path:
 ### Run tests on the standard library using a stage 1 compiler
 
 ```bash
-./x.py test library/std
+./x.py test --stage 1 library/std
 ```
 
 By listing which test suites you want to run you avoid having to run
@@ -98,7 +101,7 @@ there are some limitations.
 ```bash
 ./x.py test --stage 2
 ```
-You almost never need to do this.
+You almost never need to do this; CI will run these tests for you.
 
 ## Run unit tests on the compiler/library