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

Streamline "Getting Started" some more. 

This is a follow-up to #1279.

The "Getting Started" chapter is, TBH, pretty bad when it comes to the
stuff about building and testing. It has far too much detail and lots of
repetition, which would be overwhelming to a newcomer.

This commit removes most of it, leaving behind just quick mentions of
the most common `x.py` commands: `check`, `build`, `test`, `fmt`, with
links to the appropriate chapters for details. There were a few
interesting details that weren't covered elsewhere, so I moved those
into other chapters.
This commit is contained in:
Nicholas Nethercote 2022-01-05 13:59:15 +11:00 committed by Joshua Nelson
parent ce4ae4004c
commit e3512c8cd8
5 changed files with 58 additions and 182 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -125,8 +125,8 @@ Options:
-h, --help print this help message -h, --help print this help message
``` ```
For hacking, often building the stage 1 compiler is enough, but for For hacking, often building the stage 1 compiler is enough, which saves a lot
final testing and release, the stage 2 compiler is used. of time. But for final testing and release, the stage 2 compiler is used.
`./x.py check` is really fast to build the rust 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 It is, in particular, very useful when you're doing some kind of
@ -168,7 +168,7 @@ there is a (hacky) workaround. See [the section on "recommended
workflows"](./suggested.md) below. workflows"](./suggested.md) below.
Note that this whole command just gives you a subset of the full `rustc` Note that this whole command just gives you a subset of the full `rustc`
build. The **full** `rustc` build (what you get if you say `./x.py build build. The **full** `rustc` build (what you get with `./x.py build
--stage 2 compiler/rustc`) has quite a few more steps: --stage 2 compiler/rustc`) has quite a few more steps:
- Build `rustc` with the stage1 compiler. - Build `rustc` with the stage1 compiler.
@ -176,20 +176,16 @@ build. The **full** `rustc` build (what you get if you say `./x.py build
- Build `std` with stage2 compiler. - Build `std` with stage2 compiler.
- Build `librustdoc` and a bunch of other things with the stage2 compiler. - Build `librustdoc` and a bunch of other things with the stage2 compiler.
<a name=toolchain></a> You almost never need to do this.
## Build specific components ## Build specific components
- Build only the core library If you are working on the standard library, you probably don't need to build
the compiler unless you are planning to use a recently added nightly feature.
Instead, you can just build stage 0, which uses the current beta compiler.
```bash ```bash
./x.py build --stage 0 library/core ./x.py build --stage 0 library/std
```
- Build only the core and `proc_macro` libraries
```bash
./x.py build --stage 0 library/core library/proc_macro
``` ```
Sometimes you might just want to test if the part you’re working on can Sometimes you might just want to test if the part you’re working on can
@ -245,7 +241,8 @@ in other sections:
- Building things: - Building things:
- `./x.py build` – builds everything using the stage 1 compiler, - `./x.py build` – builds everything using the stage 1 compiler,
not just up to `std` not just up to `std`
- `./x.py build --stage 2` – builds the stage2 compiler - `./x.py build --stage 2` – builds the stage2 compiler, along with `std` and
`rustdoc` (which doesn't take too long)
- Running tests (see the [section on running tests](../tests/running.html) for - Running tests (see the [section on running tests](../tests/running.html) for
more details): more details):
- `./x.py test library/std` – runs the `#[test]` tests from `std` - `./x.py test library/std` – runs the `#[test]` tests from `std`

22
src/conventions.md
View File

@ -8,17 +8,25 @@ chapter covers [formatting](#formatting), [coding for correctness](#cc),
# Formatting and the tidy script # Formatting and the tidy script
rustc is moving towards the [Rust standard coding style][fmt]. rustc is moving towards the [Rust standard coding style][fmt].
This is enforced by the "tidy" script and can be mostly
automated using `./x.py fmt`.
As the output of [rustfmt] is not completely stable, However, for now we don't use stable `rustfmt`; we use a pinned version with a
formatting this repository using `cargo fmt` is not recommended. special config, so this may result in different style from normal [`rustfmt`].
Therefore, formatting this repository using `cargo fmt` is not recommended.
The tidy script runs automatically when you do `./x.py test` and can be run Instead, formatting should be done using `./x.py fmt`. It's a good habit to run
in isolation with `./x.py test tidy`. `./x.py fmt` before every commit, as this reduces conflicts later.
Formatting is checked by the "tidy" script. It runs automatically when you do
`./x.py test` and can be run in isolation with `./x.py test tidy`. `./x.py fmt
--check` also works.
If you want to use format-on-save in your editor, the pinned version of
`rustfmt` is built under `build/<target>/stage0/bin/rustfmt`. You'll have to
pass the <!-- date: 2021-09 --> `--edition=2021` argument yourself when calling
`rustfmt` directly.
[fmt]: https://github.com/rust-dev-tools/fmt-rfcs [fmt]: https://github.com/rust-dev-tools/fmt-rfcs
[rustfmt]:https://github.com/rust-lang/rustfmt [`rustfmt`]:https://github.com/rust-lang/rustfmt
<a name="copyright"></a> <a name="copyright"></a>

174
src/getting-started.md
View File

@ -96,174 +96,28 @@ See [this chapter][config] for more info about configuration.
[config]: ./building/how-to-build-and-run.md#create-a-configtoml [config]: ./building/how-to-build-and-run.md#create-a-configtoml
### Building and Testing `rustc` ### Common `x.py` commands
Here is a summary of the different commands for reference, but you probably Here are the basic invocations of the `x.py` commands most commonly used when
should still read the rest of the section: working on `rustc`, `std`, `rustdoc`, and other tools.
| Command | When to use it | | Command | When to use it |
| --- | --- | | --- | --- |
| `./x.py check` | Quick check to see if things compile; [rust-analyzer can run this automatically for you][rust-analyzer] | | `./x.py check` | Quick check to see if most things compile; [rust-analyzer can run this automatically for you][rust-analyzer] |
| `./x.py build --stage 0 [library/std]` | Build only the standard library, without building the compiler | | `./x.py build` | Builds `rustc`, `std`, and `rustdoc` |
| `./x.py build library/std` | Build just the 1st stage of the compiler, along with the standard library; this is faster than building stage 2 and usually good enough | | `./x.py test` | Runs all tests |
| `./x.py build --keep-stage 1 library/std` | Build the 1st stage of the compiler and skips rebuilding the standard library; this is useful after you've done an ordinary stage1 build to skip compilation time, but it can cause weird problems. (Just do a regular build to resolve.) | | `./x.py fmt` | Formats all code |
| `./x.py test [--keep-stage 1]` | Run the test suite using the stage1 compiler |
| `./x.py test --bless [--keep-stage 1]` | Run the test suite using the stage1 compiler _and_ update expected test output. |
| `./x.py build --stage 2 compiler/rustc` | Do a full 2-stage build. You almost never want to do this. |
| `./x.py test --stage 2` | Do a full 2-stage build and run all tests. You almost never want to do this. |
To do a full 2-stage build of the whole compiler, you should run this (after As written, these commands are reasonable starting points. However, there are
updating `config.toml` as mentioned above): additional options and arguments for each of them that are worth learning for
serious development work. In particular, `./x.py build` and `./x.py test`
```sh provide many ways to compile or test a subset of the code, which can save a lot
./x.py build --stage 2 compiler/rustc of time.
```
In the process, this will also necessarily build the standard libraries, and it
will build `rustdoc` (which doesn't take too long).
To build and test everything:
```sh
./x.py test
```
For most contributions, you only need to build stage 1, which saves a lot of time:
```sh
# Build the compiler (stage 1)
./x.py build library/std
# Subsequent builds
./x.py build --keep-stage 1 library/std
```
This will take a while, especially the first time. Be wary of accidentally
touching or formatting the compiler, as `x.py` will try to recompile it.
**NOTE**: The `--keep-stage 1` will _assume_ that the stage 0 standard library
does not need to be rebuilt, which is usually true, which will save some time.
However, if you are changing certain parts of the compiler, this may lead to
weird errors. Feel free to ask on [zulip][z] if you are running into issues.
This runs a ton of tests and takes a long time to complete. If you are
working on `rustc`, you can usually get by with only the [UI tests][uitests]. These
test are mostly for the frontend of the compiler, so if you are working on LLVM
or codegen, this shortcut will _not_ test your changes. You can read more about the
different test suites [in this chapter][testing].
[rust-analyzer]: ./building/suggested.html#configuring-rust-analyzer-for-rustc [rust-analyzer]: ./building/suggested.html#configuring-rust-analyzer-for-rustc
[uitests]: ./tests/adding.html#ui
[testing]: https://rustc-dev-guide.rust-lang.org/tests/intro.html
```sh See the chapters on [building](./building/how-to-build-and-run.md) and
# First build [testing](./tests/intro.md) for more details.
./x.py test src/test/ui
# Subsequent builds
./x.py test src/test/ui --keep-stage 1
```
If your changes impact test output, you can use `--bless` to automatically
update the `.stderr` files of the affected tests:
```sh
./x.py test src/test/ui --keep-stage 1 --bless
```
While working on the compiler, it can be helpful to see if the code just
compiles (similar to `cargo check`) without actually building it. You can do
this with:
```sh
./x.py check
```
This command is really fast (relative to the other commands). It usually
completes in a couple of minutes on my laptop. **A common workflow when working
on the compiler is to make changes and repeatedly check with `./x.py check`.
Then, run the tests as shown above when you think things should work.**
Finally, the CI ensures that the codebase is using consistent style. To format
the code:
```sh
# Actually format
./x.py fmt
# Just check formatting, exit with error
./x.py fmt --check
```
*Note*: we don't use stable `rustfmt`; we use a pinned version with a special
config, so this may result in different style from normal `rustfmt` if you have
format-on-save turned on. It's a good habit to run `./x.py fmt` before every
commit, as this reduces conflicts later. The pinned version is built under
`build/<target>/stage0/bin/rustfmt`, so if you want, you can use it for a
single file or for format-on-save in your editor, which can be faster than `./x.py fmt`.
You'll have to pass the <!-- date: 2021-09 --> `--edition=2021` argument
yourself when calling `rustfmt` directly.
One last thing: you can use `RUSTC_LOG=XXX` to get debug logging. [Read more
here][logging]. Notice the `C` in `RUSTC_LOG`. Other than that, it uses normal
[`env_logger`][envlog] or `tracing` syntax.
[envlog]: https://crates.io/crates/env_logger
[logging]: ./tracing.md
### Building and Testing `std`/`core`/`alloc`/`test`/`proc_macro`/etc.
As before, technically the proper way to build one of these libraries is to use
the stage-2 compiler, which of course requires a 2-stage build, described above
(`./x.py build`).
In practice, though, you don't need to build the compiler unless you are
planning to use a recently added nightly feature. Instead, you can just build
stage 0, which uses the current beta compiler.
```sh
./x.py build --stage 0
```
```sh
./x.py test --stage 0 library/std
```
(The same works for `library/alloc`, `library/core`, etc.)
### Building and Testing `rustdoc`
`rustdoc` uses `rustc` internals (and, of course, the standard library), so you
will have to build the compiler and `std` once before you can build `rustdoc`.
As before, you can use `./x.py build` to do this. The first time you build,
the stage-1 compiler will also be built.
```sh
# First build
./x.py build
# Subsequent builds
./x.py build --keep-stage 1
```
As with the compiler, you can do a fast check build:
```sh
./x.py check
```
Rustdoc has two types of tests: content tests and UI tests.
```sh
# Content tests
./x.py test src/test/rustdoc
# UI tests
./x.py test src/test/rustdoc-ui
# Both at once
./x.py test src/test/rustdoc src/test/rustdoc-ui
```
### Contributing code to other Rust projects ### Contributing code to other Rust projects

10
src/rustdoc.md
View File

@ -1,6 +1,9 @@
# Rustdoc overview # Rustdoc overview
Rustdoc actually uses the rustc internals directly. It lives in-tree with the `rustdoc` uses `rustc` internals (and, of course, the standard library), so you
will have to build the compiler and `std` once before you can build `rustdoc`.
`rustdoc` lives in-tree with the
compiler and standard library. This chapter is about how it works. compiler and standard library. This chapter is about how it works.
For information about Rustdoc's features and how to use them, see For information about Rustdoc's features and how to use them, see
the [Rustdoc book](https://doc.rust-lang.org/nightly/rustdoc/). the [Rustdoc book](https://doc.rust-lang.org/nightly/rustdoc/).
@ -39,9 +42,11 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
* Run `./x.py setup tools` before getting started. This will configure `x.py` * Run `./x.py setup tools` before getting started. This will configure `x.py`
with nice settings for developing rustdoc and other tools, including with nice settings for developing rustdoc and other tools, including
downloading a copy of rustc rather than building it. downloading a copy of rustc rather than building it.
* Use `./x.py check` to quickly check for compile errors.
* Use `./x.py build` to make a usable * Use `./x.py build` to make a usable
rustdoc you can run on other projects. rustdoc you can run on other projects.
* Add `library/test` to be able to use `rustdoc --test`. * Add `library/test` to be able to use `rustdoc --test`.
* Add `--keep-stage 1` on subsequent runs to avoid rebuilding some things.
* Run `rustup toolchain link stage2 build/$TARGET/stage2` to add a * Run `rustup toolchain link stage2 build/$TARGET/stage2` to add a
custom toolchain called `stage2` to your rustup environment. After custom toolchain called `stage2` to your rustup environment. After
running that, `cargo +stage2 doc` in any directory will build with running that, `cargo +stage2 doc` in any directory will build with
@ -52,7 +57,8 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
* If you want to copy those docs to a webserver, copy all of * If you want to copy those docs to a webserver, copy all of
`build/$TARGET/doc`, since that's where the CSS, JS, fonts, and landing `build/$TARGET/doc`, since that's where the CSS, JS, fonts, and landing
page are. page are.
* Use `./x.py test src/test/rustdoc*` to run the tests using a stage1 rustdoc. * Use `./x.py test src/test/rustdoc*` to run the tests using a stage1
rustdoc.
* See [Rustdoc internals] for more information about tests. * See [Rustdoc internals] for more information about tests.
## Code structure ## Code structure

11
src/tests/running.md
View File

@ -36,7 +36,11 @@ modifying rustc to see if things are generally working correctly would be the
following: following:
```bash ```bash
# First build
./x.py test src/test/ui ./x.py test src/test/ui
# Subsequent builds (optional, but can save time)
./x.py test src/test/ui --keep-stage 1
``` ```
This will run the `ui` test suite. Of course, the choice This will run the `ui` test suite. Of course, the choice
@ -92,6 +96,13 @@ tests for components you did not change at all.
build; therefore, while the tests **usually** work fine with stage 1, build; therefore, while the tests **usually** work fine with stage 1,
there are some limitations. there are some limitations.
### Run all tests using a stage 2 compiler
```bash
./x.py test --stage 2
```
You almost never need to do this.
## Run unit tests on the compiler/library ## Run unit tests on the compiler/library
You may want to run unit tests on a specific file with following: You may want to run unit tests on a specific file with following: