From 444a5ebdc5ec007db54dfa2f78ad436346a93984 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sun, 10 Jul 2022 22:08:32 -0500 Subject: [PATCH] Update the build instructions for the standard library Since https://github.com/rust-lang/rust/pull/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 --- src/building/bootstrapping.md | 6 ++--- src/building/compiler-documenting.md | 2 +- src/building/how-to-build-and-run.md | 34 ++++++++-------------------- src/building/suggested.md | 8 +++---- src/contributing.md | 2 +- src/profiling/wpa_profiling.md | 4 ++-- src/rustdoc-internals.md | 2 +- src/rustdoc.md | 4 ++-- src/tests/intro.md | 4 ++-- src/tests/running.md | 7 ++++-- 10 files changed, 30 insertions(+), 43 deletions(-) diff --git a/src/building/bootstrapping.md b/src/building/bootstrapping.md index c61afbcd9..31f9b61d6 100644 --- a/src/building/bootstrapping.md +++ b/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,7 +169,7 @@ 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: @@ -177,7 +177,7 @@ Build artifacts include, but are not limited to: 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 --git a/src/building/compiler-documenting.md b/src/building/compiler-documenting.md index f921cd089..fa59e863b 100644 --- a/src/building/compiler-documenting.md +++ b/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 --git a/src/building/how-to-build-and-run.md b/src/building/how-to-build-and-run.md index 9ef43e341..39715bcd2 100644 --- a/src/building/how-to-build-and-run.md +++ b/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 --git a/src/building/suggested.md b/src/building/suggested.md index a815afda5..1c2229335 100644 --- a/src/building/suggested.md +++ b/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 --git a/src/contributing.md b/src/contributing.md index 48d8b2d15..7eeb0240b 100644 --- a/src/contributing.md +++ b/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 --git a/src/profiling/wpa_profiling.md b/src/profiling/wpa_profiling.md index 7943cf5a4..e7cf9418c 100644 --- a/src/profiling/wpa_profiling.md +++ b/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 --git a/src/rustdoc-internals.md b/src/rustdoc-internals.md index 1050c259b..91bb0c358 100644 --- a/src/rustdoc-internals.md +++ b/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 --git a/src/rustdoc.md b/src/rustdoc.md index 7d07c0414..4cdda5a3e 100644 --- a/src/rustdoc.md +++ b/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 --git a/src/tests/intro.md b/src/tests/intro.md index 92f6cb664..8b65e4df5 100644 --- a/src/tests/intro.md +++ b/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 --git a/src/tests/running.md b/src/tests/running.md index 5d8417188..be9d965e4 100644 --- a/src/tests/running.md +++ b/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