mirror
/
rustc-dev-guide
mirror of https://github.com/rust-lang/rustc-dev-guide.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Change `./x.py` into `./x`

This commit is contained in:
sslime336 2023-07-01 00:43:15 +08:00 committed by Tshepang Mbambo
parent 71bdc1c631
commit a04ad82e3c
29 changed files with 155 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -118,7 +118,7 @@ git submodule update --remote src/doc/rustc-dev-guide
git add -u git add -u
git commit -m "Update rustc-dev-guide" git commit -m "Update rustc-dev-guide"
# Note that you can use -i, which is short for --incremental, in the following command # Note that you can use -i, which is short for --incremental, in the following command
./x.py test --incremental src/doc/rustc-dev-guide # This is optional and should succeed anyway ./x test --incremental src/doc/rustc-dev-guide # This is optional and should succeed anyway
# Open a PR in rust-lang/rust # Open a PR in rust-lang/rust
``` ```

8
src/backend/updating-llvm.md
View File

@ -90,16 +90,16 @@ so let's go through each in detail.
`src/llvm-project` to ensure submodule updates aren't reverted. `src/llvm-project` to ensure submodule updates aren't reverted.
Some commands you should execute are: Some commands you should execute are:
* `./x.py build src/llvm` - test that LLVM still builds * `./x build src/llvm` - test that LLVM still builds
* `./x.py build src/tools/lld` - same for LLD * `./x build src/tools/lld` - same for LLD
* `./x.py build` - build the rest of rustc * `./x build` - build the rest of rustc
You'll likely need to update [`llvm-wrapper/*.cpp`][`llvm-wrapper`] You'll likely need to update [`llvm-wrapper/*.cpp`][`llvm-wrapper`]
to compile with updated LLVM bindings. to compile with updated LLVM bindings.
Note that you should use `#ifdef` and such to ensure Note that you should use `#ifdef` and such to ensure
that the bindings still compile on older LLVM versions. that the bindings still compile on older LLVM versions.
Note that `profile = "compiler"` and other defaults set by `./x.py setup` Note that `profile = "compiler"` and other defaults set by `./x setup`
download LLVM from CI instead of building it from source. download LLVM from CI instead of building it from source.
You should disable this temporarily to make sure your changes are being used. You should disable this temporarily to make sure your changes are being used.
This is done by having the following setting in `config.toml`: This is done by having the following setting in `config.toml`:

2
src/bug-fix-procedure.md
View File

@ -325,7 +325,7 @@ general, if the test used to have `#[deny(overlapping_inherent_impls)]`, that
can just be removed. can just be removed.
``` ```
./x.py test ./x test
``` ```
#### All done! #### All done!

22
src/building/bootstrapping.md
View File

@ -96,7 +96,7 @@ However, it takes a very long time to build
because one must first build the new compiler with an older compiler because one must first build the new compiler with an older compiler
and then use that to build the new compiler with itself. and then use that to build the new compiler with itself.
For development, you usually only want the `stage1` compiler, For development, you usually only want the `stage1` compiler,
which you can build with `./x.py build library`. which you can build with `./x build library`.
See [Building the compiler](./how-to-build-and-run.html#building-the-compiler). See [Building the compiler](./how-to-build-and-run.html#building-the-compiler).
### Stage 3: the same-result test ### Stage 3: the same-result test
@ -173,27 +173,27 @@ Build artifacts include, but are not limited to:
#### Examples #### Examples
- `./x.py build --stage 0` means to build with the beta `rustc`. - `./x build --stage 0` means to build with the beta `rustc`.
- `./x.py doc --stage 0` means to document using the beta `rustdoc`. - `./x doc --stage 0` means to document using the beta `rustdoc`.
- `./x.py test --stage 0 library/std` means to run tests on the standard library - `./x test --stage 0 library/std` means to run tests on the standard library
without building `rustc` from source ('build with stage 0, then test the without building `rustc` from source ('build with stage 0, then test the
artifacts'). If you're working on the standard library, this is normally the artifacts'). If you're working on the standard library, this is normally the
test command you want. test command you want.
- `./x.py test tests/ui` means to build the stage 1 compiler and run - `./x test tests/ui` means to build the stage 1 compiler and run
`compiletest` on it. If you're working on the compiler, this is normally the `compiletest` on it. If you're working on the compiler, this is normally the
test command you want. test command you want.
#### Examples of what *not* to do #### Examples of what *not* to do
- `./x.py test --stage 0 tests/ui` is not useful: it runs tests on the - `./x test --stage 0 tests/ui` is not useful: it runs tests on the
_beta_ compiler and doesn't build `rustc` from source. Use `test tests/ui` _beta_ compiler and doesn't build `rustc` from source. Use `test tests/ui`
instead, which builds stage 1 from source. instead, which builds stage 1 from source.
- `./x.py test --stage 0 compiler/rustc` builds the compiler but runs no tests: - `./x 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 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). 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 - `./x 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 libstd or even libcore. Most of the time, you'll want `./x build
library` instead, which allows compiling programs without needing to define library` instead, which allows compiling programs without needing to define
lang items. lang items.
### Building vs. running ### Building vs. running

14
src/building/build-install-distribution-artifacts.md
View File

@ -3,22 +3,22 @@
You might want to build and package up the compiler for distribution. You might want to build and package up the compiler for distribution.
You’ll want to run this command to do it: You’ll want to run this command to do it:
```bash ```bash
./x.py dist ./x dist
``` ```
# Install distribution artifacts # Install distribution artifacts
If you’ve built a distribution artifact you might want to install it and If you’ve built a distribution artifact you might want to install it and
test that it works on your target system. You’ll want to run this command: test that it works on your target system. You’ll want to run this command:
```bash ```bash
./x.py install ./x install
``` ```
Note: If you are testing out a modification to a compiler, you Note: If you are testing out a modification to a compiler, you
might want to use it to compile some project. might want to use it to compile some project.
Usually, you do not want to use `./x.py install` for testing. Usually, you do not want to use `./x install` for testing.
Rather, you should create a toolchain as discussed in Rather, you should create a toolchain as discussed in
[here][create-rustup-toolchain]. [here][create-rustup-toolchain].

10
src/building/compiler-documenting.md
View File

@ -10,13 +10,13 @@ like the standard library (std) or the compiler (rustc).
as rustdoc is under active development: as rustdoc is under active development:
```bash ```bash
./x.py doc ./x doc
``` ```
If you want to be sure the documentation looks the same as on CI: If you want to be sure the documentation looks the same as on CI:
```bash ```bash
./x.py doc --stage 1 ./x doc --stage 1
``` ```
This ensures that (current) rustdoc gets built, This ensures that (current) rustdoc gets built,
@ -26,9 +26,9 @@ like the standard library (std) or the compiler (rustc).
you can build just the documentation you want: you can build just the documentation you want:
```bash ```bash
./x.py doc src/doc/book ./x doc src/doc/book
./x.py doc src/doc/nomicon ./x doc src/doc/nomicon
./x.py doc compiler library ./x doc compiler library
``` ```
See [the nightly docs index page](https://doc.rust-lang.org/nightly/) for a full list of books. See [the nightly docs index page](https://doc.rust-lang.org/nightly/) for a full list of books.

50
src/building/how-to-build-and-run.md
View File

@ -62,7 +62,7 @@ if you want to learn more about `x.py`, [read this chapter][bootstrap].
The `x.py` command can be run directly on most Unix systems in the following format: The `x.py` command can be run directly on most Unix systems in the following format:
```sh ```sh
./x.py <subcommand> [flags] ./x <subcommand> [flags]
``` ```
This is how the documentation and examples assume you are running `x.py`. This is how the documentation and examples assume you are running `x.py`.
@ -110,7 +110,7 @@ You can install it with `cargo install --path src/tools/x`.
## Create a `config.toml` ## Create a `config.toml`
To start, run `./x.py setup` and select the `compiler` defaults. This will do some initialization To start, run `./x setup` and select the `compiler` defaults. This will do some initialization
and create a `config.toml` for you with reasonable defaults. If you use a different default (which and create a `config.toml` for you with reasonable defaults. If you use a different default (which
you'll likely want to do if you want to contribute to an area of rust other than the compiler, such you'll likely want to do if you want to contribute to an area of rust other than the compiler, such
as rustdoc), make sure to read information about that default (located in `src/bootstrap/defaults`) as rustdoc), make sure to read information about that default (located in `src/bootstrap/defaults`)
@ -120,7 +120,7 @@ Alternatively, you can write `config.toml` by hand. See `config.example.toml` fo
settings and explanations of them. See `src/bootstrap/defaults` for common settings to change. settings and explanations of them. See `src/bootstrap/defaults` for common settings to change.
If you have already built `rustc` and you change settings related to LLVM, then you may have to If you have already built `rustc` and you change settings related to LLVM, then you may have to
execute `rm -rf build` for subsequent configuration changes to take effect. Note that `./x.py execute `rm -rf build` for subsequent configuration changes to take effect. Note that `./x
clean` will not cause a rebuild of LLVM. clean` will not cause a rebuild of LLVM.
## Common `x.py` commands ## Common `x.py` commands
@ -128,16 +128,16 @@ clean` will not cause a rebuild of LLVM.
Here are the basic invocations of the `x.py` commands most commonly used when Here are the basic invocations of the `x.py` commands most commonly used when
working on `rustc`, `std`, `rustdoc`, and other tools. working on `rustc`, `std`, `rustdoc`, and other tools.
| Command | When to use it | | Command | When to use it |
| --- | --- | | ----------- | ------------------------------------------------------------------------------------------------------------ |
| `./x.py check` | Quick check to see if most things compile; [rust-analyzer can run this automatically for you][rust-analyzer] | | `./x 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 build` | Builds `rustc`, `std`, and `rustdoc` |
| `./x.py test` | Runs all tests | | `./x test` | Runs all tests |
| `./x.py fmt` | Formats all code | | `./x fmt` | Formats all code |
As written, these commands are reasonable starting points. However, there are As written, these commands are reasonable starting points. However, there are
additional options and arguments for each of them that are worth learning for 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` serious development work. In particular, `./x build` and `./x test`
provide many ways to compile or test a subset of the code, which can save a lot provide many ways to compile or test a subset of the code, which can save a lot
of time. of time.
@ -160,7 +160,7 @@ Once you've created a `config.toml`, you are now ready to run
probably the best "go to" command for building a local compiler: probably the best "go to" command for building a local compiler:
```bash ```bash
./x.py build library ./x build library
``` ```
This may *look* like it only builds the standard library, but that is not the case. This may *look* like it only builds the standard library, but that is not the case.
@ -183,10 +183,10 @@ see [the section on avoiding rebuilds for std][keep-stage].
Sometimes you don't need a full build. When doing some kind of Sometimes you don't need a full build. When doing some kind of
"type-based refactoring", like renaming a method, or changing the "type-based refactoring", like renaming a method, or changing the
signature of some function, you can use `./x.py check` instead for a much faster build. signature of some function, you can use `./x check` instead for a much faster build.
Note that this whole command just gives you a subset of the full `rustc` 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 build. The **full** `rustc` build (what you get with `./x build
--stage 2 compiler/rustc`) has quite a few more steps: --stage 2 compiler/rustc`) has quite a few more steps:
- Build `rustc` with the stage1 compiler. - Build `rustc` with the stage1 compiler.
@ -203,7 +203,7 @@ the compiler unless you are planning to use a recently added nightly feature.
Instead, you can just build using the bootstrap compiler. Instead, you can just build using the bootstrap compiler.
```bash ```bash
./x.py build --stage 0 library ./x build --stage 0 library
``` ```
If you choose the `library` profile when running `x.py setup`, you can omit `--stage 0` (it's the If you choose the `library` profile when running `x.py setup`, you can omit `--stage 0` (it's the
@ -256,7 +256,7 @@ custom toolchain for a project (e.g. via `rustup override set stage1`) you may
want to build this component: want to build this component:
```bash ```bash
./x.py build proc-macro-srv-cli ./x build proc-macro-srv-cli
``` ```
## Building targets for cross-compilation ## Building targets for cross-compilation
@ -267,7 +267,7 @@ For example, if your host platform is `x86_64-unknown-linux-gnu`
and your cross-compilation target is `wasm32-wasi`, you can build with: and your cross-compilation target is `wasm32-wasi`, you can build with:
```bash ```bash
./x.py build --target x86_64-unknown-linux-gnu --target wasm32-wasi ./x build --target x86_64-unknown-linux-gnu --target wasm32-wasi
``` ```
Note that if you want the resulting compiler to be able to build crates that Note that if you want the resulting compiler to be able to build crates that
@ -309,18 +309,18 @@ Here are a few other useful `x.py` commands. We'll cover some of them in detail
in other sections: in other sections:
- Building things: - Building things:
- `./x.py build` – builds everything using the stage 1 compiler, - `./x build` – builds everything using the stage 1 compiler,
not just up to `std` not just up to `std`
- `./x.py build --stage 2` – builds everything with the stage 2 compiler including - `./x build --stage 2` – builds everything with the stage 2 compiler including
`rustdoc` `rustdoc`
- Running tests (see the [section on running tests](../tests/running.html) for - Running tests (see the [section on running tests](../tests/running.html) for
more details): more details):
- `./x.py test library/std` – runs the unit tests and integration tests from `std` - `./x test library/std` – runs the unit tests and integration tests from `std`
- `./x.py test tests/ui` – runs the `ui` test suite - `./x test tests/ui` – runs the `ui` test suite
- `./x.py test tests/ui/const-generics` - runs all the tests in - `./x test tests/ui/const-generics` - runs all the tests in
the `const-generics/` subdirectory of the `ui` test suite the `const-generics/` subdirectory of the `ui` test suite
- `./x.py test tests/ui/const-generics/const-types.rs` - runs - `./x test tests/ui/const-generics/const-types.rs` - runs
the single test `const-types.rs` from the `ui` test suite the single test `const-types.rs` from the `ui` test suite
### Cleaning out build directories ### Cleaning out build directories
@ -330,7 +330,7 @@ you should file a bug as to what is going wrong. If you do need to clean
everything up then you only need to run one command! everything up then you only need to run one command!
```bash ```bash
./x.py clean ./x clean
``` ```
`rm -rf build` works too, but then you have to rebuild LLVM, which can take `rm -rf build` works too, but then you have to rebuild LLVM, which can take

4
src/building/new-target.md
View File

@ -10,7 +10,7 @@ relevant to your desired goal.
For very new targets, you may need to use a different fork of LLVM For very new targets, you may need to use a different fork of LLVM
than what is currently shipped with Rust. In that case, navigate to than what is currently shipped with Rust. In that case, navigate to
the `src/llvm-project` git submodule (you might need to run `./x.py the `src/llvm-project` git submodule (you might need to run `./x
check` at least once so the submodule is updated), check out the check` at least once so the submodule is updated), check out the
appropriate commit for your fork, then commit that new submodule appropriate commit for your fork, then commit that new submodule
reference in the main Rust repository. reference in the main Rust repository.
@ -135,7 +135,7 @@ cross-compile `rustc`:
``` ```
DESTDIR=/path/to/install/in \ DESTDIR=/path/to/install/in \
./x.py install -i --stage 1 --host aarch64-apple-darwin.json --target aarch64-apple-darwin \ ./x install -i --stage 1 --host aarch64-apple-darwin.json --target aarch64-apple-darwin \
compiler/rustc library/std compiler/rustc library/std
``` ```

2
src/building/prerequisites.md
View File

@ -20,7 +20,7 @@ recommend trying to build on a Raspberry Pi! We recommend the following.
* 2+ cores. Having more cores really helps. 10 or 20 or more is not too many! * 2+ cores. Having more cores really helps. 10 or 20 or more is not too many!
Beefier machines will lead to much faster builds. If your machine is not very Beefier machines will lead to much faster builds. If your machine is not very
powerful, a common strategy is to only use `./x.py check` on your local machine powerful, a common strategy is to only use `./x check` on your local machine
and let the CI build test your changes when you push to a PR branch. and let the CI build test your changes when you push to a PR branch.
Building the compiler takes more than half an hour on my moderately powerful Building the compiler takes more than half an hour on my moderately powerful

34
src/building/suggested.md
View File

@ -10,14 +10,14 @@ to make your life easier.
CI will automatically fail your build if it doesn't pass `tidy`, our CI will automatically fail your build if it doesn't pass `tidy`, our
internal tool for ensuring code quality. If you'd like, you can install a internal tool for ensuring code quality. If you'd like, you can install a
[Git hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) [Git hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks)
that will automatically run `./x.py test tidy` on each push, to ensure that will automatically run `./x test tidy` on each push, to ensure
your code is up to par. If the hook fails then run `./x.py test tidy --bless` your code is up to par. If the hook fails then run `./x test tidy --bless`
and commit the changes. If you decide later that the pre-push behavior is and commit the changes. If you decide later that the pre-push behavior is
undesirable, you can delete the `pre-push` file in `.git/hooks`. undesirable, you can delete the `pre-push` file in `.git/hooks`.
A prebuilt git hook lives at [`src/etc/pre-push.sh`](https://github.com/rust-lang/rust/blob/master/src/etc/pre-push.sh) which can be copied into your `.git/hooks` folder as `pre-push` (without the `.sh` extension!). A prebuilt git hook lives at [`src/etc/pre-push.sh`](https://github.com/rust-lang/rust/blob/master/src/etc/pre-push.sh) which can be copied into your `.git/hooks` folder as `pre-push` (without the `.sh` extension!).
You can also install the hook as a step of running `./x.py setup`! You can also install the hook as a step of running `./x setup`!
## Configuring `rust-analyzer` for `rustc` ## Configuring `rust-analyzer` for `rustc`
@ -28,7 +28,7 @@ a file. By default, `rust-analyzer` runs the `cargo check` and `rustfmt`
commands, but you can override these commands to use more adapted versions commands, but you can override these commands to use more adapted versions
of these tools when hacking on `rustc`. For example, `x.py setup vscode` will prompt of these tools when hacking on `rustc`. For example, `x.py setup vscode` will prompt
you to create a `.vscode/settings.json` file which will configure Visual Studio code. you to create a `.vscode/settings.json` file which will configure Visual Studio code.
This will ask `rust-analyzer` to use `./x.py check` to check the sources, and the This will ask `rust-analyzer` to use `./x check` to check the sources, and the
stage 0 rustfmt to format them. stage 0 rustfmt to format them.
The recommended `rust-analyzer` settings live at [`src/etc/rust_analyzer_settings.json`]. The recommended `rust-analyzer` settings live at [`src/etc/rust_analyzer_settings.json`].
@ -41,7 +41,7 @@ If you're running `coc.nvim`, you can use `:CocLocalConfig` to create a
[`src/etc/rust_analyzer_settings.json`]: https://github.com/rust-lang/rust/blob/master/src/etc/rust_analyzer_settings.json [`src/etc/rust_analyzer_settings.json`]: https://github.com/rust-lang/rust/blob/master/src/etc/rust_analyzer_settings.json
If running `./x.py check` on save is inconvenient, in VS Code you can use a [Build If running `./x check` on save is inconvenient, in VS Code you can use a [Build
Task] instead: Task] instead:
```JSON ```JSON
@ -50,8 +50,8 @@ Task] instead:
"version": "2.0.0", "version": "2.0.0",
"tasks": [ "tasks": [
{ {
"label": "./x.py check", "label": "./x check",
"command": "./x.py check", "command": "./x check",
"type": "shell", "type": "shell",
"problemMatcher": "$rustc", "problemMatcher": "$rustc",
"presentation": { "clear": true }, "presentation": { "clear": true },
@ -73,9 +73,9 @@ Rust-Analyzer to already be configured with Neovim. Steps for this can be
[found here](https://rust-analyzer.github.io/manual.html#nvim-lsp). [found here](https://rust-analyzer.github.io/manual.html#nvim-lsp).
1. First install the plugin. This can be done by following the steps in the README. 1. First install the plugin. This can be done by following the steps in the README.
2. Run `x.py setup`, which will have a prompt for it to create a `.vscode/settings.json` file. 2. Run `x.py setup`, which will have a prompt for it to create a `.vscode/settings.json` file.
`neoconf` is able to read and update Rust-Analyzer settings automatically when the project is `neoconf` is able to read and update Rust-Analyzer settings automatically when the project is
opened when this file is detected. opened when this file is detected.
If you're running `coc.nvim`, you can use `:CocLocalConfig` to create a If you're running `coc.nvim`, you can use `:CocLocalConfig` to create a
`.vim/coc-settings.json` and copy the settings from `.vim/coc-settings.json` and copy the settings from
@ -94,11 +94,11 @@ follow the same instructions as above.
## Check, check, and check again ## Check, check, and check again
When doing simple refactorings, it can be useful to run `./x.py check` When doing simple refactorings, it can be useful to run `./x check`
continuously. If you set up `rust-analyzer` as described above, this will continuously. If you set up `rust-analyzer` as described above, this will
be done for you every time you save a file. Here you are just checking that be done for you every time you save a file. Here you are just checking that
the compiler can **build**, but often that is all you need (e.g., when renaming a the compiler can **build**, but often that is all you need (e.g., when renaming a
method). You can then run `./x.py build` when you actually need to method). You can then run `./x build` when you actually need to
run tests. run tests.
In fact, it is sometimes useful to put off tests even when you are not In fact, it is sometimes useful to put off tests even when you are not
@ -166,13 +166,13 @@ don't work (but that is easily detected and fixed).
The sequence of commands you want is as follows: The sequence of commands you want is as follows:
- Initial build: `./x.py build library` - Initial build: `./x build library`
- As [documented previously], this will build a functional - As [documented previously], this will build a functional
stage1 compiler as part of running all stage0 commands (which include stage1 compiler as part of running all stage0 commands (which include
building a `std` compatible with the stage1 compiler) as well as the 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) first few steps of the "stage 1 actions" up to "stage1 (sysroot stage1)
builds std". builds std".
- Subsequent builds: `./x.py build library --keep-stage 1` - Subsequent builds: `./x build library --keep-stage 1`
- Note that we added the `--keep-stage 1` flag here - Note that we added the `--keep-stage 1` flag here
[documented previously]: ./how-to-build-and-run.md#building-the-compiler [documented previously]: ./how-to-build-and-run.md#building-the-compiler
@ -194,8 +194,8 @@ rebuild. That ought to fix the problem.
You can also use `--keep-stage 1` when running tests. Something like this: You can also use `--keep-stage 1` when running tests. Something like this:
- Initial test run: `./x.py test tests/ui` - Initial test run: `./x test tests/ui`
- Subsequent test run: `./x.py test tests/ui --keep-stage 1` - Subsequent test run: `./x test tests/ui --keep-stage 1`
## Using incremental compilation ## Using incremental compilation
@ -203,7 +203,7 @@ You can further enable the `--incremental` flag to save additional
time in subsequent rebuilds: time in subsequent rebuilds:
```bash ```bash
./x.py test tests/ui --incremental --test-args issue-1234 ./x test tests/ui --incremental --test-args issue-1234
``` ```
If you don't want to include the flag with every command, you can If you don't want to include the flag with every command, you can

4
src/contributing.md
View File

@ -200,7 +200,7 @@ of the status of a particular pull request.
Rust has plenty of CI capacity, and you should never have to worry about wasting Rust has plenty of CI capacity, and you should never have to worry about wasting
computational resources each time you push a change. It is also perfectly fine computational resources each time you push a change. It is also perfectly fine
(and even encouraged!) to use the CI to test your changes if it can help your (and even encouraged!) to use the CI to test your changes if it can help your
productivity. In particular, we don't recommend running the full `./x.py test` suite locally, productivity. In particular, we don't recommend running the full `./x test` suite locally,
since it takes a very long time to execute. since it takes a very long time to execute.
### r+ ### r+
@ -241,7 +241,7 @@ branch, `master` will be the right choice (it's also the default).
Make sure your pull request is in compliance with Rust's style guidelines by running Make sure your pull request is in compliance with Rust's style guidelines by running
$ ./x.py test tidy --bless $ ./x test tidy --bless
We recommend to make this check before every pull request (and every new commit We recommend to make this check before every pull request (and every new commit
in a pull request); you can add [git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) in a pull request); you can add [git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks)

8
src/conventions.md
View File

@ -13,11 +13,11 @@ 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`]. special config, so this may result in different style from normal [`rustfmt`].
Therefore, formatting this repository using `cargo fmt` is not recommended. Therefore, formatting this repository using `cargo fmt` is not recommended.
Instead, formatting should be done using `./x.py fmt`. It's a good habit to run Instead, formatting should be done using `./x fmt`. It's a good habit to run
`./x.py fmt` before every commit, as this reduces conflicts later. `./x fmt` before every commit, as this reduces conflicts later.
Formatting is checked by the `tidy` script. It runs automatically when you do 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 fmt --check`. `./x test` and can be run in isolation with `./x fmt --check`.
If you want to use format-on-save in your editor, the pinned version of 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 `rustfmt` is built under `build/<target>/stage0/bin/rustfmt`. You'll have to
@ -126,7 +126,7 @@ dramatically (versus adding to it) in a later commit, that
**Format liberally.** While only the final commit of a PR must be correctly **Format liberally.** While only the final commit of a PR must be correctly
formatted, it is both easier to review and less noisy to format each commit formatted, it is both easier to review and less noisy to format each commit
individually using `./x.py fmt`. individually using `./x fmt`.
**No merges.** We do not allow merge commits into our history, other **No merges.** We do not allow merge commits into our history, other
than those by bors. If you get a merge conflict, rebase instead via a than those by bors. If you get a merge conflict, rebase instead via a

2
src/diagnostics/error-codes.md
View File

@ -37,7 +37,7 @@ To create a new error, you first need to find the next available
code. You can find it with `tidy`: code. You can find it with `tidy`:
``` ```
./x.py test tidy ./x test tidy
``` ```
This will invoke the tidy script, which generally checks that your code obeys This will invoke the tidy script, which generally checks that your code obeys

4
src/git.md
View File

@ -10,7 +10,7 @@ can be incorporated into the compiler.
The goal of this page is to cover some of the more common questions and The goal of this page is to cover some of the more common questions and
problems new contributors face. Although some Git basics will be covered here, problems new contributors face. Although some Git basics will be covered here,
if you find that this is still a little too fast for you, it might make sense if you find that this is still a little too fast for you, it might make sense
to first read some introductions to Git, such as the Beginner and Getting to first read some introductions to Git, such as the Beginner and Getting
started sections of [this tutorial from Atlassian][atlassian-git]. GitHub also started sections of [this tutorial from Atlassian][atlassian-git]. GitHub also
provides [documentation] and [guides] for beginners, or you can consult the provides [documentation] and [guides] for beginners, or you can consult the
@ -239,7 +239,7 @@ no changes added to commit (use "git add" and/or "git commit -a")
``` ```
These changes are not changes to files: they are changes to submodules (more on this These changes are not changes to files: they are changes to submodules (more on this
[later](#git-submodules)). To get rid of those, run `./x.py --help`, which will automatically update [later](#git-submodules)). To get rid of those, run `./x --help`, which will automatically update
the submodules. the submodules.
Some submodules are not actually needed; for example, `src/llvm-project` doesn't need to be checked Some submodules are not actually needed; for example, `src/llvm-project` doesn't need to be checked

3
src/implementing_new_features.md
View File

@ -177,8 +177,7 @@ a new unstable feature:
1. Add a test to ensure the feature cannot be used without 1. Add a test to ensure the feature cannot be used without
a feature gate, by creating `tests/ui/feature-gates/feature-gate-$feature_name.rs`. a feature gate, by creating `tests/ui/feature-gates/feature-gate-$feature_name.rs`.
You can generate the corresponding `.stderr` file by running `./x.py test tests/ui/feature-gates/ You can generate the corresponding `.stderr` file by running `./x test tests/ui/feature-gates/ --bless`.
--bless`.
1. Add a section to the unstable book, in 1. Add a section to the unstable book, in
`src/doc/unstable-book/src/language-features/$feature_name.md`. `src/doc/unstable-book/src/language-features/$feature_name.md`.

4
src/llvm-coverage-instrumentation.md
View File

@ -292,8 +292,8 @@ Expected results for both the `mir-opt` tests and the `coverage*` tests under
`run-make-fulldeps` can be refreshed by running: `run-make-fulldeps` can be refreshed by running:
```shell ```shell
$ ./x.py test mir-opt --bless $ ./x test mir-opt --bless
$ ./x.py test tests/run-make-fulldeps/coverage --bless $ ./x test tests/run-make-fulldeps/coverage --bless
``` ```
[mir-opt-test]: https://github.com/rust-lang/rust/blob/master/tests/mir-opt/instrument_coverage.rs [mir-opt-test]: https://github.com/rust-lang/rust/blob/master/tests/mir-opt/instrument_coverage.rs

6
src/mir/optimizations.md
View File

@ -34,7 +34,7 @@ optimizes it, and returns the improved MIR.
`println!`, `format!`, etc. generate a lot of MIR that can make it harder to `println!`, `format!`, etc. generate a lot of MIR that can make it harder to
understand what the optimization does to the test. understand what the optimization does to the test.
2. Run `./x.py test --bless tests/mir-opt/<your-test>.rs` to generate a MIR 2. Run `./x test --bless tests/mir-opt/<your-test>.rs` to generate a MIR
dump. Read [this README][mir-opt-test-readme] for instructions on how to dump dump. Read [this README][mir-opt-test-readme] for instructions on how to dump
things. things.
@ -51,10 +51,10 @@ optimizes it, and returns the improved MIR.
[`run_optimization_passes()`] function, [`run_optimization_passes()`] function,
3. and then start modifying the copied optimization. 3. and then start modifying the copied optimization.
5. Rerun `./x.py test --bless tests/mir-opt/<your-test>.rs` to regenerate the 5. Rerun `./x test --bless tests/mir-opt/<your-test>.rs` to regenerate the
MIR dumps. Look at the diffs to see if they are what you expect. MIR dumps. Look at the diffs to see if they are what you expect.
6. Run `./x.py test tests/ui` to see if your optimization broke anything. 6. Run `./x test tests/ui` to see if your optimization broke anything.
7. If there are issues with your optimization, experiment with it a bit and 7. If there are issues with your optimization, experiment with it a bit and
repeat steps 5 and 6. repeat steps 5 and 6.

8
src/profiling.md
View File

@ -19,7 +19,7 @@ Depending on what you're trying to measure, there are several different approach
- If you want a nice visual representation of the compile times of your crate graph, - If you want a nice visual representation of the compile times of your crate graph,
you can use [cargo's `--timings` flag](https://doc.rust-lang.org/nightly/cargo/reference/timings.html), you can use [cargo's `--timings` flag](https://doc.rust-lang.org/nightly/cargo/reference/timings.html),
e.g. `cargo build --timings`. e.g. `cargo build --timings`.
You can use this flag on the compiler itself with `CARGOFLAGS="--timings" ./x.py build` You can use this flag on the compiler itself with `CARGOFLAGS="--timings" ./x build`
- If you want to profile memory usage, you can use various tools depending on what operating system - If you want to profile memory usage, you can use various tools depending on what operating system
you are using. you are using.
@ -44,8 +44,8 @@ cargo install cargo-llvm-lines
# On a normal crate you could now run `cargo llvm-lines`, but `x.py` isn't normal :P # On a normal crate you could now run `cargo llvm-lines`, but `x.py` isn't normal :P
# Do a clean before every run, to not mix in the results from previous runs. # Do a clean before every run, to not mix in the results from previous runs.
./x.py clean ./x clean
env RUSTFLAGS=-Csave-temps ./x.py build --stage 0 compiler/rustc env RUSTFLAGS=-Csave-temps ./x build --stage 0 compiler/rustc
# Single crate, e.g., rustc_middle. (Relies on the glob support of your shell.) # Single crate, e.g., rustc_middle. (Relies on the glob support of your shell.)
# Convert unoptimized LLVM bitcode into a human readable LLVM assembly accepted by cargo-llvm-lines. # Convert unoptimized LLVM bitcode into a human readable LLVM assembly accepted by cargo-llvm-lines.
@ -85,7 +85,7 @@ Example output for the compiler:
326903 (0.7%) 642 (0.0%) rustc_query_system::query::plumbing::try_execute_query 326903 (0.7%) 642 (0.0%) rustc_query_system::query::plumbing::try_execute_query
``` ```
Since this doesn't seem to work with incremental compilation or `./x.py check`, Since this doesn't seem to work with incremental compilation or `./x check`,
you will be compiling rustc _a lot_. you will be compiling rustc _a lot_.
I recommend changing a few settings in `config.toml` to make it bearable: I recommend changing a few settings in `config.toml` to make it bearable:
``` ```

2
src/profiling/with_perf.md
View File

@ -10,7 +10,7 @@ This is a guide for how to profile rustc with [perf](https://perf.wiki.kernel.or
- `debuginfo-level = 1` - enables line debuginfo - `debuginfo-level = 1` - enables line debuginfo
- `jemalloc = false` - lets you do memory use profiling with valgrind - `jemalloc = false` - lets you do memory use profiling with valgrind
- leave everything else the defaults - leave everything else the defaults
- Run `./x.py build` to get a full build - Run `./x build` to get a full build
- Make a rustup toolchain pointing to that result - Make a rustup toolchain pointing to that result
- see [the "build and run" section for instructions][b-a-r] - see [the "build and run" section for instructions][b-a-r]

2
src/rustdoc-internals.md
View File

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

10
src/rustdoc.md
View File

@ -41,24 +41,24 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
## Cheat sheet ## Cheat sheet
* Run `./x.py setup tools` before getting started. This will configure `x.py` * Run `./x setup tools` before getting started. This will configure `x.py`
with nice settings for developing rustdoc and other tools, including with nice settings for developing rustdoc and other tools, including
downloading a copy of rustc rather than building it. downloading a copy of rustc rather than building it.
* Use `./x.py check src/tools/rustdoc` to quickly check for compile errors. * Use `./x check src/tools/rustdoc` to quickly check for compile errors.
* Use `./x.py build` to make a usable * Use `./x build` to make a usable
rustdoc you can run on other projects. rustdoc you can run on other projects.
* Add `library/test` to be able to use `rustdoc --test`. * Add `library/test` to be able to use `rustdoc --test`.
* Run `rustup toolchain link stage2 build/host/stage2` to add a * Run `rustup toolchain link stage2 build/host/stage2` to add a
custom toolchain called `stage2` to your rustup environment. After custom toolchain called `stage2` to your rustup environment. After
running that, `cargo +stage2 doc` in any directory will build with running that, `cargo +stage2 doc` in any directory will build with
your locally-compiled rustdoc. your locally-compiled rustdoc.
* Use `./x.py doc library` to use this rustdoc to generate the * Use `./x doc library` to use this rustdoc to generate the
standard library docs. standard library docs.
* The completed docs will be available in `build/host/doc` (under `core`, `alloc`, and `std`). * The completed docs will be available in `build/host/doc` (under `core`, `alloc`, and `std`).
* If you want to copy those docs to a webserver, copy all of * If you want to copy those docs to a webserver, copy all of
`build/host/doc`, since that's where the CSS, JS, fonts, and landing `build/host/doc`, since that's where the CSS, JS, fonts, and landing
page are. page are.
* Use `./x.py test tests/rustdoc*` to run the tests using a stage1 * Use `./x test tests/rustdoc*` to run the tests using a stage1
rustdoc. rustdoc.
* See [Rustdoc internals] for more information about tests. * See [Rustdoc internals] for more information about tests.

2
src/sanitizers.md
View File

@ -98,7 +98,7 @@ To enable a sanitizer on a new target which is already supported by LLVM:
2. [Build the runtime for the target and include it in the libdir.][sanitizer-targets] 2. [Build the runtime for the target and include it in the libdir.][sanitizer-targets]
3. [Teach compiletest that your target now supports the sanitizer.][compiletest-definition] 3. [Teach compiletest that your target now supports the sanitizer.][compiletest-definition]
Tests marked with `needs-sanitizer-*` should now run on the target. Tests marked with `needs-sanitizer-*` should now run on the target.
4. Run tests `./x.py test --force-rerun tests/ui/sanitize/` to verify. 4. Run tests `./x test --force-rerun tests/ui/sanitize/` to verify.
5. [--enable-sanitizers in the CI configuration][ci-configuration] to build and 5. [--enable-sanitizers in the CI configuration][ci-configuration] to build and
distribute the sanitizer runtime as part of the release process. distribute the sanitizer runtime as part of the release process.

6
src/tests/adding.md
View File

@ -84,7 +84,7 @@ The next step is to create the expected output from the compiler.
This can be done with the `--bless` option: This can be done with the `--bless` option:
```sh ```sh
./x.py test tests/ui/async-await/await-without-async.rs --bless ./x test tests/ui/async-await/await-without-async.rs --bless
``` ```
This will build the compiler (if it hasn't already been built), compile the This will build the compiler (if it hasn't already been built), compile the
@ -118,7 +118,7 @@ annotations](ui.md#error-annotations) section).
Save that, and run the test again: Save that, and run the test again:
```sh ```sh
./x.py test tests/ui/async-await/await-without-async.rs ./x test tests/ui/async-await/await-without-async.rs
``` ```
It should now pass, yay! It should now pass, yay!
@ -166,7 +166,7 @@ The final step before posting a PR is to check if you have affected anything els
Running the UI suite is usually a good start: Running the UI suite is usually a good start:
```sh ```sh
./x.py test tests/ui ./x test tests/ui
``` ```
If other tests start failing, you may need to investigate what has changed If other tests start failing, you may need to investigate what has changed

6
src/tests/ci.md
View File

@ -6,7 +6,7 @@
When a Pull Request is opened on GitHub, [GitHub Actions] will automatically When a Pull Request is opened on GitHub, [GitHub Actions] will automatically
launch a build that will run all tests on some configurations launch a build that will run all tests on some configurations
(x86_64-gnu-llvm-13 linux, x86_64-gnu-tools linux, and mingw-check linux). (x86_64-gnu-llvm-13 linux, x86_64-gnu-tools linux, and mingw-check linux).
In essence, each runs `./x.py test` with various different options. In essence, each runs `./x test` with various different options.
The integration bot [bors] is used for coordinating merges to the master branch. The integration bot [bors] is used for coordinating merges to the master branch.
When a PR is approved, it goes into a [queue] where merges are tested one at a When a PR is approved, it goes into a [queue] where merges are tested one at a
@ -54,8 +54,8 @@ the other jobs.
The comment at the top of `ci.yml` will tell you to run this command: The comment at the top of `ci.yml` will tell you to run this command:
```sh ```sh
./x.py run src/tools/expand-yaml-anchors ./x run src/tools/expand-yaml-anchors
```` ```
This will generate the true [`.github/workflows/ci.yml`] which is what GitHub This will generate the true [`.github/workflows/ci.yml`] which is what GitHub
Actions uses. Actions uses.

7
src/tests/compiletest.md
View File

@ -503,10 +503,9 @@ currently only apply to the test as a whole, not to particular
revisions. The only headers that are intended to really work when revisions. The only headers that are intended to really work when
customized to a revision are error patterns and compiler flags. customized to a revision are error patterns and compiler flags.
## Compare modes ## Compare modes
Compiletest can be run in different modes, called *compare modes*, which can Compiletest can be run in different modes, called _compare modes_, which can
be used to compare the behavior of all tests with different compiler flags be used to compare the behavior of all tests with different compiler flags
enabled. enabled.
This can help highlight what differences might appear with certain flags, and This can help highlight what differences might appear with certain flags, and
@ -516,7 +515,7 @@ To run the tests in a different mode, you need to pass the `--compare-mode`
CLI flag: CLI flag:
```bash ```bash
./x.py test tests/ui --compare-mode=chalk ./x test tests/ui --compare-mode=chalk
``` ```
The possible compare modes are: The possible compare modes are:
@ -537,5 +536,5 @@ following settings:
enabling split-DWARF. enabling split-DWARF.
Note that compare modes are separate to [revisions](#revisions). Note that compare modes are separate to [revisions](#revisions).
All revisions are tested when running `./x.py test tests/ui`, however All revisions are tested when running `./x test tests/ui`, however
compare-modes must be manually run individually via the `--compare-mode` flag. compare-modes must be manually run individually via the `--compare-mode` flag.

2
src/tests/docker.md
View File

@ -21,7 +21,7 @@ directory. From there, you can run `../src/ci/run.sh` which will run the build
as defined by the image. as defined by the image.
Alternatively, you can run individual commands to do specific tasks. For Alternatively, you can run individual commands to do specific tasks. For
example, you can run `python3 ../x.py test tests/ui` to just run UI tests. example, you can run `../x test tests/ui` to just run UI tests.
Note that there is some configuration in the [`src/ci/run.sh`] script that you Note that there is some configuration in the [`src/ci/run.sh`] script that you
may need to recreate. Particularly, set `submodules = false` in your may need to recreate. Particularly, set `submodules = false` in your
`config.toml` so that it doesn't attempt to modify the read-only directory. `config.toml` so that it doesn't attempt to modify the read-only directory.

46
src/tests/intro.md
View File

@ -3,14 +3,14 @@
<!-- toc --> <!-- toc -->
The Rust project runs a wide variety of different tests, orchestrated by The Rust project runs a wide variety of different tests, orchestrated by
the build system (`./x.py test`). the build system (`./x test`).
This section gives a brief overview of the different testing tools. This section gives a brief overview of the different testing tools.
Subsequent chapters dive into [running tests](running.md) and [adding new tests](adding.md). Subsequent chapters dive into [running tests](running.md) and [adding new tests](adding.md).
## Kinds of tests ## Kinds of tests
There are several kinds of tests to exercise things in the Rust distribution. There are several kinds of tests to exercise things in the Rust distribution.
Almost all of them are driven by `./x.py test`, with some exceptions noted below. Almost all of them are driven by `./x test`, with some exceptions noted below.
### Compiletest ### Compiletest
@ -19,7 +19,7 @@ It supports running different styles of tests, called *test suites*.
The tests are all located in the [`tests`] directory. The tests are all located in the [`tests`] directory.
The [Compiletest chapter][compiletest] goes into detail on how to use this tool. The [Compiletest chapter][compiletest] goes into detail on how to use this tool.
> Example: `./x.py test tests/ui` > Example: `./x test tests/ui`
[compiletest]: compiletest.md [compiletest]: compiletest.md
[`tests`]: https://github.com/rust-lang/rust/tree/master/tests [`tests`]: https://github.com/rust-lang/rust/tree/master/tests
@ -33,11 +33,11 @@ and `x.py` will essentially run `cargo test` on that package.
Examples: Examples:
| Command | Description | | Command | Description |
|---------|-------------| | ----------------------------------------- | ------------------------------------- |
| `./x.py test library/std` | Runs tests on `std` only | | `./x test library/std` | Runs tests on `std` only |
| `./x.py test library/core` | Runs tests on `core` only | | `./x test library/core` | Runs tests on `core` only |
| `./x.py test compiler/rustc_data_structures` | Runs tests on `rustc_data_structures` | | `./x test compiler/rustc_data_structures` | Runs tests on `rustc_data_structures` |
The standard library relies very heavily on documentation tests to cover its functionality. The standard library relies very heavily on documentation tests to cover its functionality.
However, unit tests and integration tests can also be used as needed. However, unit tests and integration tests can also be used as needed.
@ -58,7 +58,7 @@ then changing or adding a test would cause the crate you are working on to be re
If you were working on something like `core`, If you were working on something like `core`,
then that would require recompiling the entire standard library, and the entirety of `rustc`. then that would require recompiling the entire standard library, and the entirety of `rustc`.
`./x.py test` includes some CLI options for controlling the behavior with these tests: `./x test` includes some CLI options for controlling the behavior with these tests:
* `--doc` — Only runs documentation tests in the package. * `--doc` — Only runs documentation tests in the package.
* `--no-doc` — Run all tests *except* documentation tests. * `--no-doc` — Run all tests *except* documentation tests.
@ -71,7 +71,7 @@ Tidy is a custom tool used for validating source code style and formatting conve
such as rejecting long lines. such as rejecting long lines.
There is more information in the [section on coding conventions](../conventions.md#formatting). There is more information in the [section on coding conventions](../conventions.md#formatting).
> Example: `./x.py test tidy` > Example: `./x test tidy`
### Formatting ### Formatting
@ -80,28 +80,28 @@ The formatting check is automatically run by the Tidy tool mentioned above.
Examples: Examples:
| Command | Description | | Command | Description |
|---------|-------------| | ----------------------- | ------------------------------------------------------------------ |
| `./x.py fmt --check` | Checks formatting and exits with an error if formatting is needed. | | `./x fmt --check` | Checks formatting and exits with an error if formatting is needed. |
| `./x.py fmt` | Runs rustfmt across the entire codebase. | | `./x fmt` | Runs rustfmt across the entire codebase. |
| `./x.py test tidy --bless` | First runs rustfmt to format the codebase, then runs tidy checks. | | `./x test tidy --bless` | First runs rustfmt to format the codebase, then runs tidy checks. |
### Book documentation tests ### Book documentation tests
All of the books that are published have their own tests, All of the books that are published have their own tests,
primarily for validating that the Rust code examples pass. primarily for validating that the Rust code examples pass.
Under the hood, these are essentially using `rustdoc --test` on the markdown files. Under the hood, these are essentially using `rustdoc --test` on the markdown files.
The tests can be run by passing a path to a book to `./x.py test`. The tests can be run by passing a path to a book to `./x test`.
> Example: `./x.py test src/doc/book` > Example: `./x test src/doc/book`
### Documentation link checker ### Documentation link checker
Links across all documentation is validated with a link checker tool. Links across all documentation is validated with a link checker tool.
> Example: `./x.py test src/tools/linkchecker` > Example: `./x test src/tools/linkchecker`
> Example: `./x.py test linkchecker` > Example: `./x test linkchecker`
This requires building all of the documentation, which might take a while. This requires building all of the documentation, which might take a while.
@ -110,7 +110,7 @@ This requires building all of the documentation, which might take a while.
`distcheck` verifies that the source distribution tarball created by the build system `distcheck` verifies that the source distribution tarball created by the build system
will unpack, build, and run all tests. will unpack, build, and run all tests.
> Example: `./x.py test distcheck` > Example: `./x test distcheck`
### Tool tests ### Tool tests
@ -119,9 +119,9 @@ This includes things such as cargo, clippy, rustfmt, miri, bootstrap
(testing the Rust build system itself), etc. (testing the Rust build system itself), etc.
Most of the tools are located in the [`src/tools`] directory. Most of the tools are located in the [`src/tools`] directory.
To run the tool's tests, just pass its path to `./x.py test`. To run the tool's tests, just pass its path to `./x test`.
> Example: `./x.py test src/tools/cargo` > Example: `./x test src/tools/cargo`
Usually these tools involve running `cargo test` within the tool's directory. Usually these tools involve running `cargo test` within the tool's directory.
@ -139,7 +139,7 @@ More information can be found in the [toolstate documentation].
(such as `servo`, `ripgrep`, `tokei`, etc.). (such as `servo`, `ripgrep`, `tokei`, etc.).
This ensures there aren't any significant regressions. This ensures there aren't any significant regressions.
> Example: `./x.py test src/tools/cargotest` > Example: `./x test src/tools/cargotest`
### Crater ### Crater

38
src/tests/running.md
View File

@ -6,7 +6,7 @@ You can run the tests using `x.py`. The most basic command – which
you will almost never want to use! – is as follows: you will almost never want to use! – is as follows:
```bash ```bash
./x.py test ./x test
``` ```
This will build the stage 1 compiler and then run the whole test This will build the stage 1 compiler and then run the whole test
@ -37,7 +37,7 @@ modifying rustc to see if things are generally working correctly would be the
following: following:
```bash ```bash
./x.py test tests/ui ./x test tests/ui
``` ```
This will run the `ui` test suite. Of course, the choice This will run the `ui` test suite. Of course, the choice
@ -46,32 +46,32 @@ doing. For example, if you are hacking on debuginfo, you may be better off
with the debuginfo test suite: with the debuginfo test suite:
```bash ```bash
./x.py test tests/debuginfo ./x test tests/debuginfo
``` ```
If you only need to test a specific subdirectory of tests for any 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`: given test suite, you can pass that directory to `./x test`:
```bash ```bash
./x.py test tests/ui/const-generics ./x test tests/ui/const-generics
``` ```
Likewise, you can test a single file by passing its path: Likewise, you can test a single file by passing its path:
```bash ```bash
./x.py test tests/ui/const-generics/const-test.rs ./x test tests/ui/const-generics/const-test.rs
``` ```
### Run only the tidy script ### Run only the tidy script
```bash ```bash
./x.py test tidy ./x test tidy
``` ```
### Run tests on the standard library ### Run tests on the standard library
```bash ```bash
./x.py test --stage 0 library/std ./x test --stage 0 library/std
``` ```
Note that this only runs tests on `std`; if you want to test `core` or other crates, Note that this only runs tests on `std`; if you want to test `core` or other crates,
@ -80,13 +80,13 @@ you have to specify those explicitly.
### Run the tidy script and tests on the standard library ### Run the tidy script and tests on the standard library
```bash ```bash
./x.py test --stage 0 tidy library/std ./x test --stage 0 tidy library/std
``` ```
### Run tests on the standard library using a stage 1 compiler ### Run tests on the standard library using a stage 1 compiler
```bash ```bash
./x.py test --stage 1 library/std ./x test --stage 1 library/std
``` ```
By listing which test suites you want to run you avoid having to run By listing which test suites you want to run you avoid having to run
@ -99,7 +99,7 @@ there are some limitations.
### Run all tests using a stage 2 compiler ### Run all tests using a stage 2 compiler
```bash ```bash
./x.py test --stage 2 ./x test --stage 2
``` ```
You almost never need to do this; CI will run these tests for you. You almost never need to do this; CI will run these tests for you.
@ -108,13 +108,13 @@ You almost never need to do this; CI will run these tests for you.
You may want to run unit tests on a specific file with following: You may want to run unit tests on a specific file with following:
```bash ```bash
./x.py test compiler/rustc_data_structures/src/thin_vec/tests.rs ./x test compiler/rustc_data_structures/src/thin_vec/tests.rs
``` ```
But unfortunately, it's impossible. You should invoke following instead: But unfortunately, it's impossible. You should invoke following instead:
```bash ```bash
./x.py test compiler/rustc_data_structures/ --test-args thin_vec ./x test compiler/rustc_data_structures/ --test-args thin_vec
``` ```
## Running an individual test ## Running an individual test
@ -125,7 +125,7 @@ you may pass the full file path to achieve this, or alternatively one
may invoke `x.py` with the `--test-args` option: may invoke `x.py` with the `--test-args` option:
```bash ```bash
./x.py test tests/ui --test-args issue-1234 ./x test tests/ui --test-args issue-1234
``` ```
Under the hood, the test runner invokes the standard Rust test runner Under the hood, the test runner invokes the standard Rust test runner
@ -140,7 +140,7 @@ making a new test, you can pass `--bless` to the test subcommand. E.g.
if some tests in `tests/ui` are failing, you can run if some tests in `tests/ui` are failing, you can run
```text ```text
./x.py test tests/ui --bless ./x test tests/ui --bless
``` ```
to automatically adjust the `.stderr`, `.stdout` or `.fixed` files of to automatically adjust the `.stderr`, `.stdout` or `.fixed` files of
@ -168,7 +168,7 @@ exists in the test file. For example, you can run all the tests in
`tests/ui` as `check-pass`: `tests/ui` as `check-pass`:
```bash ```bash
./x.py test tests/ui --pass check ./x test tests/ui --pass check
``` ```
By passing `--pass $mode`, you can reduce the testing time. For each By passing `--pass $mode`, you can reduce the testing time. For each
@ -184,7 +184,7 @@ mode, a test `foo.rs` will first look for expected output in
The following will run the UI test suite in Polonius mode: The following will run the UI test suite in Polonius mode:
```bash ```bash
./x.py test tests/ui --compare-mode=polonius ./x test tests/ui --compare-mode=polonius
``` ```
See [Compare modes](compiletest.md#compare-modes) for more details. See [Compare modes](compiletest.md#compare-modes) for more details.
@ -217,7 +217,7 @@ execution* so be careful where it is used.
To do this, first build `remote-test-server` for the remote To do this, first build `remote-test-server` for the remote
machine, e.g. for RISC-V machine, e.g. for RISC-V
```sh ```sh
./x.py build src/tools/remote-test-server --target riscv64gc-unknown-linux-gnu ./x build src/tools/remote-test-server --target riscv64gc-unknown-linux-gnu
``` ```
The binary will be created at The binary will be created at
@ -251,7 +251,7 @@ variable then use `x.py` as usual. For example, to run `ui` tests for a RISC-V
machine with the IP address `1.2.3.4` use machine with the IP address `1.2.3.4` use
```sh ```sh
export TEST_DEVICE_ADDR="1.2.3.4:12345" export TEST_DEVICE_ADDR="1.2.3.4:12345"
./x.py test tests/ui --target riscv64gc-unknown-linux-gnu ./x test tests/ui --target riscv64gc-unknown-linux-gnu
``` ```
If `remote-test-server` was run with the verbose flag, output on the test machine If `remote-test-server` was run with the verbose flag, output on the test machine

4
src/tests/ui.md
View File

@ -390,7 +390,7 @@ Tests with the `*-pass` headers can be overridden with the `--pass`
command-line option: command-line option:
```sh ```sh
./x.py test tests/ui --pass check ./x test tests/ui --pass check
``` ```
The `--pass` option only affects UI tests. The `--pass` option only affects UI tests.
@ -515,7 +515,7 @@ If in the rare case you encounter a test that has different behavior, you can
run something like the following to generate the alternate stderr file: run something like the following to generate the alternate stderr file:
```sh ```sh
./x.py test tests/ui --compare-mode=polonius --bless ./x test tests/ui --compare-mode=polonius --bless
``` ```
Currently none of the compare modes are checked in CI for UI tests. Currently none of the compare modes are checked in CI for UI tests.