diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-17 12:19:13 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-17 12:19:13 +0000 |
| commit | 218caa410aa38c29984be31a5229b9fa717560ee (patch) | |
| tree | c54bd55eeb6e4c508940a30e94c0032fbd45d677 /src/doc/rustc-dev-guide | |
| parent | Releasing progress-linux version 1.67.1+dfsg1-1~progress7.99u1. (diff) | |
| download | rustc-218caa410aa38c29984be31a5229b9fa717560ee.tar.xz rustc-218caa410aa38c29984be31a5229b9fa717560ee.zip | |
Merging upstream version 1.68.2+dfsg1.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'src/doc/rustc-dev-guide')
50 files changed, 374 insertions, 346 deletions
diff --git a/src/doc/rustc-dev-guide/.github/workflows/date-check.yml b/src/doc/rustc-dev-guide/.github/workflows/date-check.yml index c34c11c1e..bf2a7a819 100644 --- a/src/doc/rustc-dev-guide/.github/workflows/date-check.yml +++ b/src/doc/rustc-dev-guide/.github/workflows/date-check.yml @@ -27,9 +27,8 @@ jobs: cargo run -- ../../src/ > ../../date-check-output.txt - name: Open issue - uses: actions/github-script@v3 + uses: actions/github-script@v6 with: - github-token: ${{secrets.GITHUB_TOKEN}} script: | const fs = require('fs'); @@ -37,7 +36,7 @@ jobs: const title = rawText.split('\n')[0]; if (title != 'empty') { const body = rawText.split('\n').slice(1).join('\n'); - github.issues.create({ + github.rest.issues.create({ owner: context.repo.owner, repo: context.repo.repo, title, diff --git a/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs b/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs index 4203fe96a..8d8b40cd7 100644 --- a/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs +++ b/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs @@ -3,7 +3,7 @@ // NOTE: For the example to compile, you will need to first run the following: // rustup component add rustc-dev llvm-tools-preview -// version: 1.62.0-nightly (7c4b47696 2022-04-30) +// version: rustc 1.68.0-nightly (935dc0721 2022-12-19) extern crate rustc_error_codes; extern crate rustc_errors; @@ -50,7 +50,6 @@ fn main() { output_dir: None, // Option<PathBuf> output_file: None, // Option<PathBuf> file_loader: None, // Option<Box<dyn FileLoader + Send + Sync>> - diagnostic_output: rustc_session::DiagnosticOutput::Default, lint_caps: FxHashMap::default(), // FxHashMap<lint::LintId, lint::Level> // This is a callback from the driver that is called when [`ParseSess`] is created. parse_sess_created: None, //Option<Box<dyn FnOnce(&mut ParseSess) + Send>> diff --git a/src/doc/rustc-dev-guide/examples/rustc-driver-getting-diagnostics.rs b/src/doc/rustc-dev-guide/examples/rustc-driver-getting-diagnostics.rs index 1d3a4034e..49ee9ff44 100644 --- a/src/doc/rustc-dev-guide/examples/rustc-driver-getting-diagnostics.rs +++ b/src/doc/rustc-dev-guide/examples/rustc-driver-getting-diagnostics.rs @@ -3,7 +3,7 @@ // NOTE: For the example to compile, you will need to first run the following: // rustup component add rustc-dev llvm-tools-preview -// version: 1.62.0-nightly (7c4b47696 2022-04-30) +// version: rustc 1.68.0-nightly (935dc0721 2022-12-19) extern crate rustc_error_codes; extern crate rustc_errors; @@ -65,10 +65,6 @@ fn main() { " .into(), }, - // Redirect the diagnostic output of the compiler to a buffer. - diagnostic_output: rustc_session::DiagnosticOutput::Raw(Box::from(DiagnosticSink( - buffer.clone(), - ))), crate_cfg: rustc_hash::FxHashSet::default(), crate_check_cfg: CheckCfg::default(), input_path: None, diff --git a/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs b/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs index 231994a97..07b09e9df 100644 --- a/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs +++ b/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs @@ -3,7 +3,7 @@ // NOTE: For the example to compile, you will need to first run the following: // rustup component add rustc-dev llvm-tools-preview -// version: 1.62.0-nightly (7c4b47696 2022-04-30) +// version: rustc 1.68.0-nightly (935dc0721 2022-12-19) extern crate rustc_ast_pretty; extern crate rustc_error_codes; @@ -43,7 +43,6 @@ fn main() { "# .to_string(), }, - diagnostic_output: rustc_session::DiagnosticOutput::Default, crate_cfg: rustc_hash::FxHashSet::default(), crate_check_cfg: CheckCfg::default(), input_path: None, diff --git a/src/doc/rustc-dev-guide/src/appendix/background.md b/src/doc/rustc-dev-guide/src/appendix/background.md index ae6136dd5..0b83b010f 100644 --- a/src/doc/rustc-dev-guide/src/appendix/background.md +++ b/src/doc/rustc-dev-guide/src/appendix/background.md @@ -328,5 +328,5 @@ does not. - [nLab](https://ncatlab.org/nlab/show/HomePage) ## Misc Papers and Blog Posts -- [Programming in Martin-Löf's Type Theory](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.118.6683&rep=rep1&type=pdf) +- [Programming in Martin-Löf's Type Theory](https://www.researchgate.net/publication/213877272_Programming_in_Martin-Lof's_Type_Theory) - [Polymorphism, Subtyping, and Type Inference in MLsub](https://dl.acm.org/doi/10.1145/3093333.3009882) diff --git a/src/doc/rustc-dev-guide/src/appendix/bibliography.md b/src/doc/rustc-dev-guide/src/appendix/bibliography.md index 27529314c..c2bb00e3b 100644 --- a/src/doc/rustc-dev-guide/src/appendix/bibliography.md +++ b/src/doc/rustc-dev-guide/src/appendix/bibliography.md @@ -23,7 +23,7 @@ Rust, as well as publications about Rust. * [Scheduling multithreaded computations by work stealing](http://supertech.csail.mit.edu/papers/steal.pdf) * [Thread scheduling for multiprogramming multiprocessors](https://www.eecis.udel.edu/%7Ecavazos/cisc879-spring2008/papers/arora98thread.pdf) * [The data locality of work stealing](http://www.aladdin.cs.cmu.edu/papers/pdfs/y2000/locality_spaa00.pdf) -* [Dynamic circular work stealing deque](https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.170.1097&rep=rep1&type=pdf) - The Chase/Lev deque +* [Dynamic circular work stealing deque](https://patents.google.com/patent/US7346753B2/en) - The Chase/Lev deque * [Work-first and help-first scheduling policies for async-finish task parallelism](https://dl.acm.org/doi/10.1109/IPDPS.2009.5161079) - More general than fully-strict work stealing * [A Java fork/join calamity](https://web.archive.org/web/20190904045322/http://www.coopsoft.com/ar/CalamityArticle.html) - critique of Java's fork/join library, particularly its application of work stealing to non-strict computation * [Scheduling techniques for concurrent systems](https://www.stanford.edu/~ouster/cgi-bin/papers/coscheduling.pdf) @@ -81,7 +81,7 @@ Rust, as well as publications about Rust. * [Ownership is Theft: Experiences Building an Embedded OS in Rust - Amit Levy, et. al.](https://amitlevy.com/papers/tock-plos2015.pdf) * [You can't spell trust without Rust](https://raw.githubusercontent.com/Gankro/thesis/master/thesis.pdf). Alexis Beingessner's master's thesis. * [Rust-Bio: a fast and safe bioinformatics library](https://academic.oup.com/bioinformatics/article/32/3/444/1743419). Johannes Köster -* [Safe, Correct, and Fast Low-Level Networking](https://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.704.1768). Robert Clipsham's master's thesis. +* [Safe, Correct, and Fast Low-Level Networking](https://octarineparrot.com/assets/msci_paper.pdf). Robert Clipsham's master's thesis. * [Formalizing Rust traits](https://open.library.ubc.ca/cIRcle/collections/ubctheses/24/items/1.0220521). Jonatan Milewski's master's thesis. * [Rust as a Language for High Performance GC Implementation](https://users.cecs.anu.edu.au/~steveb/downloads/pdf/rust-ismm-2016.pdf) * [Simple Verification of Rust Programs via Functional Purification](https://github.com/Kha/electrolysis). Sebastian Ullrich's master's thesis. diff --git a/src/doc/rustc-dev-guide/src/appendix/humorust.md b/src/doc/rustc-dev-guide/src/appendix/humorust.md index bc8255439..1b199d98a 100644 --- a/src/doc/rustc-dev-guide/src/appendix/humorust.md +++ b/src/doc/rustc-dev-guide/src/appendix/humorust.md @@ -3,7 +3,7 @@ What's a project without a sense of humor? And frankly some of these are enlightening? -- [Weird exprs test](https://github.com/rust-lang/rust/blob/master/src/test/ui/weird-exprs.rs) +- [Weird exprs test](https://github.com/rust-lang/rust/blob/master/tests/ui/weird-exprs.rs) - [Ferris Rap](http://fitzgeraldnick.com/2018/12/13/rust-raps.html) - [The Genesis of Generic Germination](https://github.com/rust-lang/rust/pull/53645#issue-210543221) - [The Bastion of the Turbofish test](https://github.com/rust-lang/rust/blob/79d8a0fcefa5134db2a94739b1d18daa01fc6e9f/src/test/ui/bastion-of-the-turbofish.rs) diff --git a/src/doc/rustc-dev-guide/src/asm.md b/src/doc/rustc-dev-guide/src/asm.md index 9b5a82f34..3b6b5e093 100644 --- a/src/doc/rustc-dev-guide/src/asm.md +++ b/src/doc/rustc-dev-guide/src/asm.md @@ -361,9 +361,9 @@ can't know ahead of time whether a function will require a frame/base pointer. Various tests for inline assembly are available: -- `src/test/assembly/asm` -- `src/test/ui/asm` -- `src/test/codegen/asm-*` +- `tests/assembly/asm` +- `tests/ui/asm` +- `tests/codegen/asm-*` Every architecture supported by inline assembly must have exhaustive tests in -`src/test/assembly/asm` which test all combinations of register classes and types. +`tests/assembly/asm` which test all combinations of register classes and types. diff --git a/src/doc/rustc-dev-guide/src/backend/monomorph.md b/src/doc/rustc-dev-guide/src/backend/monomorph.md index 21a788203..4a0b55f62 100644 --- a/src/doc/rustc-dev-guide/src/backend/monomorph.md +++ b/src/doc/rustc-dev-guide/src/backend/monomorph.md @@ -10,7 +10,7 @@ execute. Different languages handle this problem differently. For example, in some languages, such as Java, we may not know the most precise type of value until runtime. In the case of Java, this is ok because (almost) all variables are -reference values anyway (i.e. pointers to a stack allocated object). This +reference values anyway (i.e. pointers to a heap allocated object). This flexibility comes at the cost of performance, since all accesses to an object must dereference a pointer. diff --git a/src/doc/rustc-dev-guide/src/borrow_check.md b/src/doc/rustc-dev-guide/src/borrow_check.md index 8e2bb752a..f206da42a 100644 --- a/src/doc/rustc-dev-guide/src/borrow_check.md +++ b/src/doc/rustc-dev-guide/src/borrow_check.md @@ -27,7 +27,7 @@ HIR. Doing borrow checking on MIR has several advantages: ### Major phases of the borrow checker The borrow checker source is found in -[the `rustc_borrow_ck` crate][b_c]. The main entry point is +[the `rustc_borrowck` crate][b_c]. The main entry point is the [`mir_borrowck`] query. [b_c]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_borrowck/index.html diff --git a/src/doc/rustc-dev-guide/src/building/bootstrapping.md b/src/doc/rustc-dev-guide/src/building/bootstrapping.md index 3bacc21d3..543c68c2e 100644 --- a/src/doc/rustc-dev-guide/src/building/bootstrapping.md +++ b/src/doc/rustc-dev-guide/src/building/bootstrapping.md @@ -28,7 +28,7 @@ stage0 compiler, and <span style="background-color: lightgreen; color: black">green</span> nodes are built with the stage1 compiler. -[rustconf22-talk]: https://rustconf.com/schedule#bootstrapping-the-once-and-future-compiler +[rustconf22-talk]: https://www.youtube.com/watch?v=oUIjG-y4zaA ```mermaid graph TD @@ -193,14 +193,14 @@ Build artifacts include, but are not limited to: 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 test command you want. -- `./x.py test src/test/ui` means to build the stage 1 compiler and run +- `./x.py 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 test command you want. #### Examples of what *not* to do -- `./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` +- `./x.py 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` instead, which builds stage 1 from source. - `./x.py test --stage 0 compiler/rustc` builds the compiler but runs no tests: it's running `cargo test -p rustc`, but cargo doesn't understand Rust's @@ -386,7 +386,7 @@ recompiling all dependencies. `CARGOFLAGS` will pass arguments to cargo itself (e.g. `--timings`). `CARGOFLAGS_BOOTSTRAP` and `CARGOFLAGS_NOT_BOOTSTRAP` work analogously to `RUSTFLAGS_BOOTSTRAP`. -`--test-args` will pass arguments through to the test runner. For `src/test/ui`, this is +`--test-args` will pass arguments through to the test runner. For `tests/ui`, this is compiletest; for unit tests and doctests this is the `libtest` runner. Most test runner accept `--help`, which you can use to find out the options accepted by the runner. 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 46d4b9c04..24786c0c0 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 @@ -4,7 +4,7 @@ The compiler is built using a tool called `x.py`. You will need to have Python installed to run it. For instructions on how to install Python and other prerequisites, -see [the next page](./prerequisites.md). +see [the `rust-lang/rust` README][readme]. ## Get the source code @@ -13,6 +13,7 @@ the standard library (including `core`, `alloc`, `test`, `proc_macro`, etc), and a bunch of tools (e.g. `rustdoc`, the bootstrapping infrastructure, etc). [repo]: https://github.com/rust-lang/rust +[readme]: https://github.com/rust-lang/rust#building-on-a-unix-like-system The very first step to work on `rustc` is to clone the repository: @@ -21,67 +22,15 @@ git clone https://github.com/rust-lang/rust.git cd rust ``` -There are also submodules for things like LLVM, `clippy`, `miri`, etc. The -build tool will automatically clone and sync these for you. But if you want to, -you can do the following: - -```sh -# first time -git submodule update --init --recursive - -# subsequent times (to pull new commits) -git submodule update -``` - -## Create a `config.toml` - -To start, run `./x.py setup`. This will do some initialization and create a -`config.toml` for you with reasonable defaults. These defaults are specified -indirectly via the `profile` setting, which points to one of the TOML files in -`src/bootstrap/defaults.` - -Alternatively, you can write `config.toml` by hand. See `config.toml.example` -for all the available settings and explanations of them. The following settings -are of particular interest, and `config.toml.example` has full explanations. - -You may want to change some of the following settings (and possibly others, such as -`llvm.ccache`): - -```toml -[llvm] -# Whether to use Rust CI built LLVM instead of locally building it. -download-ci-llvm = true # Download a pre-built LLVM? -assertions = true # LLVM assertions on? -ccache = "/path/to/ccache" # Use ccache when building LLVM? - -[rust] -debug-logging = true # Leave debug! and trace! calls in rustc? -incremental = true # Build rustc with incremental compilation? -``` - -If you set `download-ci-llvm = true`, in some circumstances, such as when -updating the version of LLVM used by `rustc`, you may want to temporarily -disable this feature. See the ["Updating LLVM" section] for more. - -["Updating LLVM" section]: ../backend/updating-llvm.md#feature-updates - -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 -clean` will not cause a rebuild of LLVM. - ## What is `x.py`? -`x.py` is the script used to orchestrate the tooling in the `rustc` repository. -It is the script that can build docs, run tests, and compile `rustc`. -It is the now preferred way to build `rustc` and it replaces the old makefiles -from before. Below are the different ways to utilize `x.py` in order to -effectively deal with the repo for various common tasks. +`x.py` is the build tool for the `rust` repository. It can build docs, run tests, and compile the +compiler and standard library. This chapter focuses on the basics to be productive, but -if you want to learn more about `x.py`, read its README.md -[here](https://github.com/rust-lang/rust/blob/master/src/bootstrap/README.md). -To read more about the bootstrap process and why `x.py` is necessary, -[read this chapter][bootstrap]. +if you want to learn more about `x.py`, [read this chapter][bootstrap]. + +[bootstrap]: ./bootstrapping.md ### Running `x.py` slightly more conveniently @@ -91,48 +40,26 @@ of a checkout. It also looks up the appropriate version of `python` to use. You can install it with `cargo install --path src/tools/x`. -[bootstrap]: ./bootstrapping.md - -## Building the Compiler +## Create a `config.toml` -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. +To start, run `./x.py setup`. This will do some initialization and create a +`config.toml` for you with reasonable defaults. -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. +Alternatively, you can write `config.toml` by hand. See `config.toml.example` for all the available +settings and explanations of them. See `src/bootstrap/defaults` for common settings to change. -There are many flags you can pass to the build command of `x.py` that can be -beneficial to cutting down compile times or fitting other things you might -need to change. They are: - -```txt -Options: - -v, --verbose use verbose output (-vv for very verbose) - -i, --incremental use incremental compilation - --config FILE TOML configuration file for build - --build BUILD build target of the stage0 compiler - --host HOST host targets to build - --target TARGET target targets to build - --on-fail CMD command to run on failure - --stage N stage to build - --keep-stage N stage to keep without recompiling - --src DIR path to the root of the Rust checkout - -j, --jobs JOBS number of jobs to run in parallel - -h, --help print this help message -``` +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 +clean` will not cause a rebuild of LLVM. -For hacking, often building the stage 1 compiler is enough, which saves a lot -of time. But for final testing and release, the stage 2 compiler is used. +## Building the Compiler -`./x.py check` is really fast to build the Rust compiler. -It is, in particular, very useful when you're doing some kind of -"type-based refactoring", like renaming a method, or changing the -signature of some function. +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. Once you've created a `config.toml`, you are now ready to run `x.py`. There are a lot of options here, but let's start with what is -probably the best "go to" command for building a local rust: +probably the best "go to" command for building a local compiler: ```bash ./x.py build library @@ -156,6 +83,10 @@ see [the section on avoiding rebuilds for std][keep-stage]. [keep-stage]: ./suggested.md#faster-builds-with---keep-stage +Sometimes you don't need a full build. When doing some kind of +"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. + 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 --stage 2 compiler/rustc`) has quite a few more steps: @@ -177,6 +108,9 @@ Instead, you can just build using the bootstrap compiler. ./x.py build --stage 0 library ``` +If you choose the `library` profile when running `x.py setup`, you can omit `--stage 0` (it's the +default). + ## Creating a rustup toolchain Once you have successfully built `rustc`, you will have created a bunch @@ -285,14 +219,14 @@ in other sections: - `./x.py build` – builds everything using the stage 1 compiler, not just up to `std` - `./x.py build --stage 2` – builds everything with the stage 2 compiler including - `rustdoc` (which doesn't take too long) + `rustdoc` - Running tests (see the [section on running tests](../tests/running.html) for more details): - `./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 + - `./x.py test tests/ui` – runs the `ui` test suite + - `./x.py test tests/ui/const-generics` - runs all the tests in the `const-generics/` subdirectory of the `ui` test suite - - `./x.py test src/test/ui/const-generics/const-types.rs` - runs + - `./x.py test tests/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/prerequisites.md b/src/doc/rustc-dev-guide/src/building/prerequisites.md index 100b14aca..8fee0a4b5 100644 --- a/src/doc/rustc-dev-guide/src/building/prerequisites.md +++ b/src/doc/rustc-dev-guide/src/building/prerequisites.md @@ -2,48 +2,7 @@ ## Dependencies -Before building the compiler, you need the following things installed: - -* `python` 3 or 2.7 (under the name `python`; `python2` or `python3` will not work) -* `curl` -* `git` -* `ssl` which comes in `libssl-dev` or `openssl-devel` -* `pkg-config` if you are compiling on Linux and targeting Linux -* `libstdc++-static` may be required on some Linux distributions such as Fedora and Ubuntu - -If building LLVM from source (the default), you'll need additional tools: - -* `g++`, `clang++`, or MSVC with versions listed on <!-- date-check: Aug 2022 --> - [LLVM's documentation](https://releases.llvm.org/13.0.0/docs/GettingStarted.html#host-c-toolchain-both-compiler-and-standard-library) -* `ninja`, or GNU `make` 3.81 or later (ninja is recommended, especially on Windows) -* `cmake` 3.13.4 or later - -Otherwise, you'll need LLVM installed and `llvm-config` in your path. -See [this section for more info][sysllvm]. - -[sysllvm]: ./new-target.md#using-pre-built-llvm - -### Windows - -* Install [winget](https://github.com/microsoft/winget-cli) - -`winget` is a Windows package manager. It will make package installation easy -on Windows. - -Run the following in a terminal: - -```powershell -winget install -e Python.Python.3 -winget install -e Kitware.CMake -``` - -If any of those is installed already, winget will detect it. Then edit your system's `PATH` variable -and add: `C:\Program Files\CMake\bin`. See -[this guide on editing the system `PATH`](https://www.java.com/en/download/help/path.html) from the -Java documentation. - -For more information about building on Windows, -see [the `rust-lang/rust` README](https://github.com/rust-lang/rust#building-on-windows). +See [the `rust-lang/rust` README](https://github.com/rust-lang/rust#dependencies). ## Hardware @@ -65,8 +24,8 @@ powerful, a common strategy is to only use `./x.py check` on your local machine 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 -laptop. The first time you build the compiler, LLVM will also be built unless -you use CI-built LLVM ([see here][config]). +laptop. We suggest downloading LLVM from CI so you don't have to build it from source +([see here][config]). Like `cargo`, the build system will use as many cores as possible. Sometimes this can cause you to run low on memory. You can use `-j` to adjust the number @@ -80,10 +39,3 @@ longer (especially after a rebase), but will save a ton of space from the incremental caches. [config]: ./how-to-build-and-run.md#create-a-configtoml - -## `rustc` and toolchain installation - -Follow the installation given in the [Rust book][install] to install a working -`rustc` and the necessary C/++ toolchain on your platform. - -[install]: https://doc.rust-lang.org/book/ch01-01-installation.html diff --git a/src/doc/rustc-dev-guide/src/building/suggested.md b/src/doc/rustc-dev-guide/src/building/suggested.md index a85229c6a..f81daa5bc 100644 --- a/src/doc/rustc-dev-guide/src/building/suggested.md +++ b/src/doc/rustc-dev-guide/src/building/suggested.md @@ -34,10 +34,10 @@ you can write: <!-- date-check: nov 2022 --><!-- the date comment is for the edi "--json-output" ], "rust-analyzer.rustfmt.overrideCommand": [ - "./build/$TARGET_TRIPLE/stage0/bin/rustfmt", + "./build/host/stage0/bin/rustfmt", "--edition=2021" ], - "rust-analyzer.procMacro.server": "./build/$TARGET_TRIPLE/stage0/libexec/rust-analyzer-proc-macro-srv", + "rust-analyzer.procMacro.server": "./build/host/stage0/libexec/rust-analyzer-proc-macro-srv", "rust-analyzer.procMacro.enable": true, "rust-analyzer.cargo.buildScripts.enable": true, "rust-analyzer.cargo.buildScripts.invocationLocation": "root", @@ -48,7 +48,7 @@ you can write: <!-- date-check: nov 2022 --><!-- the date comment is for the edi "check", "--json-output" ], - "rust-analyzer.cargo.sysroot": "./build/$TARGET_TRIPLE/stage0-sysroot", + "rust-analyzer.cargo.sysroot": "./build/host/stage0-sysroot", "rust-analyzer.rustc.source": "./Cargo.toml", } ``` @@ -56,11 +56,6 @@ you can write: <!-- date-check: nov 2022 --><!-- the date comment is for the edi in your `.vscode/settings.json` file. This will ask `rust-analyzer` to use `./x.py check` to check the sources, and the stage 0 rustfmt to format them. -> NOTE: Make sure to replace `TARGET_TRIPLE` in the `rust-analyzer.rustfmt.overrideCommand` -> setting with the appropriate target triple for your machine. An example of such -> a triple is `x86_64-unknown-linux-gnu`. An easy way to check your target triple -> is to run `rustc -vV` and checking the `host` value of its output. - If you have enough free disk space and you would like to be able to run `x.py` commands while rust-analyzer runs in the background, you can also add `--build-dir build-rust-analyzer` to the `overrideCommand` to avoid x.py locking. @@ -177,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 src/test/ui` -- Subsequent test run: `./x.py test src/test/ui --keep-stage 1` +- Initial test run: `./x.py test tests/ui` +- Subsequent test run: `./x.py test tests/ui --keep-stage 1` ## Fine-tuning optimizations diff --git a/src/doc/rustc-dev-guide/src/compiler-debugging.md b/src/doc/rustc-dev-guide/src/compiler-debugging.md index 35458b55c..eac9aeb6d 100644 --- a/src/doc/rustc-dev-guide/src/compiler-debugging.md +++ b/src/doc/rustc-dev-guide/src/compiler-debugging.md @@ -128,7 +128,7 @@ fn main() { } ``` -```bash +``` $ rustc +stage1 error.rs error[E0277]: cannot add `()` to `{integer}` --> error.rs:2:7 @@ -143,7 +143,7 @@ error: aborting due to previous error Now, where does the error above come from? -```bash +``` $ RUST_BACKTRACE=1 rustc +stage1 error.rs -Z treat-err-as-bug error[E0277]: the trait bound `{integer}: std::ops::Add<()>` is not satisfied --> error.rs:2:7 @@ -185,6 +185,40 @@ stack backtrace: Cool, now I have a backtrace for the error! +## Getting the the error creation location + +`-Z track-diagnostics` can help figure out where errors are emitted. It uses `#[track_caller]` +for this and prints its location alongside the error: + +``` +$ RUST_BACKTRACE=1 rustc +stage1 error.rs -Z track-diagnostics +error[E0277]: cannot add `()` to `{integer}` + --> src\error.rs:2:7 + | +2 | 1 + (); + | ^ no implementation for `{integer} + ()` +-Ztrack-diagnostics: created at compiler/rustc_trait_selection/src/traits/error_reporting/mod.rs:638:39 + | + = help: the trait `Add<()>` is not implemented for `{integer}` + = help: the following other types implement trait `Add<Rhs>`: + <&'a f32 as Add<f32>> + <&'a f64 as Add<f64>> + <&'a i128 as Add<i128>> + <&'a i16 as Add<i16>> + <&'a i32 as Add<i32>> + <&'a i64 as Add<i64>> + <&'a i8 as Add<i8>> + <&'a isize as Add<isize>> + and 48 others + +For more information about this error, try `rustc --explain E0277`. +``` + +This is similar but different to `-Z treat-err-as-bug`: +- it will print the locations for all errors emitted +- it does not require a compiler built with debug symbols +- you don't have to read through a big stack trace. + ## Getting logging output The compiler uses the [`tracing`] crate for logging. diff --git a/src/doc/rustc-dev-guide/src/compiler-src.md b/src/doc/rustc-dev-guide/src/compiler-src.md index ad6968bb4..1f55a9d09 100644 --- a/src/doc/rustc-dev-guide/src/compiler-src.md +++ b/src/doc/rustc-dev-guide/src/compiler-src.md @@ -147,14 +147,14 @@ You can read more about rustdoc in [this chapter][rustdocch]. ## Tests -The test suite for all of the above is in [`src/test/`]. You can read more +The test suite for all of the above is in [`tests/`]. You can read more about the test suite [in this chapter][testsch]. The test harness itself is in [`src/tools/compiletest`]. [testsch]: ./tests/intro.md -[`src/test/`]: https://github.com/rust-lang/rust/tree/master/src/test +[`tests/`]: https://github.com/rust-lang/rust/tree/master/tests [`src/tools/compiletest`]: https://github.com/rust-lang/rust/tree/master/src/tools/compiletest ## Build System diff --git a/src/doc/rustc-dev-guide/src/contributing.md b/src/doc/rustc-dev-guide/src/contributing.md index 41ad1c915..bc39508a4 100644 --- a/src/doc/rustc-dev-guide/src/contributing.md +++ b/src/doc/rustc-dev-guide/src/contributing.md @@ -185,7 +185,7 @@ As a developer to this repository, you don't have to treat the following externa differently from other crates that are directly in this repo: * [Clippy](https://github.com/rust-lang/rust-clippy) -* [Miri](https://github.com/rust-lang/miri) +* [Miri] * [rustfmt](https://github.com/rust-lang/rustfmt) * [rust-analyzer](https://github.com/rust-lang/rust-analyzer) @@ -348,7 +348,7 @@ 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`. 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`. +Results should appear in `build/host/doc`. [docs]: https://doc.rust-lang.org @@ -549,3 +549,4 @@ are: [ro]: https://www.rustaceans.org/ [rctd]: tests/intro.md [cheatsheet]: https://bors.rust-lang.org/ +[Miri]: https://github.com/rust-lang/miri diff --git a/src/doc/rustc-dev-guide/src/diagnostics.md b/src/doc/rustc-dev-guide/src/diagnostics.md index e1d5fbe1a..b50b7bd18 100644 --- a/src/doc/rustc-dev-guide/src/diagnostics.md +++ b/src/doc/rustc-dev-guide/src/diagnostics.md @@ -269,7 +269,7 @@ book][rustc-lint-levels] and the [reference][reference-diagnostics]. ### Finding the source of errors -There are two main ways to find where a given error is emitted: +There are three main ways to find where a given error is emitted: - `grep` for either a sub-part of the error message/label or error code. This usually works well and is straightforward, but there are some cases where @@ -287,6 +287,8 @@ There are two main ways to find where a given error is emitted: - The _construction_ of the error is far away from where it is _emitted_, a problem similar to the one we faced with the `grep` approach. In some cases, we buffer multiple errors in order to emit them in order. +- Invoking `rustc` with `-Z track-diagnostics` will print error creation + locations alongside the error. The regular development practices apply: judicious use of `debug!()` statements and use of a debugger to trigger break points in order to figure out in what diff --git a/src/doc/rustc-dev-guide/src/git.md b/src/doc/rustc-dev-guide/src/git.md index 65397e349..cac3d6534 100644 --- a/src/doc/rustc-dev-guide/src/git.md +++ b/src/doc/rustc-dev-guide/src/git.md @@ -16,6 +16,10 @@ started sections of [this tutorial from Atlassian][atlassian-git]. GitHub also provides [documentation] and [guides] for beginners, or you can consult the more in depth [book from Git]. +This guide is incomplete. If you run into trouble with git that this page doesn't help with, +please [open an issue] so we can document how to fix it. + +[open an issue]: https://github.com/rust-lang/rustc-dev-guide/issues/new [book from Git]: https://git-scm.com/book/en/v2/ [atlassian-git]: https://www.atlassian.com/git/tutorials/what-is-version-control [documentation]: https://docs.github.com/en/get-started/quickstart/set-up-git @@ -58,7 +62,7 @@ and PRs: 1. Ensure that you're making your changes on top of master: `git checkout master`. 2. Get the latest changes from the Rust repo: `git pull upstream master --ff-only`. - (see [No-Merge Policy](#keeping-things-up-to-date) for more info about this). + (see [No-Merge Policy][no-merge-policy] for more info about this). 3. Make a new branch for your change: `git checkout -b issue-12345-fix`. 4. Make some changes to the repo and test them. 5. Stage your changes via `git add src/changed/file.rs src/another/change.rs` @@ -76,7 +80,7 @@ pulling-and-rebasing, you can use `git push --force-with-lease`). If you end up needing to rebase and are hitting conflicts, see [Rebasing](#rebasing). If you want to track upstream while working on long-running feature/issue, see -[Keeping things up to date](#keeping-things-up-to-date). +[Keeping things up to date][no-merge-policy]. If your reviewer requests changes, the procedure for those changes looks much the same, with some steps skipped: @@ -86,6 +90,8 @@ the same, with some steps skipped: 2. Make, stage, and commit your additional changes just like before. 3. Push those changes to your fork: `git push`. + [no-merge-policy]: #keeping-things-up-to-date + ## Troubleshooting git issues You don't need to clone `rust-lang/rust` from scratch if it's out of date! @@ -93,6 +99,14 @@ Even if you think you've messed it up beyond repair, there are ways to fix the git state that don't require downloading the whole repository again. Here are some common issues you might run into: +### I made a merge commit by accident. + +Git has two ways to update your branch with the newest changes: merging and rebasing. +Rust [uses rebasing][no-merge-policy]. If you make a merge commit, it's not too hard to fix: +`git rebase -i upstream/master`. + +See [Rebasing](#rebasing) for more about rebasing. + ### I deleted my fork on GitHub! This is not a problem from git's perspective. If you run `git remote -v`, @@ -100,20 +114,72 @@ it will say something like this: ``` $ git remote -v -origin https://github.com//rust-lang/rust (fetch) -origin https://github.com//rust-lang/rust (push) -personal https://github.com/jyn514/rust (fetch) -personal https://github.com/jyn514/rust (push) +origin git@github.com:jyn514/rust.git (fetch) +origin git@github.com:jyn514/rust.git (push) +upstream https://github.com/rust-lang/rust (fetch) +upstream https://github.com/rust-lang/rust (fetch) ``` If you renamed your fork, you can change the URL like this: ```console -git remote set-url personal <URL> +git remote set-url origin <URL> ``` where the `<URL>` is your new fork. +### I changed a submodule by accident + +Usually people notice this when rustbot posts a comment on github that `cargo` has been modified: + + + +You might also notice conflicts in the web UI: + + + +The most common cause is that you rebased after a change and ran `git add .` without first running +`x.py` to update the submodules. Alternatively, you might have run `cargo fmt` instead of `x fmt` +and modified files in a submodule, then committed the changes. + +To fix it, do the following things: + +1. See which commit has the accidental changes: `git log --stat -n1 src/tools/cargo` +2. Revert the changes to that commit: `git checkout <my-commit>~ src/tools/cargo`. Type `~` + literally but replace `<my-commit>` with the output from step 1. +3. Tell git to commit the changes: `git commit --fixup <my-commit>` +4. Repeat steps 1-3 for all the submodules you modified. + - If you modified the submodule in several different commits, you will need to repeat steps 1-3 + for each commit you modified. You'll know when to stop when the `git log` command shows a commit + that's not authored by you. +5. Squash your changes into the existing commits: `git rebase --autosquash -i upstream/master` +6. [Push your changes](#standard-process). + +### I see "error: cannot rebase" when I try to rebase + +These are two common errors to see when rebasing: +``` +error: cannot rebase: Your index contains uncommitted changes. +error: Please commit or stash them. +``` +``` +error: cannot rebase: You have unstaged changes. +error: Please commit or stash them. +``` + +(See https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_the_three_states for the difference between the two.) + +This means you have made changes since the last time you made a commit. To be able to rebase, either +commit your changes, or make a temporary commit called a "stash" to have them still not be commited +when you finish rebasing. You may want to configure git to make this "stash" automatically, which +will prevent the "cannot rebase" error in nearly all cases: + +``` +git config --global rebase.autostash true +``` + +See https://git-scm.com/book/en/v2/Git-Tools-Stashing-and-Cleaning for more info about stashing. + ### I see 'Untracked Files: src/stdarch'? This is left over from the move to the `library/` directory. @@ -135,6 +201,24 @@ and just want to get a clean copy of the repository back, you can use `git reset git reset --hard master ``` +### Git is trying to rebase commits I didn't write? + +If you see many commits in your rebase list, or merge commits, or commits by other people that you +didn't write, it likely means you're trying to rebase over the wrong branch. For example, you may +have a `rust-lang/rust` remote `upstream`, but ran `git rebase origin/master` instead of `git rebase +upstream/master`. The fix is to abort the rebase and use the correct branch instead: + +``` +git rebase --abort +git rebase -i upstream/master +``` + +<details><summary>Click here to see an example of rebasing over the wrong branch</summary> + + + +</details> + ### Quick note about submodules When updating your local repository with `git pull`, you may notice that sometimes @@ -269,9 +353,8 @@ and rebase them: ``` git checkout master git pull upstream master --ff-only # to make certain there are no merge commits -git checkout feature_branch -git rebase master -git push --force-with-lease (set origin to be the same as local) +git rebase master feature_branch +git push --force-with-lease # (set origin to be the same as local) ``` To avoid merges as per the [No-Merge Policy](#no-merge-policy), you may want to use @@ -279,7 +362,7 @@ To avoid merges as per the [No-Merge Policy](#no-merge-policy), you may want to to ensure that Git doesn't create merge commits when `git pull`ing, without needing to pass `--ff-only` or `--rebase` every time. -You can also `git push --force-with-lease` from master to keep your origin's master in sync with +You can also `git push --force-with-lease` from master to keep your fork's master in sync with upstream. ## Advanced Rebasing @@ -385,6 +468,44 @@ tradeoff. The main advantage is the generally linear commit history. This greatly simplifies bisecting and makes the history and commit log much easier to follow and understand. +## Tips for reviewing + +**NOTE**: This section is for *reviewing* PRs, not authoring them. + +### Hiding whitespace + +Github has a button for disabling whitespace changes that may be useful. +You can also use `git diff -w origin/master` to view changes locally. + + + +### Fetching PRs + +To checkout PRs locally, you can use `git fetch upstream pull/NNNNN/head && git checkout +FETCH_HEAD`. + +You can also use github's cli tool. Github shows a button on PRs where you can copy-paste the +command to check it out locally. See <https://cli.github.com/> for more info. + + + +### Moving large sections of code + +Git and Github's default diff view for large moves *within* a file is quite poor; it will show each +line as deleted and each line as added, forcing you to compare each line yourself. Git has an option +to show moved lines in a different color: + +``` +git log -p --color-moved=dimmed-zebra --color-moved-ws=allow-indentation-change +``` + +See [the docs for `--color-moved`](https://git-scm.com/docs/git-diff#Documentation/git-diff.txt---color-movedltmodegt) for more info. + +### range-diff + +See [the relevant section for PR authors](#git-range-diff). This can be useful for comparing code +that was force-pushed to make sure there are no unexpected changes. + ## Git submodules **NOTE**: submodules are a nice thing to know about, but it *isn't* an absolute diff --git a/src/doc/rustc-dev-guide/src/img/github-cli.png b/src/doc/rustc-dev-guide/src/img/github-cli.png Binary files differnew file mode 100644 index 000000000..c3b0e7707 --- /dev/null +++ b/src/doc/rustc-dev-guide/src/img/github-cli.png diff --git a/src/doc/rustc-dev-guide/src/img/github-whitespace-changes.png b/src/doc/rustc-dev-guide/src/img/github-whitespace-changes.png Binary files differnew file mode 100644 index 000000000..9a19a10aa --- /dev/null +++ b/src/doc/rustc-dev-guide/src/img/github-whitespace-changes.png diff --git a/src/doc/rustc-dev-guide/src/img/other-peoples-commits.png b/src/doc/rustc-dev-guide/src/img/other-peoples-commits.png Binary files differnew file mode 100644 index 000000000..e4fc2c797 --- /dev/null +++ b/src/doc/rustc-dev-guide/src/img/other-peoples-commits.png diff --git a/src/doc/rustc-dev-guide/src/img/rustbot-submodules.png b/src/doc/rustc-dev-guide/src/img/rustbot-submodules.png Binary files differnew file mode 100644 index 000000000..c2e6937cb --- /dev/null +++ b/src/doc/rustc-dev-guide/src/img/rustbot-submodules.png diff --git a/src/doc/rustc-dev-guide/src/img/submodule-conflicts.png b/src/doc/rustc-dev-guide/src/img/submodule-conflicts.png Binary files differnew file mode 100644 index 000000000..e90a6bbe8 --- /dev/null +++ b/src/doc/rustc-dev-guide/src/img/submodule-conflicts.png diff --git a/src/doc/rustc-dev-guide/src/incrcomp-debugging.md b/src/doc/rustc-dev-guide/src/incrcomp-debugging.md index ba312c959..3606943dd 100644 --- a/src/doc/rustc-dev-guide/src/incrcomp-debugging.md +++ b/src/doc/rustc-dev-guide/src/incrcomp-debugging.md @@ -6,7 +6,7 @@ There are various ways to write tests against the dependency graph. The simplest mechanisms are the `#[rustc_if_this_changed]` and `#[rustc_then_this_would_need]` annotations. These are used in ui tests to test whether the expected set of paths exist in the dependency graph. -As an example, see `src/test/ui/dep-graph/dep-graph-caller-callee.rs`. +As an example, see `tests/ui/dep-graph/dep-graph-caller-callee.rs`. The idea is that you can annotate a test like: diff --git a/src/doc/rustc-dev-guide/src/llvm-coverage-instrumentation.md b/src/doc/rustc-dev-guide/src/llvm-coverage-instrumentation.md index b186f4820..b29b32a62 100644 --- a/src/doc/rustc-dev-guide/src/llvm-coverage-instrumentation.md +++ b/src/doc/rustc-dev-guide/src/llvm-coverage-instrumentation.md @@ -297,15 +297,15 @@ Expected results for both the `mir-opt` tests and the `coverage*` tests under ```shell $ ./x.py test mir-opt --bless -$ ./x.py test src/test/run-make-fulldeps/coverage --bless +$ ./x.py test tests/run-make-fulldeps/coverage --bless ``` -[mir-opt-test]: https://github.com/rust-lang/rust/blob/master/src/test/mir-opt/instrument_coverage.rs -[coverage-test-samples]: https://github.com/rust-lang/rust/tree/master/src/test/run-make-fulldeps/coverage -[`coverage-reports`]: https://github.com/rust-lang/rust/tree/master/src/test/run-make-fulldeps/coverage-reports -[`coverage-spanview`]: https://github.com/rust-lang/rust/tree/master/src/test/run-make-fulldeps/coverage-spanview +[mir-opt-test]: https://github.com/rust-lang/rust/blob/master/tests/mir-opt/instrument_coverage.rs +[coverage-test-samples]: https://github.com/rust-lang/rust/tree/master/tests/run-make-fulldeps/coverage +[`coverage-reports`]: https://github.com/rust-lang/rust/tree/master/tests/run-make-fulldeps/coverage-reports +[`coverage-spanview`]: https://github.com/rust-lang/rust/tree/master/tests/run-make-fulldeps/coverage-spanview [spanview-debugging]: compiler-debugging.md#viewing-spanview-output -[`coverage-llvmir`]: https://github.com/rust-lang/rust/tree/master/src/test/run-make-fulldeps/coverage-llvmir +[`coverage-llvmir`]: https://github.com/rust-lang/rust/tree/master/tests/run-make-fulldeps/coverage-llvmir ## Implementation Details of the `InstrumentCoverage` MIR Pass diff --git a/src/doc/rustc-dev-guide/src/memory.md b/src/doc/rustc-dev-guide/src/memory.md index cde2f454c..e5122deb2 100644 --- a/src/doc/rustc-dev-guide/src/memory.md +++ b/src/doc/rustc-dev-guide/src/memory.md @@ -16,18 +16,19 @@ types for equality: for each interned type `X`, we implemented [`PartialEq for X`][peqimpl], so we can just compare pointers. The [`CtxtInterners`] type contains a bunch of maps of interned types and the arena itself. -[peqimpl]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyS.html#implementations +[peqimpl]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.Ty.html#implementations [`CtxtInterners`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.CtxtInterners.html#structfield.arena -### Example: `ty::TyS` +### Example: `ty::TyKind` -Taking the example of [`ty::TyS`] which represents a type in the compiler (you +Taking the example of [`ty::TyKind`] which represents a type in the compiler (you can read more [here](./ty.md)). Each time we want to construct a type, the compiler doesn’t naively allocate from the buffer. Instead, we check if that type was already constructed. If it was, we just get the same pointer we had before, otherwise we make a fresh pointer. With this schema if we want to know if two types are the same, all we need to do is compare the pointers which is -efficient. `TyS` is carefully setup so you never construct them on the stack. +efficient. `TyKind` should never be constructed on the stack, and it would be unusable +if done so. You always allocate them from this arena and you always intern them so they are unique. @@ -52,7 +53,7 @@ allocate, and which are found in this module. Here are a few examples: [`TraitRef`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TraitRef.html [`Predicate`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.Predicate.html -[`ty::TyS`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyS.html +[`ty::TyKind`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/sty/type.TyKind.html ## The tcx and how it uses lifetimes diff --git a/src/doc/rustc-dev-guide/src/mir/optimizations.md b/src/doc/rustc-dev-guide/src/mir/optimizations.md index cef785ea9..037cf5874 100644 --- a/src/doc/rustc-dev-guide/src/mir/optimizations.md +++ b/src/doc/rustc-dev-guide/src/mir/optimizations.md @@ -28,13 +28,13 @@ optimizes it, and returns the improved MIR. ## Quickstart for adding a new optimization -1. Make a Rust source file in `src/test/mir-opt` that shows the code you want to +1. Make a Rust source file in `tests/mir-opt` that shows the code you want to optimize. This should be kept simple, so avoid `println!` or other formatting code if it's not necessary for the optimization. The reason for this is that `println!`, `format!`, etc. generate a lot of MIR that can make it harder to understand what the optimization does to the test. -2. Run `./x.py test --bless src/test/mir-opt/<your-test>.rs` to generate a MIR +2. Run `./x.py 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 things. @@ -51,10 +51,10 @@ optimizes it, and returns the improved MIR. [`run_optimization_passes()`] function, 3. and then start modifying the copied optimization. -5. Rerun `./x.py test --bless src/test/mir-opt/<your-test>.rs` to regenerate the +5. Rerun `./x.py 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. -6. Run `./x.py test src/test/ui` to see if your optimization broke anything. +6. Run `./x.py test tests/ui` to see if your optimization broke anything. 7. If there are issues with your optimization, experiment with it a bit and repeat steps 5 and 6. @@ -70,7 +70,7 @@ optimizes it, and returns the improved MIR. If you have any questions along the way, feel free to ask in `#t-compiler/wg-mir-opt` on Zulip. -[mir-opt-test-readme]: https://github.com/rust-lang/rust/blob/master/src/test/mir-opt/README.md +[mir-opt-test-readme]: https://github.com/rust-lang/rust/blob/master/tests/mir-opt/README.md [`compiler/rustc_mir_transform/src`]: https://github.com/rust-lang/rust/tree/master/compiler/rustc_mir_transform/src <!--- TODO: Change NoLandingPads. [#1232](https://github.com/rust-lang/rustc-dev-guide/issues/1232) --> [`no_landing_pads`]: https://github.com/rust-lang/rust/blob/master/compiler/rustc_mir_transform/src/no_landing_pads.rs diff --git a/src/doc/rustc-dev-guide/src/mir/passes.md b/src/doc/rustc-dev-guide/src/mir/passes.md index 5528b7762..4c7feb04e 100644 --- a/src/doc/rustc-dev-guide/src/mir/passes.md +++ b/src/doc/rustc-dev-guide/src/mir/passes.md @@ -33,9 +33,8 @@ basically consists of one method, `run_pass`, that simply gets an came from). The MIR is therefore modified in place (which helps to keep things efficient). -A good example of a basic MIR pass is [`NoLandingPads`], which walks -the MIR and removes all edges that are due to unwinding – this is -used when configured with `panic=abort`, which never unwinds. As you +A basic example of a MIR pass is [`RemoveStorageMarkers`], which walks +the MIR and removes all storage marks if they won't be emitted during codegen. As you can see from its source, a MIR pass is defined by first defining a dummy type, a struct with no fields, something like: @@ -97,6 +96,5 @@ alternatives in [rust-lang/rust#41710]. [rust-lang/rust#41710]: https://github.com/rust-lang/rust/issues/41710 [mirtransform]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/ -<!--- TODO: Change NoLandingPads. [#1232](https://github.com/rust-lang/rustc-dev-guide/issues/1232) --> -[`NoLandingPads`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/no_landing_pads/struct.NoLandingPads.html +[`RemoveStorageMarkers`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/remove_storage_markers/struct.RemoveStorageMarkers.html [MIR visitor]: ./visitor.html diff --git a/src/doc/rustc-dev-guide/src/mir/visitor.md b/src/doc/rustc-dev-guide/src/mir/visitor.md index 5c21d5304..505b700b3 100644 --- a/src/doc/rustc-dev-guide/src/mir/visitor.md +++ b/src/doc/rustc-dev-guide/src/mir/visitor.md @@ -37,12 +37,10 @@ code that will execute whenever a `foo` is found. If you want to recursively walk the contents of the `foo`, you then invoke the `super_foo` method. (NB. You never want to override `super_foo`.) -A very simple example of a visitor can be found in [`NoLandingPads`]. -That visitor doesn't even require any state: it just visits all -terminators and removes their `unwind` successors. +A very simple example of a visitor can be found in [`LocalUseCounter`]. +By implementing `visit_local` method, this visitor counts how many times each local is used. -<!--- TODO: Change NoLandingPads. [#1232](https://github.com/rust-lang/rustc-dev-guide/issues/1232) --> -[`NoLandingPads`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/no_landing_pads/struct.NoLandingPads.html +[`LocalUseCounter`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/simplify_try/struct.LocalUseCounter.html ## Traversal diff --git a/src/doc/rustc-dev-guide/src/overview.md b/src/doc/rustc-dev-guide/src/overview.md index ceb0efdb2..ca37f94b2 100644 --- a/src/doc/rustc-dev-guide/src/overview.md +++ b/src/doc/rustc-dev-guide/src/overview.md @@ -374,7 +374,7 @@ For more details on bootstrapping, see - Lexical Analysis: Lex the user program to a stream of tokens - Guide: [Lexing and Parsing](the-parser.md) - Lexer definition: [`rustc_lexer`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lexer/index.html) - - Main entry point: [`rustc_lexer::first_token`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lexer/fn.first_token.html) + - Main entry point: [`rustc_lexer::cursor::Cursor::advance_token`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lexer/cursor/struct.Cursor.html#method.advance_token) - Parsing: Parse the stream of tokens to an Abstract Syntax Tree (AST) - Guide: [Lexing and Parsing](the-parser.md) - Guide: [Macro Expansion](macro-expansion.md) diff --git a/src/doc/rustc-dev-guide/src/profile-guided-optimization.md b/src/doc/rustc-dev-guide/src/profile-guided-optimization.md index db2624e92..69c0599a0 100644 --- a/src/doc/rustc-dev-guide/src/profile-guided-optimization.md +++ b/src/doc/rustc-dev-guide/src/profile-guided-optimization.md @@ -131,8 +131,8 @@ in [run-make tests][rmake-tests] (the relevant tests have `pgo` in their name). There is also a [codegen test][codegen-test] that checks that some expected instrumentation artifacts show up in LLVM IR. -[rmake-tests]: https://github.com/rust-lang/rust/tree/master/src/test/run-make-fulldeps -[codegen-test]: https://github.com/rust-lang/rust/blob/master/src/test/codegen/pgo-instrumentation.rs +[rmake-tests]: https://github.com/rust-lang/rust/tree/master/tests/run-make-fulldeps +[codegen-test]: https://github.com/rust-lang/rust/blob/master/tests/codegen/pgo-instrumentation.rs ## Additional Information diff --git a/src/doc/rustc-dev-guide/src/queries/incremental-compilation-in-detail.md b/src/doc/rustc-dev-guide/src/queries/incremental-compilation-in-detail.md index abd2b0155..76ebf10e8 100644 --- a/src/doc/rustc-dev-guide/src/queries/incremental-compilation-in-detail.md +++ b/src/doc/rustc-dev-guide/src/queries/incremental-compilation-in-detail.md @@ -62,7 +62,8 @@ the result of `type_of(bar)` might yield a different result than what we have in the cache and, transitively, the result of `type_check_item(foo)` might have changed too. We thus re-run `type_check_item(foo)`, which in turn will re-run `type_of(bar)`, which will yield an up-to-date result -because it reads the up-to-date version of `Hir(bar)`. +because it reads the up-to-date version of `Hir(bar)`. Also, we re-run +`type_check_item(bar)` because result of `type_of(bar)` might have changed. ## The Problem With The Basic Algorithm: False Positives diff --git a/src/doc/rustc-dev-guide/src/queries/query-evaluation-model-in-detail.md b/src/doc/rustc-dev-guide/src/queries/query-evaluation-model-in-detail.md index 8a08f1e04..296d88f6e 100644 --- a/src/doc/rustc-dev-guide/src/queries/query-evaluation-model-in-detail.md +++ b/src/doc/rustc-dev-guide/src/queries/query-evaluation-model-in-detail.md @@ -201,8 +201,8 @@ OK as long as the mutation is not observable. This is achieved by two things: - Before a result is stolen, we make sure to eagerly run all queries that might ever need to read that result. This has to be done manually by calling those queries. -- Whenever a query tries to access a stolen result, we make the compiler ICE so - that such a condition cannot go unnoticed. +- Whenever a query tries to access a stolen result, we make an ICE + (Internal Compiler Error) so that such a condition cannot go unnoticed. This is not an ideal setup because of the manual intervention needed, so it should be used sparingly and only when it is well known which queries might diff --git a/src/doc/rustc-dev-guide/src/query.md b/src/doc/rustc-dev-guide/src/query.md index 268a56558..5dbffac8d 100644 --- a/src/doc/rustc-dev-guide/src/query.md +++ b/src/doc/rustc-dev-guide/src/query.md @@ -223,7 +223,7 @@ Let's go over these elements one by one: - **Query modifiers:** various flags and options that customize how the query is processed (mostly with respect to [incremental compilation][incrcomp]). -[Key]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_query_impl/keys/trait.Key.html +[Key]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/query/keys/trait.Key.html [incrcomp]: queries/incremental-compilation-in-detail.html#query-modifiers So, to add a query: diff --git a/src/doc/rustc-dev-guide/src/rustc-driver-getting-diagnostics.md b/src/doc/rustc-dev-guide/src/rustc-driver-getting-diagnostics.md index 5ce93c3df..bb19ad9d3 100644 --- a/src/doc/rustc-dev-guide/src/rustc-driver-getting-diagnostics.md +++ b/src/doc/rustc-dev-guide/src/rustc-driver-getting-diagnostics.md @@ -7,7 +7,7 @@ To get diagnostics from the compiler, configure `rustc_interface::Config` to output diagnostic to a buffer, and run `TyCtxt.analysis`. The following was tested -with <!-- date-check: June 2022 --> `nightly-2022-06-05` (See [here][example] +with <!-- date-check: Jan 2023 --> `nightly-2022-12-19` (See [here][example] for the complete example): [example]: https://github.com/rust-lang/rustc-dev-guide/blob/master/examples/rustc-driver-getting-diagnostics.rs @@ -24,11 +24,7 @@ let config = rustc_interface::Config { ), }, /* other config */ - }, - // Redirect the diagnostic output of the compiler to a buffer. - diagnostic_output: rustc_session::DiagnosticOutput::Raw(Box::from(DiagnosticSink( - buffer.clone(), - ))), + }, /* other config */ }; rustc_interface::run_compiler(config, |compiler| { diff --git a/src/doc/rustc-dev-guide/src/rustc-driver-interacting-with-the-ast.md b/src/doc/rustc-dev-guide/src/rustc-driver-interacting-with-the-ast.md index ce53f3861..5b495b4fe 100644 --- a/src/doc/rustc-dev-guide/src/rustc-driver-interacting-with-the-ast.md +++ b/src/doc/rustc-dev-guide/src/rustc-driver-interacting-with-the-ast.md @@ -5,7 +5,7 @@ ## Getting the type of an expression To get the type of an expression, use the `global_ctxt` to get a `TyCtxt`. -The following was tested with <!-- date-check: June 2022 --> `nightly-2022-06-05` +The following was tested with <!-- date-check: Jan 2023 --> `nightly-2022-12-19` (see [here][example] for the complete example): [example]: https://github.com/rust-lang/rustc-dev-guide/blob/master/examples/rustc-driver-interacting-with-the-ast.rs diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals.md b/src/doc/rustc-dev-guide/src/rustdoc-internals.md index c85e82e96..a8cc0c376 100644 --- a/src/doc/rustc-dev-guide/src/rustdoc-internals.md +++ b/src/doc/rustc-dev-guide/src/rustdoc-internals.md @@ -191,7 +191,7 @@ Some extra reading about `make_test` can be found So that's rustdoc's code in a nutshell, but there's more things in the repo that deal with it. Since we have the full `compiletest` suite at hand, there's -a set of tests in `src/test/rustdoc` that make sure the final HTML is what we +a set of tests in `tests/rustdoc` that make sure the final HTML is what we expect in various situations. These tests also use a supplementary script, `src/etc/htmldocck.py`, that allows it to look through the final HTML using XPath notation to get a precise look at the output. The full description of all @@ -204,7 +204,7 @@ directory relative to the test file with the comment. If you need to build docs for the auxiliary file, use `// build-aux-docs`. In addition, there are separate tests for the search index and rustdoc's -ability to query it. The files in `src/test/rustdoc-js` each contain a +ability to query it. The files in `tests/rustdoc-js` each contain a different search query and the expected results, broken out by search tab. These files are processed by a script in `src/tools/rustdoc-js` and the Node.js runtime. These tests don't have as thorough of a writeup, but a broad example diff --git a/src/doc/rustc-dev-guide/src/rustdoc.md b/src/doc/rustc-dev-guide/src/rustdoc.md index 23428efd6..d58b27bb7 100644 --- a/src/doc/rustc-dev-guide/src/rustdoc.md +++ b/src/doc/rustc-dev-guide/src/rustdoc.md @@ -46,17 +46,17 @@ does is call the `main()` that's in this crate's `lib.rs`, though.) * Use `./x.py build` to make a usable rustdoc you can run on other projects. * Add `library/test` to be able to use `rustdoc --test`. - * Run `rustup toolchain link stage2 build/$TARGET/stage2` to add a + * Run `rustup toolchain link stage2 build/host/stage2` to add a 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` to use this rustdoc to generate the standard library docs. - * The completed docs will be available in `build/$TARGET/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 - `build/$TARGET/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. -* Use `./x.py test src/test/rustdoc*` to run the tests using a stage1 +* Use `./x.py test tests/rustdoc*` to run the tests using a stage1 rustdoc. * See [Rustdoc internals] for more information about tests. @@ -72,13 +72,13 @@ does is call the `main()` that's in this crate's `lib.rs`, though.) `doctest.rs`. * The Markdown renderer is loaded up in `html/markdown.rs`, including functions for extracting doctests from a given block of Markdown. -* The tests on the structure of rustdoc HTML output are located in `src/test/rustdoc`, where +* The tests on the structure of rustdoc HTML output are located in `tests/rustdoc`, where they're handled by the test runner of rustbuild and the supplementary script `src/etc/htmldocck.py`. ## Tests -* All paths in this section are relative to `src/test` in the rust-lang/rust repository. +* All paths in this section are relative to `tests` in the rust-lang/rust repository. * Tests on search index generation are located in `rustdoc-js`, as a series of JavaScript files that encode queries on the standard library search index and expected results. diff --git a/src/doc/rustc-dev-guide/src/sanitizers.md b/src/doc/rustc-dev-guide/src/sanitizers.md index a088d62ed..21b07ec99 100644 --- a/src/doc/rustc-dev-guide/src/sanitizers.md +++ b/src/doc/rustc-dev-guide/src/sanitizers.md @@ -9,6 +9,9 @@ The rustc compiler contains support for following sanitizers: forward-edge control flow protection. * [Hardware-assisted AddressSanitizer][clang-hwasan] a tool similar to AddressSanitizer but based on partial hardware assistance. +* [KernelControlFlowIntegrity][clang-kcfi] LLVM Kernel Control Flow Integrity + (KCFI) provides forward-edge control flow protection for operating systems + kernels. * [LeakSanitizer][clang-lsan] a run-time memory leak detector. * [MemorySanitizer][clang-msan] a detector of uninitialized reads. * [ThreadSanitizer][clang-tsan] a fast data race detector. @@ -16,9 +19,9 @@ The rustc compiler contains support for following sanitizers: ## How to use the sanitizers? To enable a sanitizer compile with `-Z sanitizer=...` option, where value is one -of `address`, `cfi`, `hwaddress`, `leak`, `memory` or `thread`. For more details -on how to use sanitizers please refer to the sanitizer flag in [the unstable -book](https://doc.rust-lang.org/unstable-book/). +of `address`, `cfi`, `hwaddress`, `kcfi`, `leak`, `memory` or `thread`. For more +details on how to use sanitizers please refer to the sanitizer flag in [the +unstable book](https://doc.rust-lang.org/unstable-book/). ## How are sanitizers implemented in rustc? @@ -73,8 +76,8 @@ implementation: ## Testing sanitizers Sanitizers are validated by code generation tests in -[`src/test/codegen/sanitize*.rs`][test-cg] and end-to-end functional tests in -[`src/test/ui/sanitize/`][test-ui] directory. +[`tests/codegen/sanitize*.rs`][test-cg] and end-to-end functional tests in +[`tests/ui/sanitize/`][test-ui] directory. Testing sanitizer functionality requires the sanitizer runtimes (built when `sanitizer = true` in `config.toml`) and target providing support for particular @@ -82,8 +85,8 @@ sanitizer. When sanitizer is unsupported on given target, sanitizers tests will be ignored. This behaviour is controlled by compiletest `needs-sanitizer-*` directives. -[test-cg]: https://github.com/rust-lang/rust/tree/master/src/test/codegen -[test-ui]: https://github.com/rust-lang/rust/tree/master/src/test/ui/sanitize +[test-cg]: https://github.com/rust-lang/rust/tree/master/tests/codegen +[test-ui]: https://github.com/rust-lang/rust/tree/master/tests/ui/sanitize ## Enabling sanitizer on a new target @@ -95,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] 3. [Teach compiletest that your target now supports the sanitizer.][compiletest-definition] Tests marked with `needs-sanitizer-*` should now run on the target. -4. Run tests `./x.py test --force-rerun src/test/ui/sanitize/` to verify. +4. Run tests `./x.py test --force-rerun tests/ui/sanitize/` to verify. 5. [--enable-sanitizers in the CI configuration][ci-configuration] to build and distribute the sanitizer runtime as part of the release process. @@ -109,6 +112,7 @@ To enable a sanitizer on a new target which is already supported by LLVM: * [AddressSanitizer in Clang][clang-asan] * [ControlFlowIntegrity in Clang][clang-cfi] * [Hardware-assisted AddressSanitizer][clang-hwasan] +* [KernelControlFlowIntegrity in Clang][clang-kcfi] * [LeakSanitizer in Clang][clang-lsan] * [MemorySanitizer in Clang][clang-msan] * [ThreadSanitizer in Clang][clang-tsan] @@ -116,6 +120,7 @@ To enable a sanitizer on a new target which is already supported by LLVM: [clang-asan]: https://clang.llvm.org/docs/AddressSanitizer.html [clang-cfi]: https://clang.llvm.org/docs/ControlFlowIntegrity.html [clang-hwasan]: https://clang.llvm.org/docs/HardwareAssistedAddressSanitizerDesign.html +[clang-kcfi]: https://clang.llvm.org/docs/ControlFlowIntegrity.html#fsanitize-kcfi [clang-lsan]: https://clang.llvm.org/docs/LeakSanitizer.html [clang-msan]: https://clang.llvm.org/docs/MemorySanitizer.html [clang-tsan]: https://clang.llvm.org/docs/ThreadSanitizer.html diff --git a/src/doc/rustc-dev-guide/src/serialization.md b/src/doc/rustc-dev-guide/src/serialization.md index 5d8434b55..691d21bc2 100644 --- a/src/doc/rustc-dev-guide/src/serialization.md +++ b/src/doc/rustc-dev-guide/src/serialization.md @@ -162,5 +162,5 @@ for `Encodable<CacheEncoder>`. [`rustc_metadata::rmeta::decoder::DecodeContext`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/rmeta/decoder/struct.DecodeContext.html [`rustc_metadata::rmeta::encoder::EncodeContext`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/rmeta/encoder/struct.EncodeContext.html [`rustc_serialize`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_serialize/index.html -[`TyDecoder`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/codec/trait.TyEncoder.html -[`TyEncoder`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/codec/trait.TyDecoder.html +[`TyDecoder`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/codec/trait.TyDecoder.html +[`TyEncoder`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/codec/trait.TyEncoder.html diff --git a/src/doc/rustc-dev-guide/src/tests/adding.md b/src/doc/rustc-dev-guide/src/tests/adding.md index 2fb1e0b65..632614539 100644 --- a/src/doc/rustc-dev-guide/src/tests/adding.md +++ b/src/doc/rustc-dev-guide/src/tests/adding.md @@ -12,7 +12,7 @@ This will depend on the nature of the change and what you want to exercise. Here are some rough guidelines: - The majority of compiler tests are done with [compiletest]. - - The majority of compiletest tests are [UI](ui.md) tests in the [`src/test/ui`] directory. + - The majority of compiletest tests are [UI](ui.md) tests in the [`tests/ui`] directory. - Changes to the standard library are usually tested within the standard library itself. - The majority of standard library tests are written as doctests, which illustrate and exercise typical API behavior. @@ -30,7 +30,7 @@ Here are some rough guidelines: - Check out the [compiletest] chapter for more specialized test suites. [compiletest]: compiletest.md -[`src/test/ui`]: https://github.com/rust-lang/rust/tree/master/src/test/ui/ +[`tests/ui`]: https://github.com/rust-lang/rust/tree/master/tests/ui/ ## UI test walkthrough @@ -41,13 +41,13 @@ For this tutorial, we'll be adding a test for an async error message. ### Step 1. Add a test file The first step is to create a Rust source file somewhere in the -[`src/test/ui`] tree. +[`tests/ui`] tree. When creating a test, do your best to find a good location and name (see [Test organization](ui.md#test-organization) for more). Since naming is the hardest part of development, everything should be downhill from here! -Let's place our async test at `src/test/ui/async-await/await-without-async.rs`: +Let's place our async test at `tests/ui/async-await/await-without-async.rs`: ```rust,ignore // Check what happens when using await in a non-async fn. @@ -84,19 +84,19 @@ The next step is to create the expected output from the compiler. This can be done with the `--bless` option: ```sh -./x.py test src/test/ui/async-await/await-without-async.rs --bless +./x.py test tests/ui/async-await/await-without-async.rs --bless ``` This will build the compiler (if it hasn't already been built), compile the test, and place the output of the compiler in a file called -`src/test/ui/async-await/await-without-async.stderr`. +`tests/ui/async-await/await-without-async.stderr`. However, this step will fail! You should see an error message, something like this: -> error: /rust/src/test/ui/async-await/await-without-async.rs:7: unexpected +> error: /rust/tests/ui/async-await/await-without-async.rs:7: unexpected > error: '7:10: 7:16: `await` is only allowed inside `async` functions and -> blocks [E0728]' +> blocks E0728' ### Step 3. Add error annotations @@ -118,7 +118,7 @@ annotations](ui.md#error-annotations) section). Save that, and run the test again: ```sh -./x.py test src/test/ui/async-await/await-without-async.rs +./x.py test tests/ui/async-await/await-without-async.rs ``` It should now pass, yay! @@ -131,7 +131,7 @@ If you are adding a new diagnostic message, now would be a good time to also consider how readable the message looks overall, particularly for people new to Rust. -Our example `src/test/ui/async-await/await-without-async.stderr` file should +Our example `tests/ui/async-await/await-without-async.stderr` file should look like this: ```text @@ -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: ```sh -./x.py test src/test/ui +./x.py test tests/ui ``` If other tests start failing, you may need to investigate what has changed diff --git a/src/doc/rustc-dev-guide/src/tests/compiletest.md b/src/doc/rustc-dev-guide/src/tests/compiletest.md index 70cef2ad3..9f0c56dc4 100644 --- a/src/doc/rustc-dev-guide/src/tests/compiletest.md +++ b/src/doc/rustc-dev-guide/src/tests/compiletest.md @@ -26,11 +26,11 @@ suite. ## Test suites -All of the tests are in the [`src/test`] directory. +All of the tests are in the [`tests`] directory. The tests are organized into "suites", with each suite in a separate subdirectory. Each test suite behaves a little differently, with different compiler behavior and different checks for correctness. -For example, the [`src/test/incremental`] directory contains tests for +For example, the [`tests/incremental`] directory contains tests for incremental compilation. The various suites are defined in [`src/tools/compiletest/src/common.rs`] in the `pub enum Mode` declaration. @@ -62,12 +62,12 @@ The following test suites are available, with links for more information: - `rustdoc-json` — tests on the JSON output of rustdoc. - `rustdoc-ui` — tests on the terminal output of rustdoc. -[`src/test`]: https://github.com/rust-lang/rust/blob/master/src/test +[`tests`]: https://github.com/rust-lang/rust/blob/master/tests [`src/tools/compiletest/src/common.rs`]: https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/common.rs ### Pretty-printer tests -The tests in [`src/test/pretty`] exercise the "pretty-printing" functionality of `rustc`. +The tests in [`tests/pretty`] exercise the "pretty-printing" functionality of `rustc`. The `-Z unpretty` CLI option for `rustc` causes it to translate the input source into various different formats, such as the Rust source after macro expansion. @@ -119,11 +119,11 @@ The header commands for pretty-printing tests are: pretty-printing rounds will be compared to ensure that the pretty-printed output converges to a steady state. -[`src/test/pretty`]: https://github.com/rust-lang/rust/tree/master/src/test/pretty +[`tests/pretty`]: https://github.com/rust-lang/rust/tree/master/tests/pretty ### Incremental tests -The tests in [`src/test/incremental`] exercise incremental compilation. +The tests in [`tests/incremental`] exercise incremental compilation. They use [revision headers](#revisions) to tell compiletest to run the compiler in a series of steps. Compiletest starts with an empty directory with the `-C incremental` flag, and @@ -168,12 +168,12 @@ cause an Internal Compiler Error (ICE). This is a highly specialized header to check that the incremental cache continues to work after an ICE. -[`src/test/incremental`]: https://github.com/rust-lang/rust/tree/master/src/test/incremental +[`tests/incremental`]: https://github.com/rust-lang/rust/tree/master/tests/incremental ### Debuginfo tests -The tests in [`src/test/debuginfo`] test debuginfo generation. +The tests in [`tests/debuginfo`] test debuginfo generation. They build a program, launch a debugger, and issue commands to the debugger. A single test can work with cdb, gdb, and lldb. @@ -237,12 +237,12 @@ test based on the debugger currently being used: NOTE: The "Rust" version of LLDB doesn't exist anymore, so this will always be ignored. This should probably be removed. -[`src/test/debuginfo`]: https://github.com/rust-lang/rust/tree/master/src/test/debuginfo +[`tests/debuginfo`]: https://github.com/rust-lang/rust/tree/master/tests/debuginfo ### Codegen tests -The tests in [`src/test/codegen`] test LLVM code generation. +The tests in [`tests/codegen`] test LLVM code generation. They compile the test with the `--emit=llvm-ir` flag to emit LLVM IR. They then run the LLVM [FileCheck] tool. The test is annotated with various `// CHECK` comments to check the generated code. @@ -250,13 +250,13 @@ See the FileCheck documentation for a tutorial and more information. See also the [assembly tests](#assembly-tests) for a similar set of tests. -[`src/test/codegen`]: https://github.com/rust-lang/rust/tree/master/src/test/codegen +[`tests/codegen`]: https://github.com/rust-lang/rust/tree/master/tests/codegen [FileCheck]: https://llvm.org/docs/CommandGuide/FileCheck.html ### Assembly tests -The tests in [`src/test/assembly`] test LLVM assembly output. +The tests in [`tests/assembly`] test LLVM assembly output. They compile the test with the `--emit=asm` flag to emit a `.s` file with the assembly output. They then run the LLVM [FileCheck] tool. @@ -271,12 +271,12 @@ See the FileCheck documentation for a tutorial and more information. See also the [codegen tests](#codegen-tests) for a similar set of tests. -[`src/test/assembly`]: https://github.com/rust-lang/rust/tree/master/src/test/assembly +[`tests/assembly`]: https://github.com/rust-lang/rust/tree/master/tests/assembly ### Codegen-units tests -The tests in [`src/test/codegen-units`] test the +The tests in [`tests/codegen-units`] test the [monomorphization](../backend/monomorph.md) collector and CGU partitioning. These tests work by running `rustc` with a flag to print the result of the @@ -295,12 +295,12 @@ where `cgu` is a space separated list of the CGU names and the linkage information in brackets. For example: `//~ MONO_ITEM static function::FOO @@ statics[Internal]` -[`src/test/codegen-units`]: https://github.com/rust-lang/rust/tree/master/src/test/codegen-units +[`tests/codegen-units`]: https://github.com/rust-lang/rust/tree/master/tests/codegen-units ### Mir-opt tests -The tests in [`src/test/mir-opt`] check parts of the generated MIR to make +The tests in [`tests/mir-opt`] check parts of the generated MIR to make sure it is generated correctly and is doing the expected optimizations. Check out the [MIR Optimizations](../mir/optimizations.md) chapter for more. @@ -345,12 +345,12 @@ problematic in the presence of pointers in constants or other bit width dependent things. In that case you can add `// EMIT_MIR_FOR_EACH_BIT_WIDTH` to your test, causing separate files to be generated for 32bit and 64bit systems. -[`src/test/mir-opt`]: https://github.com/rust-lang/rust/tree/master/src/test/mir-opt +[`tests/mir-opt`]: https://github.com/rust-lang/rust/tree/master/tests/mir-opt ### Run-make tests -The tests in [`src/test/run-make`] are general-purpose tests using Makefiles +The tests in [`tests/run-make`] are general-purpose tests using Makefiles which provide the ultimate in flexibility. These should be used as a last resort. If possible, you should use one of the other test suites. @@ -365,18 +365,18 @@ There is a [`tools.mk`] Makefile which you can include which provides a bunch of utilities to make it easier to run commands and compare outputs. Take a look at some of the other tests for some examples on how to get started. -[`tools.mk`]: https://github.com/rust-lang/rust/blob/master/src/test/run-make-fulldeps/tools.mk -[`src/test/run-make`]: https://github.com/rust-lang/rust/tree/master/src/test/run-make +[`tools.mk`]: https://github.com/rust-lang/rust/blob/master/tests/run-make-fulldeps/tools.mk +[`tests/run-make`]: https://github.com/rust-lang/rust/tree/master/tests/run-make ### Valgrind tests -The tests in [`src/test/run-pass-valgrind`] are for use with [Valgrind]. +The tests in [`tests/run-pass-valgrind`] are for use with [Valgrind]. These are currently vestigial, as Valgrind is no longer used in CI. These may be removed in the future. [Valgrind]: https://valgrind.org/ -[`src/test/run-pass-valgrind`]: https://github.com/rust-lang/rust/tree/master/src/test/run-pass-valgrind +[`tests/run-pass-valgrind`]: https://github.com/rust-lang/rust/tree/master/tests/run-pass-valgrind ## Building auxiliary crates @@ -501,7 +501,7 @@ To run the tests in a different mode, you need to pass the `--compare-mode` CLI flag: ```bash -./x.py test src/test/ui --compare-mode=chalk +./x.py test tests/ui --compare-mode=chalk ``` The possible compare modes are: @@ -517,10 +517,10 @@ tests support different output for different modes. In CI, compare modes are only used in one Linux builder, and only with the following settings: -* `src/test/debuginfo`: Uses `split-dwarf` mode. +* `tests/debuginfo`: Uses `split-dwarf` mode. This helps ensure that none of the debuginfo tests are affected when enabling split-DWARF. Note that compare modes are separate to [revisions](#revisions). -All revisions are tested when running `./x.py test src/test/ui`, however +All revisions are tested when running `./x.py test tests/ui`, however compare-modes must be manually run individually via the `--compare-mode` flag. diff --git a/src/doc/rustc-dev-guide/src/tests/docker.md b/src/doc/rustc-dev-guide/src/tests/docker.md index feb614c51..0d9e0a492 100644 --- a/src/doc/rustc-dev-guide/src/tests/docker.md +++ b/src/doc/rustc-dev-guide/src/tests/docker.md @@ -21,7 +21,7 @@ directory. From there, you can run `../src/ci/run.sh` which will run the build as defined by the image. Alternatively, you can run individual commands to do specific tasks. For -example, you can run `python3 ../x.py test src/test/ui` to just run UI tests. +example, you can run `python3 ../x.py test tests/ui` to just run UI tests. 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 `config.toml` so that it doesn't attempt to modify the read-only directory. diff --git a/src/doc/rustc-dev-guide/src/tests/headers.md b/src/doc/rustc-dev-guide/src/tests/headers.md index bfa637f34..5b71f3ea1 100644 --- a/src/doc/rustc-dev-guide/src/tests/headers.md +++ b/src/doc/rustc-dev-guide/src/tests/headers.md @@ -244,12 +244,12 @@ described below: - Examples: `/path/to/rust`, `/path/to/build/root` - `{{src-base}}`: The directory where the test is defined. This is equivalent to `$DIR` for [output normalization]. - - Example: `/path/to/rust/src/test/ui/error-codes` + - Example: `/path/to/rust/tests/ui/error-codes` - `{{build-base}}`: The base directory where the test's output goes. This is equivalent to `$TEST_BUILD_DIR` for [output normalization]. - Example: `/path/to/rust/build/x86_64-unknown-linux-gnu/test/ui` -See [`src/test/ui/commandline-argfile.rs`](https://github.com/rust-lang/rust/blob/a5029ac0ab372aec515db2e718da6d7787f3d122/src/test/ui/commandline-argfile.rs) +See [`tests/ui/commandline-argfile.rs`](https://github.com/rust-lang/rust/blob/master/tests/ui/commandline-argfile.rs) for an example of a test that uses this substitution. [output normalization]: ui.md#normalization diff --git a/src/doc/rustc-dev-guide/src/tests/intro.md b/src/doc/rustc-dev-guide/src/tests/intro.md index 66e0a9eef..adc5d58ec 100644 --- a/src/doc/rustc-dev-guide/src/tests/intro.md +++ b/src/doc/rustc-dev-guide/src/tests/intro.md @@ -16,13 +16,13 @@ Almost all of them are driven by `./x.py test`, with some exceptions noted below The main test harness for testing the compiler itself is a tool called [compiletest]. It supports running different styles of tests, called *test suites*. -The tests are all located in the [`src/test`] directory. +The tests are all located in the [`tests`] directory. The [Compiletest chapter][compiletest] goes into detail on how to use this tool. -> Example: `./x.py test src/test/ui` +> Example: `./x.py test tests/ui` [compiletest]: compiletest.md -[`src/test`]: https://github.com/rust-lang/rust/tree/master/src/test +[`tests`]: https://github.com/rust-lang/rust/tree/master/tests ### Package tests diff --git a/src/doc/rustc-dev-guide/src/tests/running.md b/src/doc/rustc-dev-guide/src/tests/running.md index 5d1441936..96c869109 100644 --- a/src/doc/rustc-dev-guide/src/tests/running.md +++ b/src/doc/rustc-dev-guide/src/tests/running.md @@ -37,7 +37,7 @@ modifying rustc to see if things are generally working correctly would be the following: ```bash -./x.py test src/test/ui +./x.py test tests/ui ``` This will run the `ui` test suite. Of course, the choice @@ -46,20 +46,20 @@ doing. For example, if you are hacking on debuginfo, you may be better off with the debuginfo test suite: ```bash -./x.py test src/test/debuginfo +./x.py test tests/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 src/test/ui/const-generics +./x.py test tests/ui/const-generics ``` Likewise, you can test a single file by passing its path: ```bash -./x.py test src/test/ui/const-generics/const-test.rs +./x.py test tests/ui/const-generics/const-test.rs ``` ### Run only the tidy script @@ -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: ```bash -./x.py test src/test/ui --test-args issue-1234 +./x.py test tests/ui --test-args issue-1234 ``` Under the hood, the test runner invokes the standard Rust test runner @@ -137,10 +137,10 @@ filtering for tests that include "issue-1234" in the name. (Thus If you have changed the compiler's output intentionally, or you are 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 +if some tests in `tests/ui` are failing, you can run ```text -./x.py test src/test/ui --bless +./x.py test tests/ui --bless ``` to automatically adjust the `.stderr`, `.stdout` or `.fixed` files of @@ -165,10 +165,10 @@ Pass UI tests now have three modes, `check-pass`, `build-pass` and `run-pass`. When `--pass $mode` is passed, these tests will be forced to run under the given `$mode` unless the directive `// ignore-pass` exists in the test file. For example, you can run all the tests in -`src/test/ui` as `check-pass`: +`tests/ui` as `check-pass`: ```bash -./x.py test src/test/ui --pass check +./x.py test tests/ui --pass check ``` By passing `--pass $mode`, you can reduce the testing time. For each @@ -181,7 +181,7 @@ You can further enable the `--incremental` flag to save additional time in subsequent rebuilds: ```bash -./x.py test src/test/ui --incremental --test-args issue-1234 +./x.py test tests/ui --incremental --test-args issue-1234 ``` If you don't want to include the flag with every command, you can @@ -205,7 +205,7 @@ mode, a test `foo.rs` will first look for expected output in The following will run the UI test suite in Polonius mode: ```bash -./x.py test src/test/ui --compare-mode=polonius +./x.py test tests/ui --compare-mode=polonius ``` See [Compare modes](compiletest.md#compare-modes) for more details. @@ -218,7 +218,7 @@ Most tests are just `rs` files, so after you can do something like: ```bash -rustc +stage1 src/test/ui/issue-1234.rs +rustc +stage1 tests/ui/issue-1234.rs ``` This is much faster, but doesn't always work. For example, some tests @@ -242,7 +242,7 @@ machine, e.g. for RISC-V ``` The binary will be created at -`./build/$HOST_ARCH/stage2-tools/$TARGET_ARCH/release/remote-test-server`. Copy +`./build/host/stage2-tools/$TARGET_ARCH/release/remote-test-server`. Copy this over to the remote machine. On the remote machine, run the `remote-test-server` with the `--bind @@ -272,7 +272,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 ```sh export TEST_DEVICE_ADDR="1.2.3.4:12345" -./x.py test src/test/ui --target riscv64gc-unknown-linux-gnu +./x.py test tests/ui --target riscv64gc-unknown-linux-gnu ``` If `remote-test-server` was run with the verbose flag, output on the test machine diff --git a/src/doc/rustc-dev-guide/src/tests/ui.md b/src/doc/rustc-dev-guide/src/tests/ui.md index 3556f4e23..cc32ad1d3 100644 --- a/src/doc/rustc-dev-guide/src/tests/ui.md +++ b/src/doc/rustc-dev-guide/src/tests/ui.md @@ -6,18 +6,18 @@ UI tests are a particular [test suite](compiletest.md#test-suites) of compiletes ## Introduction -The tests in [`src/test/ui`] are a collection of general-purpose tests which +The tests in [`tests/ui`] are a collection of general-purpose tests which primarily focus on validating the console output of the compiler, but can be used for many other purposes. For example, tests can also be configured to [run the resulting program](#controlling-passfail-expectations) to verify its behavior. -[`src/test/ui`]: https://github.com/rust-lang/rust/blob/master/src/test/ui +[`tests/ui`]: https://github.com/rust-lang/rust/blob/master/tests/ui ## General structure of a test -A test consists of a Rust source file located anywhere in the `src/test/ui` directory. -For example, [`src/test/ui/hello.rs`] is a basic hello-world test. +A test consists of a Rust source file located anywhere in the `tests/ui` directory. +For example, [`tests/ui/hello.rs`] is a basic hello-world test. Compiletest will use `rustc` to compile the test, and compare the output against the expected output which is stored in a `.stdout` or `.stderr` file @@ -40,7 +40,7 @@ By default, a test is built as an executable binary. If you need a different crate type, you can use the `#![crate_type]` attribute to set it as needed. -[`src/test/ui/hello.rs`]: https://github.com/rust-lang/rust/blob/master/src/test/ui/hello.rs +[`tests/ui/hello.rs`]: https://github.com/rust-lang/rust/blob/master/tests/ui/hello.rs ## Output comparison @@ -99,7 +99,7 @@ platforms, mainly about filenames. Compiletest makes the following replacements on the compiler output: - The directory where the test is defined is replaced with `$DIR`. - Example: `/path/to/rust/src/test/ui/error-codes` + Example: `/path/to/rust/tests/ui/error-codes` - The directory to the standard library source is replaced with `$SRC_DIR`. Example: `/path/to/rust/library` - Line and column numbers for paths in `$SRC_DIR` are replaced with `LL:COL`. @@ -160,8 +160,8 @@ The corresponding reference file will use the normalized output to test both Please see [`ui/transmute/main.rs`][mrs] and [`main.stderr`] for a concrete usage example. -[mrs]: https://github.com/rust-lang/rust/blob/master/src/test/ui/transmute/main.rs -[`main.stderr`]: https://github.com/rust-lang/rust/blob/master/src/test/ui/transmute/main.stderr +[mrs]: https://github.com/rust-lang/rust/blob/master/tests/ui/transmute/main.rs +[`main.stderr`]: https://github.com/rust-lang/rust/blob/master/tests/ui/transmute/main.stderr Besides `normalize-stderr-32bit` and `-64bit`, one may use any target information or stage supported by [`ignore-X`](headers.md#ignoring-tests) @@ -387,7 +387,7 @@ Tests with the `*-pass` headers can be overridden with the `--pass` command-line option: ```sh -./x.py test src/test/ui --pass check +./x.py test tests/ui --pass check ``` The `--pass` option only affects UI tests. @@ -426,30 +426,30 @@ from the internet – we often name the test after the issue plus a short description. Ideally, the test should be added to a directory that helps identify what piece of code is being tested here (e.g., -`src/test/ui/borrowck/issue-54597-reject-move-out-of-borrow-via-pat.rs`) +`tests/ui/borrowck/issue-54597-reject-move-out-of-borrow-via-pat.rs`) When writing a new feature, **create a subdirectory to store your tests**. For example, if you are implementing RFC 1234 ("Widgets"), then it might make -sense to put the tests in a directory like `src/test/ui/rfc1234-widgets/`. +sense to put the tests in a directory like `tests/ui/rfc1234-widgets/`. In other cases, there may already be a suitable directory. (The proper directory structure to use is actually an area of active debate.) -Over time, the [`src/test/ui`] directory has grown very fast. +Over time, the [`tests/ui`] directory has grown very fast. There is a check in [tidy](intro.md#tidy) that will ensure none of the subdirectories has more than 1000 entries. Having too many files causes problems because it isn't editor/IDE friendly and the GitHub UI won't show more than 1000 entries. -However, since `src/test/ui` (UI test root directory) and `src/test/ui/issues` +However, since `tests/ui` (UI test root directory) and `tests/ui/issues` directories have more than 1000 entries, we set a different limit for those directories. So, please avoid putting a new test there and try to find a more relevant place. For example, if your test is related to closures, you should put it in -`src/test/ui/closures`. +`tests/ui/closures`. If you're not sure where is the best place, it's still okay to add to -`src/test/ui/issues/`. +`tests/ui/issues/`. When you reach the limit, you could increase it by tweaking [here][ui test tidy]. @@ -512,7 +512,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: ```sh -./x.py test src/test/ui --compare-mode=polonius --bless +./x.py test tests/ui --compare-mode=polonius --bless ``` Currently none of the compare modes are checked in CI for UI tests. diff --git a/src/doc/rustc-dev-guide/src/ty.md b/src/doc/rustc-dev-guide/src/ty.md index 9b35f0d4c..90e17e85f 100644 --- a/src/doc/rustc-dev-guide/src/ty.md +++ b/src/doc/rustc-dev-guide/src/ty.md @@ -119,23 +119,20 @@ or `fn(i32) -> i32` (with type aliases fully expanded). ## `ty::Ty` implementation -[`rustc_middle::ty::Ty`][ty_ty] is actually a type alias to [`&TyS`][tys]. -This type, which is short for "Type Structure", is where the main functionality is located. -You can ignore `TyS` struct in general; you will basically never access it explicitly. -We always pass it by reference using the `Ty` alias. -The only exception is to define inherent methods on types. In particular, `TyS` has a [`kind`][kind] -field of type [`TyKind`][tykind], which represents the key type information. `TyKind` is a big enum +[`rustc_middle::ty::Ty`][ty_ty] is actually a wrapper around +[`Interned<WithCachedTypeInfo<TyKind>>`][tykind]. +You can ignore `Interned` in general; you will basically never access it explicitly. +We always hide them within `Ty` and skip over it via `Deref` impls or methods. +`TyKind` is a big enum with variants to represent many different Rust types (e.g. primitives, references, abstract data types, generics, lifetimes, etc). -`TyS` also has 2 more fields, `flags` and `outer_exclusive_binder`. They +`WithCachedTypeInfo` has a few cached values like `flags` and `outer_exclusive_binder`. They are convenient hacks for efficiency and summarize information about the type that we may want to -know, but they don’t come into the picture as much here. Finally, `ty::TyS`s -are [interned](./memory.md), so that the `ty::Ty` can be a thin pointer-like +know, but they don’t come into the picture as much here. Finally, [`Interned`](./memory.md) allows +the `ty::Ty` to be a thin pointer-like type. This allows us to do cheap comparisons for equality, along with the other benefits of interning. -[tys]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyS.html -[kind]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyS.html#structfield.kind [tykind]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/enum.TyKind.html ## Allocating and working with types diff --git a/src/doc/rustc-dev-guide/src/type-checking.md b/src/doc/rustc-dev-guide/src/type-checking.md index cd58faf22..08f15e30b 100644 --- a/src/doc/rustc-dev-guide/src/type-checking.md +++ b/src/doc/rustc-dev-guide/src/type-checking.md @@ -4,7 +4,7 @@ The [`rustc_typeck`][typeck] crate contains the source for "type collection" and "type checking", as well as a few other bits of related functionality. (It draws heavily on the [type inference] and [trait solving].) -[typeck]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_typeck/index.html +[typeck]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_analysis/index.html [type inference]: ./type-inference.md [trait solving]: ./traits/resolution.md @@ -39,6 +39,6 @@ type *checking*). For more details, see the [`collect`][collect] module. [queries]: ./query.md -[collect]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_typeck/collect/ +[collect]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_analysis/collect/index.html **TODO**: actually talk about type checking... [#1161](https://github.com/rust-lang/rustc-dev-guide/issues/1161) |
