Update docs to match the new x.py defaults (#813)

9 files changed, 66 insertions, 86 deletions

diff --git a/src/doc/rustc-dev-guide/README.md b/src/doc/rustc-dev-guide/README.md
index 8f7db233ef4..345b385892e 100644
--- a/src/doc/rustc-dev-guide/README.md
+++ b/src/doc/rustc-dev-guide/README.md
@@ -132,7 +132,7 @@ git submodule update --remote src/doc/rustc-dev-guide
 git add -u
 git commit -m "Update rustc-dev-guide"
 # Note that you can use -i, which is short for --incremental, in the following command
-./x.py test --incremental --stage 1 src/doc/rustc-dev-guide # This is optional and should succeed anyway
+./x.py test --incremental src/doc/rustc-dev-guide # This is optional and should succeed anyway
 # Open a PR in rust-lang/rust
 ```
 
diff --git a/src/doc/rustc-dev-guide/src/building/compiler-documenting.md b/src/doc/rustc-dev-guide/src/building/compiler-documenting.md
index 68c9fd2279f..111f6858d9f 100644
--- a/src/doc/rustc-dev-guide/src/building/compiler-documenting.md
+++ b/src/doc/rustc-dev-guide/src/building/compiler-documenting.md
@@ -9,11 +9,14 @@ since documentation is more about the content.
 
 ## Document everything
 
+This uses the beta rustdoc, which usually but not always has the same output
+as stage 1 rustdoc.
+
 ```bash
 ./x.py doc
 ```
 
-## If you want to avoid the whole Stage 2 build
+## If you want to be sure that the links behave the same as on CI
 
 ```bash
 ./x.py doc --stage 1
diff --git a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md b/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md
index 155c8497266..f4d783f5daf 100644
--- a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md
+++ b/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md
@@ -62,19 +62,6 @@ debug = true
 # compiler.
 codegen-units = 0
 
-# Debuginfo level for most of Rust code, corresponds to the `-C debuginfo=N` option of `rustc`.
-# `0` - no debug info
-# `1` - line tables only - sufficient to generate backtraces that include line
-#       information and inlined functions, set breakpoints at source code
-#       locations, and step through execution in a debugger.
-# `2` - full debug info with variable and type information
-# Can be overridden for specific subsets of Rust code (rustc, std or tools).
-# Debuginfo for tests run with compiletest is not controlled by this option
-# and needs to be enabled separately with `debuginfo-level-tests`.
-#
-# Defaults to 2 if debug is true
-debuginfo-level = 1
-
 # Whether to always use incremental compilation when building rustc
 incremental = true
 
@@ -147,10 +134,9 @@ To read more about the bootstrap process, [read this chapter][bootstrap].
 
 ## Building the Compiler
 
-To build a compiler, run `./x.py build`. This will do the whole bootstrapping
-process described above, producing a usable compiler toolchain from the source
-code you have checked out. This takes a long time, so it is not usually what
-you want to actually run (more on this later).
+To build a compiler, run `./x.py build`. This will build up to the stage1 compiler,
+including `rustdoc`, producing a usable compiler toolchain from the source
+code you have checked out.
 
 Note that building will require a relatively large amount of storage space.
 You may want to have upwards of 10 or 15 gigabytes available to build the compiler.
@@ -190,7 +176,7 @@ 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 --stage 1 src/libstd
+./x.py build -i src/libstd
 ```
 
 This may *look* like it only builds `libstd`, but that is not the case.
@@ -220,8 +206,8 @@ 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 just say `./x.py
-build`) has quite a few more steps:
+build. The **full** `rustc` build (what you get if you say `./x.py build
+--stage 2 src/rustc`) has quite a few more steps:
 
 - Build `librustc` and `rustc` with the stage1 compiler.
   - The resulting compiler here is called the "stage2" compiler.
@@ -244,12 +230,6 @@ Build the libcore and libproc_macro library only
 ./x.py build src/libcore src/libproc_macro
 ```
 
-Build only libcore up to Stage 1
-
-```bash
-./x.py build src/libcore --stage 1
-```
-
 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
@@ -296,16 +276,16 @@ Here are a few other useful `x.py` commands. We'll cover some of them in detail
 in other sections:
 
 - Building things:
-  - `./x.py build --stage 1` – builds everything using the stage 1 compiler,
+  - `./x.py build` – builds everything using the stage 1 compiler,
     not just up to `libstd`
-  - `./x.py build` – builds the stage2 compiler
+  - `./x.py build --stage 2` – builds the stage2 compiler
 - Running tests (see the [section on running tests](../tests/running.html) for
   more details):
-  - `./x.py test --stage 1 src/libstd` – runs the `#[test]` tests from `libstd`
-  - `./x.py test --stage 1 src/test/ui` – runs the `ui` test suite
-  - `./x.py test --stage 1 src/test/ui/const-generics` - runs all the tests in
+  - `./x.py test src/libstd` – runs the `#[test]` tests from `libstd`
+  - `./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
-  - `./x.py test --stage 1 src/test/ui/const-generics/const-types.rs` - runs
+  - `./x.py test src/test/ui/const-generics/const-types.rs` - runs
   the single test `const-types.rs` from the `ui` test suite
 
 ### Cleaning out build directories
diff --git a/src/doc/rustc-dev-guide/src/building/suggested.md b/src/doc/rustc-dev-guide/src/building/suggested.md
index 102586721d0..fd2c00baa41 100644
--- a/src/doc/rustc-dev-guide/src/building/suggested.md
+++ b/src/doc/rustc-dev-guide/src/building/suggested.md
@@ -58,13 +58,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 --stage 1 src/libstd`
+- Initial build: `./x.py build -i src/libstd`
   - As [documented above](#command), this will build a functional
     stage1 compiler as part of running all stage0 commands (which include
     building a `libstd` compatible with the stage1 compiler) as well as the
     first few steps of the "stage 1 actions" up to "stage1 (sysroot stage1)
     builds libstd".
-- Subsequent builds: `./x.py build -i --stage 1 src/libstd --keep-stage 1`
+- Subsequent builds: `./x.py build -i src/libstd --keep-stage 1`
   - Note that we added the `--keep-stage 1` flag here
 
 As mentioned, the effect of `--keep-stage 1` is that we just *assume* that the
@@ -84,8 +84,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 --stage 1 src/test/ui`
-- Subsequent test run: `./x.py test -i --stage 1 src/test/ui --keep-stage 1`
+- Initial test run: `./x.py test -i src/test/ui`
+- Subsequent test run: `./x.py test -i src/test/ui --keep-stage 1`
 
 ## Fine-tuning optimizations
 
diff --git a/src/doc/rustc-dev-guide/src/contributing.md b/src/doc/rustc-dev-guide/src/contributing.md
index ec94a3f9c63..180197ddc2f 100644
--- a/src/doc/rustc-dev-guide/src/contributing.md
+++ b/src/doc/rustc-dev-guide/src/contributing.md
@@ -361,12 +361,12 @@ You can find documentation style guidelines in [RFC 1574][rfc1574].
 
 [rfc1574]: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text
 
-In many cases, you don't need a full `./x.py doc`, which will build the entire
-stage 2 compiler and compile the various books published on
+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 --stage 0 src/libstd`. If that fails, or if you need to
-see the output from the latest version of `rustdoc`, use `--stage 1` instead of
-`--stage 0`. Results should appear in `build/$TARGET/crate-docs`.
+first try `./x.py doc src/libstd`. 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/crate-docs`.
 
 [docs]: https://doc.rust-lang.org
 
diff --git a/src/doc/rustc-dev-guide/src/getting-started.md b/src/doc/rustc-dev-guide/src/getting-started.md
index a2994a4bee3..9d5db4b05d3 100644
--- a/src/doc/rustc-dev-guide/src/getting-started.md
+++ b/src/doc/rustc-dev-guide/src/getting-started.md
@@ -175,19 +175,19 @@ should still read the rest of the section:
 | Command | When to use it |
 | --- | --- |
 | `x.py check` | Quick check to see if things compile; rust-analyzer can run this automatically for you |
-| `x.py build --stage 0 src/libstd` | Build only the standard library, without building the compiler |
-| `x.py build --stage 1 src/libstd` | 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 --stage 1 --keep-stage 1 src/libstd` | 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 --stage 1 [--keep-stage 1]` | Run the test suite using the stage1 compiler |
-| `x.py test --stage 1 --bless [--keep-stage 1]` | Run the test suite using the stage1 compiler _and_ update expected test output. |
-| `x.py build` | Do a full 2-stage build. You almost never want to do this. |
-| `x.py test` | Do a full 2-stage build and run all tests. You almost never want to do this. |
+| `x.py build --stage 0 [src/libstd]` | Build only the standard library, without building the compiler |
+| `x.py build src/libstd` | 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 src/libstd` | 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 src/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):
 
 ```sh
-./x.py build
+./x.py build --stage 2 src/rustc
 ```
 
 In the process, this will also necessarily build the standard libraries, and it
@@ -203,10 +203,10 @@ For most contributions, you only need to build stage 1, which saves a lot of tim
 
 ```sh
 # Build the compiler (stage 1)
-./x.py build --stage 1 src/libstd
+./x.py build src/libstd
 
 # Subsequent builds
-./x.py build --stage 1 --keep-stage 1 src/libstd
+./x.py build --keep-stage 1 src/libstd
 ```
 
 This will take a while, especially the first time. Be wary of accidentally
@@ -228,17 +228,17 @@ different test suites [in this chapter][testing].
 
 ```sh
 # First build
-./x.py test --stage 1 src/test/ui
+./x.py test src/test/ui
 
 # Subsequent builds
-./x.py test --stage 1 src/test/ui --keep-stage 1
+./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 --stage 1 src/test/ui --keep-stage 1 --bless
+./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
@@ -290,7 +290,7 @@ 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 src/libstd
+./x.py build --stage 0
 ```
 
 ```sh
@@ -303,17 +303,15 @@ stage 0, which uses the current beta compiler.
 
 `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.
-
-However, in practice, stage 1 should be sufficient. The first time you build,
+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 --stage 1 src/tools/rustdoc
+./x.py build
 
 # Subsequent builds
-./x.py build --stage 1 --keep-stage 1 src/tools/rustdoc
+./x.py build --keep-stage 1
 ```
 
 As with the compiler, you can do a fast check build:
@@ -326,13 +324,13 @@ Rustdoc has two types of tests: content tests and UI tests.
 
 ```sh
 # Content tests
-./x.py test --stage 1 src/test/rustdoc
+./x.py test src/test/rustdoc
 
 # UI tests
-./x.py test --stage 1 src/test/rustdoc-ui
+./x.py test src/test/rustdoc-ui
 
 # Both at once
-./x.py test --stage 1 src/test/rustdoc src/test/rustdoc-ui
+./x.py test src/test/rustdoc src/test/rustdoc-ui
 ```
 
 ### Contributing code to other Rust projects
diff --git a/src/doc/rustc-dev-guide/src/queries/profiling.md b/src/doc/rustc-dev-guide/src/queries/profiling.md
index 958dd333769..33d001f3994 100644
--- a/src/doc/rustc-dev-guide/src/queries/profiling.md
+++ b/src/doc/rustc-dev-guide/src/queries/profiling.md
@@ -20,7 +20,7 @@ address [issue 42678](https://github.com/rust-lang/rust/issues/42678).
 Compile the compiler, up to at least stage 1:
 
 ```
-python x.py --stage 1
+x.py build src/libstd
 ```
 
 ### 2. Run `rustc`, with flags
diff --git a/src/doc/rustc-dev-guide/src/rustdoc.md b/src/doc/rustc-dev-guide/src/rustdoc.md
index 6ac944697ad..1a3cf7019f0 100644
--- a/src/doc/rustc-dev-guide/src/rustdoc.md
+++ b/src/doc/rustc-dev-guide/src/rustdoc.md
@@ -30,7 +30,7 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
 
 ## Cheat sheet
 
-* Use `./x.py build --stage 1 src/libstd src/tools/rustdoc` to make a usable
+* Use `./x.py build` to make a usable
   rustdoc you can run on other projects.
   * Add `src/libtest` to be able to use `rustdoc --test`.
   * If you've used `rustup toolchain link local /path/to/build/$TARGET/stage1`
@@ -41,7 +41,7 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
   * The completed docs will be available in `build/$TARGET/doc/std`, though the
     bundle is meant to be used as though you would copy out the `doc` folder to
     a web server, since that's where the CSS/JS and landing page are.
-* Use `x.py test --stage 1 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.
 * Most of the HTML printing code is in `html/format.rs` and `html/render.rs`.
   It's in a bunch of `fmt::Display` implementations and supplementary
diff --git a/src/doc/rustc-dev-guide/src/tests/running.md b/src/doc/rustc-dev-guide/src/tests/running.md
index a6303c1a6fc..44561f6f2da 100644
--- a/src/doc/rustc-dev-guide/src/tests/running.md
+++ b/src/doc/rustc-dev-guide/src/tests/running.md
@@ -7,7 +7,7 @@ you will almost never want to use! – is as follows:
 ./x.py test
 ```
 
-This will build the full stage 2 compiler and then run the whole test
+This will build the stage 1 compiler and then run the whole test
 suite. You probably don't want to do this very often, because it takes
 a very long time, and anyway bors / travis will do it for you. (Often,
 I will run this command in the background after opening a PR that I
@@ -29,35 +29,34 @@ If you are building gdb from source, you will need to configure with
 ## Running a subset of the test suites
 
 When working on a specific PR, you will usually want to run a smaller
-set of tests, and with a stage 1 build. For example, a good "smoke
-test" that can be used after modifying rustc to see if things are
-generally working correctly would be the following:
+set of tests. For example, a good "smoke test" that can be used after
+modifying rustc to see if things are generally working correctly would be the
+following:
 
 ```bash
-./x.py test --stage 1 src/test/{ui,compile-fail}
+./x.py test src/test/{ui,compile-fail}
 ```
 
-This will run the `ui` and `compile-fail` test suites,
-and only with the stage 1 build. Of course, the choice of test suites
-is somewhat arbitrary, and may not suit the task you are doing. For
-example, if you are hacking on debuginfo, you may be better off with
-the debuginfo test suite:
+This will run the `ui` and `compile-fail` test suites. Of course, the choice
+of test suites is somewhat arbitrary, and may not suit the task you are
+doing. For example, if you are hacking on debuginfo, you may be better off
+with the debuginfo test suite:
 
 ```bash
-./x.py test --stage 1 src/test/debuginfo
+./x.py test src/test/debuginfo
 ```
 
 If you only need to test a specific subdirectory of tests for any
 given test suite, you can pass that directory to `x.py test`:
 
 ```bash
-./x.py test --stage 1 src/test/ui/const-generics
+./x.py test src/test/ui/const-generics
 ```
 
 Likewise, you can test a single file by passing its path:
 
 ```bash
-./x.py test --stage 1 src/test/ui/const-generics/const-test.rs
+./x.py test src/test/ui/const-generics/const-test.rs
 ```
 
 ### Run only the tidy script
@@ -81,7 +80,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 src/libstd --stage 1
+>   ./x.py test src/libstd
 ```
 
 By listing which test suites you want to run you avoid having to run
@@ -99,7 +98,7 @@ you may pass the full file path to achieve this, or alternatively one
 may invoke `x.py` with the `--test-args` option:
 
 ```bash
-./x.py test --stage 1 src/test/ui --test-args issue-1234
+./x.py test src/test/ui --test-args issue-1234
 ```
 
 Under the hood, the test runner invokes the standard rust test runner
@@ -114,7 +113,7 @@ making a new test, you can pass `--bless` to the test subcommand. E.g.
 if some tests in `src/test/ui` are failing, you can run
 
 ```text
-./x.py test --stage 1 src/test/ui --bless
+./x.py test src/test/ui --bless
 ```
 
 to automatically adjust the `.stderr`, `.stdout` or `.fixed` files of
@@ -130,7 +129,7 @@ exists in the test file. For example, you can run all the tests in
 `src/test/ui` as `check-pass`:
 
 ```bash
-./x.py test --stage 1 src/test/ui --pass check
+./x.py test src/test/ui --pass check
 ```
 
 By passing `--pass $mode`, you can reduce the testing time. For each
@@ -144,7 +143,7 @@ You can further enable the `--incremental` flag to save additional
 time in subsequent rebuilds:
 
 ```bash
-./x.py test --stage 1 src/test/ui --incremental --test-args issue-1234
+./x.py test src/test/ui --incremental --test-args issue-1234
 ```
 
 If you don't want to include the flag with every command, you can