From bc8d6588043835d4ebafb32e436a2ba5a8af413d Mon Sep 17 00:00:00 2001 From: mark Date: Mon, 1 Jun 2020 21:58:37 -0500 Subject: [PATCH 01/22] start a getting started guide --- src/SUMMARY.md | 1 + src/getting-started.md | 223 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 224 insertions(+) create mode 100644 src/getting-started.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 0a9dc7773..b6f01cfba 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -6,6 +6,7 @@ - [Part 1: Building, debugging, and contributing to Rustc](./part-1-intro.md) - [About the compiler team](./compiler-team.md) + - [Getting Started](./getting-started.md) - [How to Build and Run the Compiler](./building/how-to-build-and-run.md) - [Suggested Workflows](./building/suggested.md) - [Bootstrapping](./building/bootstrapping.md) diff --git a/src/getting-started.md b/src/getting-started.md new file mode 100644 index 000000000..c82964463 --- /dev/null +++ b/src/getting-started.md @@ -0,0 +1,223 @@ +# Getting Started + +This documentation is _not_ intended to be comprehensive; it is meant to be a +quick guide for the most useful things. For more information, [see this +chapter](./building/how-to-build-and-run.md). + +## Asking Questions + +The compiler team (or "t-compiler") usually hangs out in Zulip [in this +"stream"][z]; it will be easiest to get questions answered there. + +[z]: https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler + +**Please ask questions!** A lot of people report feeling that they are "wasting +expert time", but nobody on t-compiler feels this way. Contributors are +important to us. + +Also, if you feel comfortable, prefer public topics, as this means others can +see the questions and answers, and perhaps even integrate them back into this +guide :) + +### Experts + +Not all `t-compiler` members are experts on all parts of `rustc`; it's a pretty +large project. To find out who has expertise on different parts of the +compiler, [consult this "experts map"][map]. + +It's not perfectly complete, though, so please also feel free to ask questions +even if you can't figure out who to ping. + +[map]: https://github.com/rust-lang/compiler-team/blob/master/content/experts/map.toml + +### Etiquette + +We do ask that you be mindful to include as much useful information as you can +in your question, but we recognize this can be hard if you are unfamiliar with +contributing to Rust. + +Just pinging someone without providing any context can be a bit annoying and +just create noise, so we ask that you be mindful of the fact that the +`t-compiler` folks get a lot of pings in a day. + +## Cloning and Building + +The main repository is [`rust-lang/rust`][repo]. This contains the compiler, +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 + +There are also a bunch of submodules for things like LLVM, `clippy`, `miri`, +etc. You don't need to clone these immediately, but the build tool will +automatically clone and sync them (more later). + +[**Take a look at the "Suggested Workflows" chapter for some helpful +advice.**][suggested] + +[suggested]: ./building/suggested.md + +### System Requirements + +[**See this chapter for detailed software requirements.**](./building/prerequisites.md) +Most notably, you will need python 2 to run `x.py`. + +There are no hard hardware requirements, but building the compiler is +computationally expensive, so a beefier machine will help, and I wouldn't +recommend building try to build on a Raspberry Pi :P + +- x86 and ARM are both supported (TODO: confirm) +- Recommended 30GB of free disk space; otherwise, you will have to keep + clearing incremental caches. +- Recommended >=8GB RAM +- Recommended >=2 cores; more cores really helps +- You will need an internet connection to build; the bootstrapping process + involves updating git submodules and downloading a beta compiler. It doesn't + need to be super fast, but that can help. + +Building the compiler take more than half an hour on my moderately powerful +laptop (even longer if you build LLVM). + +### Cloning + +You can just do a normal git clone: + +```shell +git clone https://github.com/rust-lang/rust.git +``` + +You don't need to clone the submodules at this time. + +**Pro tip**: if you contribute often, you may want to look at the git worktrees +tip in [this chapter][suggested]. + +### Configuring the Compiler + +The compiler has a configuration file which contains a ton of settings. We will +provide some recommendations here that should work for most, but [check out +this chapter for more info][config]. + +[config]: ./building/how-to-build-and-run.html#create-a-configtoml + +In the top level of the repo: + +```shell +cp config.toml.example config.toml +``` + +Then, edit `config.toml`. You will need to search for, uncomment, and update +the following settings: + +- `debug = true`: enables debug symbols and `debug!` logging, takes a bit longer to compile. +- `incremental = true`: enables incremental compilation of the compiler itself. + This is turned off by default because it's technically unsound. Sometimes + this will cause weird crashes, but it can really speed things up. +- `llvm-config`: enable building with system LLVM. [See this chapter][sysllvm] + for more info. This avoids having to build LLVM, which takes forever. + +[sysllvm]: ./building/suggested.html#building-with-system-llvm + +### `./x.py` Intro + +`rustc` is a bootstrapping compiler because it is written in Rust. Where do you +get do you get the original compiler from? We use the current `beta` compiler +to build the compiler. Then, we use that compiler to build itself. Thus, +`rustc` has a 2-stage build. + +We have a special tool `./x.py` that drives this process. It is used for +compiling the compiler, the standard libraries, and `rustdoc`. It is also used +for driving CI and building the final release artifacts. + +### Building and Testing `rustc` + +For most contributions, you only need to build stage 1, which saves a lot of time. +After updating `config.toml`, as mentioned above, you can use `./x.py`: + +```shell +# Build the compiler (stage 1) +./x.py build --stage 1 +``` + +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. + +To run the compiler's UI test (the bulk of the test suite): + +``` +# UI tests +./x.py test --stage 1 src/test/ui +``` + +This will build the compiler first, if needed. + +This will be enough for most people. Notably, though, it mostly tests the +compiler frontend, not codegen or debug info. You can read more about the +different test suites [in this chapter][testing]. + +[testing]: https://rustc-dev-guide.rust-lang.org/tests/intro.html + +If you only want to check that the compiler builds (without actually building +it) you can run the following: + +```shell +./x.py check +``` + +To format the code: + +```shell +# Actually format +./x.py fmt + +# Just check formatting, exit with error +./x.py fmt --check +``` + +You can use `RUSTC_LOG=XXX` to get debug logging. [Read more here][logging]. + +[logging]: ./compiler-debugging.html#getting-logging-output + +### Building and Testing `std`/`core`/`alloc`/`test`/`proc_macro`/etc. + +TODO + +### Building and Testing `rustdoc` + +TODO + +### Contributing code to other Rust projects + +TODO: talk about things like miri, clippy, chalk, etc + +## Contributor Procedures + +There are some official procedures to know about. This is a tour of the +highlights, but there are a lot more details, which we will link to below. + +### Bug Fixes + +TODO: talk about bors, highfive + +### New Features + +TODO: talk about RFCs, stabilization + +### Breaking Changes + +TODO: talk about crater, FCP, etc + +### Major Changes + +TODO: talk about MCP + +### Performance + +TODO: Talk about perf runs + +## Other Resources + +- This guide: talks about how `rustc` works +- [The t-compiler zulip][z] +- [The compiler's documentation (rustdocs)](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/) + +TODO: am I missing any? From 3af22dc8907e44ef5467b70c9957bb23fffa0987 Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Tue, 2 Jun 2020 13:29:06 -0500 Subject: [PATCH 02/22] Typo fixes Co-authored-by: Camelid <37223377+camelid@users.noreply.github.com> --- src/getting-started.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/getting-started.md b/src/getting-started.md index c82964463..3c4a541a9 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -60,11 +60,11 @@ advice.**][suggested] ### System Requirements [**See this chapter for detailed software requirements.**](./building/prerequisites.md) -Most notably, you will need python 2 to run `x.py`. +Most notably, you will need Python 2 to run `x.py`. There are no hard hardware requirements, but building the compiler is computationally expensive, so a beefier machine will help, and I wouldn't -recommend building try to build on a Raspberry Pi :P +recommend trying to build on a Raspberry Pi :P - x86 and ARM are both supported (TODO: confirm) - Recommended 30GB of free disk space; otherwise, you will have to keep @@ -75,7 +75,7 @@ recommend building try to build on a Raspberry Pi :P involves updating git submodules and downloading a beta compiler. It doesn't need to be super fast, but that can help. -Building the compiler take more than half an hour on my moderately powerful +Building the compiler takes more than half an hour on my moderately powerful laptop (even longer if you build LLVM). ### Cloning @@ -120,7 +120,7 @@ the following settings: ### `./x.py` Intro `rustc` is a bootstrapping compiler because it is written in Rust. Where do you -get do you get the original compiler from? We use the current `beta` compiler +get the original compiler from? We use the current beta compiler to build the compiler. Then, we use that compiler to build itself. Thus, `rustc` has a 2-stage build. From cb59548e65c05d50650054f124269446b5da4079 Mon Sep 17 00:00:00 2001 From: mark Date: Tue, 2 Jun 2020 13:44:20 -0500 Subject: [PATCH 03/22] address some review comments --- src/getting-started.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/src/getting-started.md b/src/getting-started.md index 3c4a541a9..bc8d6648a 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -69,14 +69,19 @@ recommend trying to build on a Raspberry Pi :P - x86 and ARM are both supported (TODO: confirm) - Recommended 30GB of free disk space; otherwise, you will have to keep clearing incremental caches. -- Recommended >=8GB RAM -- Recommended >=2 cores; more cores really helps +- Recommended >=8GB RAM. +- Recommended >=2 cores; more cores really helps. - You will need an internet connection to build; the bootstrapping process involves updating git submodules and downloading a beta compiler. It doesn't need to be super fast, but that can help. Building the compiler takes more than half an hour on my moderately powerful -laptop (even longer if you build LLVM). +laptop. The first time you build the compiler, LLVM will also be built unless +you use system LLVM (see below). + +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 +concurrent jobs. ### Cloning @@ -113,7 +118,7 @@ the following settings: This is turned off by default because it's technically unsound. Sometimes this will cause weird crashes, but it can really speed things up. - `llvm-config`: enable building with system LLVM. [See this chapter][sysllvm] - for more info. This avoids having to build LLVM, which takes forever. + for more info. This avoids building LLVM, which can take a while. [sysllvm]: ./building/suggested.html#building-with-system-llvm From 4011af01fd2071437012bff438332bd1299170e9 Mon Sep 17 00:00:00 2001 From: mark Date: Tue, 2 Jun 2020 14:25:30 -0500 Subject: [PATCH 04/22] write about processes --- src/getting-started.md | 108 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 102 insertions(+), 6 deletions(-) diff --git a/src/getting-started.md b/src/getting-started.md index bc8d6648a..1ec7b1b26 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -199,25 +199,121 @@ TODO: talk about things like miri, clippy, chalk, etc There are some official procedures to know about. This is a tour of the highlights, but there are a lot more details, which we will link to below. -### Bug Fixes +### Code Review -TODO: talk about bors, highfive +When you open a PR on the `rust-lang/rust` repo, a bot called `@highfive` will +automatically assign a reviewer to the PR. The reviewer is the person that will +approve the PR to be tested and merged. If you want a specific reviewer (e.g. a +team member you've been working with), you can specifically request them by +writing `r? @user` (e.g. `r? @eddyb`) in either the original post or a followup +comment. + +The reviewer may request some changes using the GitHub code review interface. +They may also request special procedures (such as a crater run; see below) for +some PRs. + +When the PR is ready to be merged, the reviewer will issue a command to +`@bors`, the CI bot. Usually, this is `@bors r+` or `@bors r=@user` to approve +a PR (there are few other commands, but they are less relevant here). This puts +the PR in [bors's queue][bors] to be tested and merged. Be patient; this can take a +while and the queue can sometimes be long. PRs are never merged by hand. + +[bors]: https://buildbot2.rust-lang.org/homu/queue/rust + +### Bug Fixes or "Normal" code changes + +For most PRs, no special procedures are needed. You can just open a PR, and it +will be reviewed, approved, and merged. This includes most bug fixes, +refactorings, and other user-invisible changes. The next few sections talk +about exceptions to this rule. ### New Features -TODO: talk about RFCs, stabilization +Rust has strong backwards-compatibility guarantees. Thus, new features can't +just be implemented directly in stable Rust. Instead, we have 3 release +channels: stable, beta, and nightly. + +- **Stable**: this is the latest stable release for general usage. +- **Beta**: this is the next release (will be stable within 6 weeks). +- **Nightly**: follows the `master` branch of the repo. This is the only + channel where unstable, incomplete, or experimental features are usable with + feature gates. + +In order to implement a new feature, usually you will need to go through [the +RFC process][rfc] to propose a design, have discussions, etc. In some cases, +small features can be added with only an FCP (see below). If in doubt, ask the +compiler, language, or libs team (whichever is most relevant). + +[rfc]: https://github.com/rust-lang/rfcs/blob/master/README.md + +After a feature is approved to be added, a tracking issue is created on the +`rust-lang/rust` repo, which tracks the progress towards the implementation of +the feature, any bugs reported, and eventually stabilization. + +The feature then needs to be implemented behind a feature gate, which prevents +it from being accidentally used. + +Finally, somebody may propose stabilizing the feature in an upcoming version of +Rust. This requires an FCP (see below) to get the approval of the relevant teams. + +After that, the feature gate can be removed and the feature turned on for all users. + +[For more details on this process, see this chapter.](./implementing_new_features.md) ### Breaking Changes -TODO: talk about crater, FCP, etc +As mentioned above, Rust has strong backwards-compatibility guarantees. To this +end, we are reluctant to make breaking changes. However, sometimes they are +needed to correct compiler bugs (e.g. code that compiled but should not). + +Depending on the scale of the breakage, there are a few different actions that +can be taken. If the reviewer believes the breakage is very minimal (i.e. very +unlikely to be actually encountered by users), they may just merge the change. +More often, they will request a Final Comment Period (FCP), which calls for +rough consensus among the members of a relevant team. The team members can +discuss the issue and either accept, reject, or request changes on the PR. + +If the scale of breakage is large, a deprecation warning may be needed. This is +a warning that the compiler will display to users whose code will break in the +future. After some time, an FCP can be used to move forward with the actual +breakage. + +If the scale of breakage is unknown, a team member or contributor may request a +[crater] run. This is a bot that will compile all crates.io crates and many +public github repos with the compiler with your changes. A report will then be +generated with crates that ceased to compile with or began to compile with your +changes. Crater runs can take a few days to complete. + +[crater]: https://github.com/rust-lang/crater ### Major Changes -TODO: talk about MCP +The compiler team has a special process for large changes, whether or not they +cause breakage. This process is call Major Change Proposal (MCP). MCP is a +relatively lightweight mechanism for getting feedback on large changes to the +compiler (as opposed to a full RFC or a design meeting with the team). + +Example of things that might require MCPs include major refactorings, changes +to important types, or important changes to how the compiler does something. + +**When in doubt, ask on [zulip][z]. We would hate for you to put a lot of work +into a PR that ends up not getting merged!** ### Performance -TODO: Talk about perf runs +Compiler performance is important. We have put a lot of effort over the last +few years into [gradually improving it][perfdash]. + +[perfdash]: https://perf.rust-lang.org/dashboard.html + +If you suspect that your change may cause a performance regression (or +improvement), you can request a "perf run" (your reviewer may also request one +before approving). This is yet another bot that will compile a collection of +benchmarks on a compiler with your changes. The numbers are reported +[here][perf], and you can see a comparison of your changes against the latest +master. + +[perf]: https://perf.rust-lang.org/dashboard.html ## Other Resources From bde0b6bbaa7d6f97c3bad833a932c5fbc40f1412 Mon Sep 17 00:00:00 2001 From: mark Date: Tue, 2 Jun 2020 14:45:37 -0500 Subject: [PATCH 05/22] some minor updates --- src/getting-started.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/src/getting-started.md b/src/getting-started.md index 1ec7b1b26..4207fd1ee 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -67,8 +67,9 @@ computationally expensive, so a beefier machine will help, and I wouldn't recommend trying to build on a Raspberry Pi :P - x86 and ARM are both supported (TODO: confirm) -- Recommended 30GB of free disk space; otherwise, you will have to keep - clearing incremental caches. +- Recommended >=30GB of free disk space; otherwise, you will have to keep + clearing incremental caches. More space is better, the compiler is a bit of a + hog; it's a problem we are aware of. - Recommended >=8GB RAM. - Recommended >=2 cores; more cores really helps. - You will need an internet connection to build; the bootstrapping process @@ -146,7 +147,7 @@ After updating `config.toml`, as mentioned above, you can use `./x.py`: 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. -To run the compiler's UI test (the bulk of the test suite): +To run the compiler's UI test suite (the bulk of the test suite): ``` # UI tests @@ -227,6 +228,13 @@ will be reviewed, approved, and merged. This includes most bug fixes, refactorings, and other user-invisible changes. The next few sections talk about exceptions to this rule. +Also, note that is perfectly acceptable to open WIP PRs or GitHub [Draft +PRs][draft]. Some people prefer to do this so they can get feedback along the +way or share their code with a collaborator. Others do this so they can utilize +the CI to build and test their PR (e.g. if you are developing on a laptop). + +[draft]: https://github.blog/2019-02-14-introducing-draft-pull-requests/ + ### New Features Rust has strong backwards-compatibility guarantees. Thus, new features can't From ddef3e22e03452421ac867c6a342edabd3d1a21f Mon Sep 17 00:00:00 2001 From: mark Date: Tue, 2 Jun 2020 14:57:37 -0500 Subject: [PATCH 06/22] a couple more small changes --- src/SUMMARY.md | 2 +- src/getting-started.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index b6f01cfba..9513376e9 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -5,8 +5,8 @@ --- - [Part 1: Building, debugging, and contributing to Rustc](./part-1-intro.md) - - [About the compiler team](./compiler-team.md) - [Getting Started](./getting-started.md) + - [About the compiler team](./compiler-team.md) - [How to Build and Run the Compiler](./building/how-to-build-and-run.md) - [Suggested Workflows](./building/suggested.md) - [Bootstrapping](./building/bootstrapping.md) diff --git a/src/getting-started.md b/src/getting-started.md index 4207fd1ee..5d78e416b 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -272,7 +272,8 @@ After that, the feature gate can be removed and the feature turned on for all us As mentioned above, Rust has strong backwards-compatibility guarantees. To this end, we are reluctant to make breaking changes. However, sometimes they are -needed to correct compiler bugs (e.g. code that compiled but should not). +needed to correct compiler bugs (e.g. code that compiled but should not) or +make progress on some features. Depending on the scale of the breakage, there are a few different actions that can be taken. If the reviewer believes the breakage is very minimal (i.e. very From 2301cd5b84bb6153b5a82c18f343e6d00582f7f1 Mon Sep 17 00:00:00 2001 From: mark Date: Tue, 2 Jun 2020 19:28:36 -0500 Subject: [PATCH 07/22] mention incremental disk space --- src/getting-started.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/getting-started.md b/src/getting-started.md index 5d78e416b..3c3781da8 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -84,6 +84,11 @@ 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 concurrent jobs. +Also, if you don't have too much free disk space, you may want to turn off +incremental compilation (see the "Configuring" section below). This will make +compilation take longer, but will save a ton of space from the incremental +caches. + ### Cloning You can just do a normal git clone: From 10f16cf809d28b1fdcba990b97c4e699d7d62385 Mon Sep 17 00:00:00 2001 From: mark Date: Tue, 2 Jun 2020 19:53:54 -0500 Subject: [PATCH 08/22] fix link --- src/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/getting-started.md b/src/getting-started.md index 3c3781da8..9fa76817a 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -327,7 +327,7 @@ benchmarks on a compiler with your changes. The numbers are reported [here][perf], and you can see a comparison of your changes against the latest master. -[perf]: https://perf.rust-lang.org/dashboard.html +[perf]: https://perf.rust-lang.org ## Other Resources From a9b72eba415604a7da1479828bf62a3e4fad6a3e Mon Sep 17 00:00:00 2001 From: mark Date: Fri, 5 Jun 2020 11:24:47 -0500 Subject: [PATCH 09/22] add a bit more --- src/getting-started.md | 66 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 62 insertions(+), 4 deletions(-) diff --git a/src/getting-started.md b/src/getting-started.md index 9fa76817a..2d11edf8e 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -147,16 +147,24 @@ After updating `config.toml`, as mentioned above, you can use `./x.py`: ```shell # Build the compiler (stage 1) ./x.py build --stage 1 + +# Subsequent builds +./x.py build --stage 1 --keep-stage 1 ``` 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. + To run the compiler's UI test suite (the bulk of the test suite): ``` # UI tests -./x.py test --stage 1 src/test/ui +./x.py test --stage 1 src/test/ui [--keep-stage 1] ``` This will build the compiler first, if needed. @@ -190,15 +198,65 @@ You can use `RUSTC_LOG=XXX` to get debug logging. [Read more here][logging]. ### Building and Testing `std`/`core`/`alloc`/`test`/`proc_macro`/etc. -TODO +To contribute to `libstd`, 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. + +```sh +./x.py build --stage 0 src/libstd +``` + +TODO: how to test? ### Building and Testing `rustdoc` -TODO +`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`. + +The following command will build all of them. Stage 1 should be sufficient, +even though the release version will use the full 2-stage build. + +```sh +# First build +./x.py build --stage 1 src/tools/rustdoc + +# Subsequent builds +./x.py build --stage 1 --keep-stage 1 src/tools/rustdoc +``` + +You can also use `./x.py check` here to do a fast check build. + +TODO: how to test? ### Contributing code to other Rust projects -TODO: talk about things like miri, clippy, chalk, etc +There are a bunch of other projects that one can contribute too outside of the +`rust-lang/rust` repo, including `clippy`, `miri`, `chalk`, and many others. + +These repos might have their own contributing guidelines and procedures. Many +of them are owned by working groups (e.g. `chalk` is largely owned by +WG-traits). For more info, see the documentation in those repos' READMEs. + +### Other ways to contribute + +There are a bunch of other ways you can contribute, especially if you don't +feel comfortable jumping straight into the large `rust-lang/rust` codebase. + +The following tasks are doable without much background knowledge but are +incredibly helpful: + +- [ICE-breakers Cleanup crew][iceb]: find minimal reproductions of ICEs, bisect + regressions, etc. This is a way of helping that saves a ton of time for + others to fix an error later. +- Writing documentation: if you are feeling a bit more intrepid, you could try + to read a part of the code and write doc comments for it. This will help you + to learn some part of the compiler while also producing a useful artifact! +- [Working groups][wg]: there are a bunch of working groups on a wide variety + of rust-related things. + +[iceb]: ./ice-breaker/cleanup-crew.md +[wg]: https://rust-lang.github.io/compiler-team/working-groups/ + ## Contributor Procedures From f4a55adb26448c59b9061fc23d563ae8e751f0ed Mon Sep 17 00:00:00 2001 From: mark Date: Fri, 5 Jun 2020 11:25:48 -0500 Subject: [PATCH 10/22] add note on submodules --- src/getting-started.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/src/getting-started.md b/src/getting-started.md index 2d11edf8e..d5a4c51b3 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -97,7 +97,16 @@ You can just do a normal git clone: git clone https://github.com/rust-lang/rust.git ``` -You don't need to clone the submodules at this time. +You don't need to clone the submodules at this time. 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 +``` **Pro tip**: if you contribute often, you may want to look at the git worktrees tip in [this chapter][suggested]. From 3e6a8b83e6a0bcecc36748e52890b948f3bc3de4 Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Fri, 5 Jun 2020 11:29:03 -0500 Subject: [PATCH 11/22] Apply suggestions from code review Co-authored-by: Camelid <37223377+camelid@users.noreply.github.com> --- src/getting-started.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/getting-started.md b/src/getting-started.md index d5a4c51b3..21f52ca9c 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -132,7 +132,7 @@ the following settings: - `incremental = true`: enables incremental compilation of the compiler itself. This is turned off by default because it's technically unsound. Sometimes this will cause weird crashes, but it can really speed things up. -- `llvm-config`: enable building with system LLVM. [See this chapter][sysllvm] +- `llvm-config`: enables building with system LLVM. [See this chapter][sysllvm] for more info. This avoids building LLVM, which can take a while. [sysllvm]: ./building/suggested.html#building-with-system-llvm @@ -274,7 +274,7 @@ highlights, but there are a lot more details, which we will link to below. ### Code Review -When you open a PR on the `rust-lang/rust` repo, a bot called `@highfive` will +When you open a PR on the `rust-lang/rust` repo, a bot called `@rust-highfive` will automatically assign a reviewer to the PR. The reviewer is the person that will approve the PR to be tested and merged. If you want a specific reviewer (e.g. a team member you've been working with), you can specifically request them by @@ -334,7 +334,7 @@ The feature then needs to be implemented behind a feature gate, which prevents it from being accidentally used. Finally, somebody may propose stabilizing the feature in an upcoming version of -Rust. This requires an FCP (see below) to get the approval of the relevant teams. +Rust. This requires a Final Comment Period (see below) to get the approval of the relevant teams. After that, the feature gate can be removed and the feature turned on for all users. @@ -400,6 +400,6 @@ master. - This guide: talks about how `rustc` works - [The t-compiler zulip][z] -- [The compiler's documentation (rustdocs)](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/) +- [The compiler's documentation (rustdocs)](https://doc.rust-lang.org/nightly/nightly-rustc/) TODO: am I missing any? From 8ad947b47cc68bb20480daf55899524ec5c560eb Mon Sep 17 00:00:00 2001 From: mark Date: Fri, 5 Jun 2020 11:28:36 -0500 Subject: [PATCH 12/22] add forge --- src/getting-started.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/getting-started.md b/src/getting-started.md index 21f52ca9c..dfc0a843c 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -401,5 +401,6 @@ master. - This guide: talks about how `rustc` works - [The t-compiler zulip][z] - [The compiler's documentation (rustdocs)](https://doc.rust-lang.org/nightly/nightly-rustc/) +- [The Forge](https://forge.rust-lang.org/) has more documentation about various procedures. TODO: am I missing any? From 62e7f0e9c3671bd8cc2c592c5936dffb2257f5fa Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Wed, 17 Jun 2020 12:51:41 -0500 Subject: [PATCH 13/22] Apply suggestions from code review Co-authored-by: Camelid <37223377+camelid@users.noreply.github.com> Co-authored-by: Joshua Nelson Co-authored-by: Phil Hansch --- src/getting-started.md | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/src/getting-started.md b/src/getting-started.md index dfc0a843c..d7d7f9314 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -173,7 +173,11 @@ To run the compiler's UI test suite (the bulk of the test suite): ``` # UI tests -./x.py test --stage 1 src/test/ui [--keep-stage 1] +# First build +./x.py test --stage 1 src/test/ui + +# Subsequent builds +./x.py test --stage 1 src/test/ui --keep-stage 1 ``` This will build the compiler first, if needed. @@ -215,7 +219,9 @@ stage 0. ./x.py build --stage 0 src/libstd ``` -TODO: how to test? +```sh +./x.py test --stage 0 src/libstd +``` ### Building and Testing `rustdoc` @@ -235,11 +241,22 @@ even though the release version will use the full 2-stage build. You can also use `./x.py check` here to do a fast check build. -TODO: how to test? +Rustdoc has two types of tests: content tests and UI tests. + +```sh +# Content tests +./x.py test --stage 1 src/test/rustdoc + +# UI tests +./x.py test --stage 1 src/test/rustdoc-ui + +# Both at once +./x.py test --stage 1 src/test/rustdoc* +``` ### Contributing code to other Rust projects -There are a bunch of other projects that one can contribute too outside of the +There are a bunch of other projects that you can contribute to outside of the `rust-lang/rust` repo, including `clippy`, `miri`, `chalk`, and many others. These repos might have their own contributing guidelines and procedures. Many @@ -300,7 +317,7 @@ will be reviewed, approved, and merged. This includes most bug fixes, refactorings, and other user-invisible changes. The next few sections talk about exceptions to this rule. -Also, note that is perfectly acceptable to open WIP PRs or GitHub [Draft +Also, note that it is perfectly acceptable to open WIP PRs or GitHub [Draft PRs][draft]. Some people prefer to do this so they can get feedback along the way or share their code with a collaborator. Others do this so they can utilize the CI to build and test their PR (e.g. if you are developing on a laptop). @@ -370,7 +387,7 @@ changes. Crater runs can take a few days to complete. ### Major Changes The compiler team has a special process for large changes, whether or not they -cause breakage. This process is call Major Change Proposal (MCP). MCP is a +cause breakage. This process is called a Major Change Proposal (MCP). MCP is a relatively lightweight mechanism for getting feedback on large changes to the compiler (as opposed to a full RFC or a design meeting with the team). @@ -402,5 +419,6 @@ master. - [The t-compiler zulip][z] - [The compiler's documentation (rustdocs)](https://doc.rust-lang.org/nightly/nightly-rustc/) - [The Forge](https://forge.rust-lang.org/) has more documentation about various procedures. +- `#contribute`, `#compiler`, and `#rustdoc` on [Discord](https://discord.gg/rust-lang). TODO: am I missing any? From 8d742b2730982c12ed4bc865fd4242569112eb50 Mon Sep 17 00:00:00 2001 From: mark Date: Wed, 17 Jun 2020 12:53:46 -0500 Subject: [PATCH 14/22] python 3 also --- src/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/getting-started.md b/src/getting-started.md index d7d7f9314..9715403e6 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -60,7 +60,7 @@ advice.**][suggested] ### System Requirements [**See this chapter for detailed software requirements.**](./building/prerequisites.md) -Most notably, you will need Python 2 to run `x.py`. +Most notably, you will need Python 2 or 3 to run `x.py`. There are no hard hardware requirements, but building the compiler is computationally expensive, so a beefier machine will help, and I wouldn't From c37d6bc06c692f574d4abda7502ef099109a6aa4 Mon Sep 17 00:00:00 2001 From: mark Date: Wed, 17 Jun 2020 12:56:57 -0500 Subject: [PATCH 15/22] add a note about disk space --- src/getting-started.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/getting-started.md b/src/getting-started.md index 9715403e6..755034cf2 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -129,9 +129,10 @@ Then, edit `config.toml`. You will need to search for, uncomment, and update the following settings: - `debug = true`: enables debug symbols and `debug!` logging, takes a bit longer to compile. -- `incremental = true`: enables incremental compilation of the compiler itself. - This is turned off by default because it's technically unsound. Sometimes - this will cause weird crashes, but it can really speed things up. +- `incremental = true`: enables incremental compilation of the compiler itself, + which can significantly speed things up. This is turned off by default + because it's technically unsound; sometimes this will cause weird crashes. + Also, it can consume a lot of disk space. - `llvm-config`: enables building with system LLVM. [See this chapter][sysllvm] for more info. This avoids building LLVM, which can take a while. From c645df3e6ef90fba1473d23dae465b711121b390 Mon Sep 17 00:00:00 2001 From: mark Date: Wed, 17 Jun 2020 13:45:55 -0500 Subject: [PATCH 16/22] Slightly reorganize to first present the slow command then the fast commands --- src/getting-started.md | 103 +++++++++++++++++++++++++++++------------ 1 file changed, 74 insertions(+), 29 deletions(-) diff --git a/src/getting-started.md b/src/getting-started.md index 755034cf2..466394577 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -66,7 +66,6 @@ There are no hard hardware requirements, but building the compiler is computationally expensive, so a beefier machine will help, and I wouldn't recommend trying to build on a Raspberry Pi :P -- x86 and ARM are both supported (TODO: confirm) - Recommended >=30GB of free disk space; otherwise, you will have to keep clearing incremental caches. More space is better, the compiler is a bit of a hog; it's a problem we are aware of. @@ -125,14 +124,15 @@ In the top level of the repo: cp config.toml.example config.toml ``` -Then, edit `config.toml`. You will need to search for, uncomment, and update +Then, edit `config.toml`. You may want to search for, uncomment, and update the following settings: - `debug = true`: enables debug symbols and `debug!` logging, takes a bit longer to compile. - `incremental = true`: enables incremental compilation of the compiler itself, which can significantly speed things up. This is turned off by default - because it's technically unsound; sometimes this will cause weird crashes. - Also, it can consume a lot of disk space. + because it's technically unsound; sometimes it will cause weird crashes. + Also, it can consume a lot of disk space. This has the same effect as the + `-i` or `--incremental` flags. - `llvm-config`: enables building with system LLVM. [See this chapter][sysllvm] for more info. This avoids building LLVM, which can take a while. @@ -140,19 +140,44 @@ the following settings: ### `./x.py` Intro -`rustc` is a bootstrapping compiler because it is written in Rust. Where do you +`rustc` is a _bootstrapping_ compiler because it is written in Rust. Where do you get the original compiler from? We use the current beta compiler to build the compiler. Then, we use that compiler to build itself. Thus, -`rustc` has a 2-stage build. +`rustc` has a 2-stage build. You can read more about bootstrapping +[here][boot], but you don't need more to contribute. + +[boot]: ./building/bootstrapping.md We have a special tool `./x.py` that drives this process. It is used for compiling the compiler, the standard libraries, and `rustdoc`. It is also used for driving CI and building the final release artifacts. +Unfortunately, a proper 2-stage build takes a long time depending on your +hardware, but it is the only correct way to build everything (e.g. it's what +the CI and release processes use). **However, in most cases, you can get by +without a full 2-stage build**. In the following section, we give instructions +for how to do "the correct thing", but then we also give various tips to speed +things up. + ### Building and Testing `rustc` -For most contributions, you only need to build stage 1, which saves a lot of time. -After updating `config.toml`, as mentioned above, you can use `./x.py`: +To do a full 2-stage build of the whole compiler, you should run this (after +updating `config.toml` as mentioned above): + +```sh +./x.py build +``` + +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: ```shell # Build the compiler (stage 1) @@ -170,10 +195,16 @@ 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. -To run the compiler's UI test suite (the bulk of the test suite): +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]. + +[uitests]: ./tests/adding.html#ui +[testing]: https://rustc-dev-guide.rust-lang.org/tests/intro.html ``` -# UI tests # First build ./x.py test --stage 1 src/test/ui @@ -181,22 +212,19 @@ To run the compiler's UI test suite (the bulk of the test suite): ./x.py test --stage 1 src/test/ui --keep-stage 1 ``` -This will build the compiler first, if needed. - -This will be enough for most people. Notably, though, it mostly tests the -compiler frontend, not codegen or debug info. You can read more about the -different test suites [in this chapter][testing]. - -[testing]: https://rustc-dev-guide.rust-lang.org/tests/intro.html - -If you only want to check that the compiler builds (without actually building -it) you can run the following: +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: ```shell ./x.py check ``` -To format the code: +This command is really fast (relative to the other commands). It usually +completes in a couple of minutes on my laptop. + +Finally, the CI ensures that the codebase is using consistent style. To format +the code: ```shell # Actually format @@ -206,15 +234,27 @@ To format the code: ./x.py fmt --check ``` -You can use `RUSTC_LOG=XXX` to get debug logging. [Read more here][logging]. +*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. + +On 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] syntax. +[envlog]: https://crates.io/crates/env_logger [logging]: ./compiler-debugging.html#getting-logging-output ### Building and Testing `std`/`core`/`alloc`/`test`/`proc_macro`/etc. -To contribute to `libstd`, you don't need to build the compiler unless you are +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. +stage 0 (i.e. which basically just uses the current beta compiler). ```sh ./x.py build --stage 0 src/libstd @@ -224,13 +264,16 @@ stage 0. ./x.py test --stage 0 src/libstd ``` +(The same works for `src/liballoc`, `src/libcore`, 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 following command will build all of them. Stage 1 should be sufficient, -even though the release version will use the full 2-stage build. +However, in practice, stage 1 should be sufficient. The first time you build, +the stage-1 compiler will also be built. ```sh # First build @@ -240,7 +283,11 @@ even though the release version will use the full 2-stage build. ./x.py build --stage 1 --keep-stage 1 src/tools/rustdoc ``` -You can also use `./x.py check` here to do a fast check build. +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. @@ -421,5 +468,3 @@ master. - [The compiler's documentation (rustdocs)](https://doc.rust-lang.org/nightly/nightly-rustc/) - [The Forge](https://forge.rust-lang.org/) has more documentation about various procedures. - `#contribute`, `#compiler`, and `#rustdoc` on [Discord](https://discord.gg/rust-lang). - -TODO: am I missing any? From 9417073a3d2bc4b64972cb14afb858eb850188f8 Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Wed, 17 Jun 2020 14:47:47 -0500 Subject: [PATCH 17/22] Better wording Co-authored-by: Camelid <37223377+camelid@users.noreply.github.com> --- src/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/getting-started.md b/src/getting-started.md index 466394577..cb87210ad 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -140,7 +140,7 @@ the following settings: ### `./x.py` Intro -`rustc` is a _bootstrapping_ compiler because it is written in Rust. Where do you +`rustc` is a _bootstrapping_ compiler, which means that it is written in Rust. So where do you get the original compiler from? We use the current beta compiler to build the compiler. Then, we use that compiler to build itself. Thus, `rustc` has a 2-stage build. You can read more about bootstrapping From 7694270788a5924c81639dc273e0d9a2f8cb2ea5 Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Wed, 17 Jun 2020 17:08:42 -0500 Subject: [PATCH 18/22] Apply suggestions from code review Co-authored-by: LeSeulArtichaut --- src/getting-started.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/getting-started.md b/src/getting-started.md index cb87210ad..e7c270079 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -2,7 +2,7 @@ This documentation is _not_ intended to be comprehensive; it is meant to be a quick guide for the most useful things. For more information, [see this -chapter](./building/how-to-build-and-run.md). +chapter on how to build and run the compiler](./building/how-to-build-and-run.md). ## Asking Questions @@ -77,7 +77,7 @@ recommend trying to build on a Raspberry Pi :P 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 system LLVM (see below). +you use your system's LLVM (see below). 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 @@ -140,16 +140,16 @@ the following settings: ### `./x.py` Intro -`rustc` is a _bootstrapping_ compiler, which means that it is written in Rust. So where do you +`rustc` is a _bootstrapping_ compiler, which means that it is written in Rust and thus needs to be compiled by itself. So where do you get the original compiler from? We use the current beta compiler -to build the compiler. Then, we use that compiler to build itself. Thus, +to build a new compiler. Then, we use that compiler to build itself. Thus, `rustc` has a 2-stage build. You can read more about bootstrapping -[here][boot], but you don't need more to contribute. +[here][boot], but you don't need to know much more to contribute. [boot]: ./building/bootstrapping.md We have a special tool `./x.py` that drives this process. It is used for -compiling the compiler, the standard libraries, and `rustdoc`. It is also used +building the compiler, the standard libraries, and `rustdoc`. It is also used for driving CI and building the final release artifacts. Unfortunately, a proper 2-stage build takes a long time depending on your From 922cfa6b636a6abee92eaca38ab61810f1e40796 Mon Sep 17 00:00:00 2001 From: mark Date: Wed, 17 Jun 2020 17:18:34 -0500 Subject: [PATCH 19/22] address review comments --- src/getting-started.md | 41 ++++++++++++++++++++++++----------------- 1 file changed, 24 insertions(+), 17 deletions(-) diff --git a/src/getting-started.md b/src/getting-started.md index e7c270079..b1ed6bc0e 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -77,14 +77,16 @@ recommend trying to build on a Raspberry Pi :P 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 your system's LLVM (see below). +you use your system's LLVM ([see below][configsec]). + +[configsec]: #configuring-the-compiler 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 concurrent jobs. Also, if you don't have too much free disk space, you may want to turn off -incremental compilation (see the "Configuring" section below). This will make +incremental compilation ([see below][configsec]). This will make compilation take longer, but will save a ton of space from the incremental caches. @@ -92,7 +94,7 @@ caches. You can just do a normal git clone: -```shell +```sh git clone https://github.com/rust-lang/rust.git ``` @@ -107,9 +109,6 @@ git submodule update --init --recursive git submodule update ``` -**Pro tip**: if you contribute often, you may want to look at the git worktrees -tip in [this chapter][suggested]. - ### Configuring the Compiler The compiler has a configuration file which contains a ton of settings. We will @@ -120,7 +119,7 @@ this chapter for more info][config]. In the top level of the repo: -```shell +```sh cp config.toml.example config.toml ``` @@ -134,13 +133,16 @@ the following settings: Also, it can consume a lot of disk space. This has the same effect as the `-i` or `--incremental` flags. - `llvm-config`: enables building with system LLVM. [See this chapter][sysllvm] - for more info. This avoids building LLVM, which can take a while. + for more info. This avoids building LLVM, which can take a while (45 minutes + on my laptop; others have reported 15 minutes or faster with incremental + compilation). [sysllvm]: ./building/suggested.html#building-with-system-llvm ### `./x.py` Intro -`rustc` is a _bootstrapping_ compiler, which means that it is written in Rust and thus needs to be compiled by itself. So where do you +`rustc` is a _bootstrapping_ compiler, which means that it is written in Rust +and thus needs to be compiled by itself. So where do you get the original compiler from? We use the current beta compiler to build a new compiler. Then, we use that compiler to build itself. Thus, `rustc` has a 2-stage build. You can read more about bootstrapping @@ -179,7 +181,7 @@ To build and test everything: For most contributions, you only need to build stage 1, which saves a lot of time: -```shell +```sh # Build the compiler (stage 1) ./x.py build --stage 1 @@ -216,7 +218,7 @@ 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: -```shell +```sh ./x.py check ``` @@ -226,7 +228,7 @@ completes in a couple of minutes on my laptop. Finally, the CI ensures that the codebase is using consistent style. To format the code: -```shell +```sh # Actually format ./x.py fmt @@ -237,7 +239,9 @@ the code: *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. +commit, as this reduces conflicts later. The pinned verson is built under +`build//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`. On 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 @@ -347,8 +351,10 @@ writing `r? @user` (e.g. `r? @eddyb`) in either the original post or a followup comment. The reviewer may request some changes using the GitHub code review interface. -They may also request special procedures (such as a crater run; see below) for -some PRs. +They may also request special procedures (such as a [crater] run; [see +below][break]) for some PRs. + +[break]: #breaking-changes When the PR is ready to be merged, the reviewer will issue a command to `@bors`, the CI bot. Usually, this is `@bors r+` or `@bors r=@user` to approve @@ -386,7 +392,7 @@ channels: stable, beta, and nightly. In order to implement a new feature, usually you will need to go through [the RFC process][rfc] to propose a design, have discussions, etc. In some cases, -small features can be added with only an FCP (see below). If in doubt, ask the +small features can be added with only an FCP ([see below][break]). If in doubt, ask the compiler, language, or libs team (whichever is most relevant). [rfc]: https://github.com/rust-lang/rfcs/blob/master/README.md @@ -399,7 +405,8 @@ The feature then needs to be implemented behind a feature gate, which prevents it from being accidentally used. Finally, somebody may propose stabilizing the feature in an upcoming version of -Rust. This requires a Final Comment Period (see below) to get the approval of the relevant teams. +Rust. This requires a Final Comment Period ([see below][break]) to get the +approval of the relevant teams. After that, the feature gate can be removed and the feature turned on for all users. From a0b4bcfc5774e1221ae7d3ed4e66d26fa614daa7 Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Thu, 18 Jun 2020 11:55:58 -0500 Subject: [PATCH 20/22] LeSeulArtichaut wording/typo fixes Co-authored-by: LeSeulArtichaut --- src/getting-started.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/getting-started.md b/src/getting-started.md index b1ed6bc0e..628326763 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -323,7 +323,7 @@ feel comfortable jumping straight into the large `rust-lang/rust` codebase. The following tasks are doable without much background knowledge but are incredibly helpful: -- [ICE-breakers Cleanup crew][iceb]: find minimal reproductions of ICEs, bisect +- [Cleanup crew][iceb]: find minimal reproductions of ICEs, bisect regressions, etc. This is a way of helping that saves a ton of time for others to fix an error later. - Writing documentation: if you are feeling a bit more intrepid, you could try @@ -357,7 +357,7 @@ below][break]) for some PRs. [break]: #breaking-changes When the PR is ready to be merged, the reviewer will issue a command to -`@bors`, the CI bot. Usually, this is `@bors r+` or `@bors r=@user` to approve +`@bors`, the CI bot. Usually, this is `@bors r+` or `@bors r=user` to approve a PR (there are few other commands, but they are less relevant here). This puts the PR in [bors's queue][bors] to be tested and merged. Be patient; this can take a while and the queue can sometimes be long. PRs are never merged by hand. @@ -410,7 +410,7 @@ approval of the relevant teams. After that, the feature gate can be removed and the feature turned on for all users. -[For more details on this process, see this chapter.](./implementing_new_features.md) +[For more details on this process, see this chapter on implementing new features.](./implementing_new_features.md) ### Breaking Changes @@ -428,7 +428,7 @@ discuss the issue and either accept, reject, or request changes on the PR. If the scale of breakage is large, a deprecation warning may be needed. This is a warning that the compiler will display to users whose code will break in the -future. After some time, an FCP can be used to move forward with the actual +future. After some time, an FCP can be used to move forward with the actual breakage. If the scale of breakage is unknown, a team member or contributor may request a @@ -449,7 +449,7 @@ compiler (as opposed to a full RFC or a design meeting with the team). Example of things that might require MCPs include major refactorings, changes to important types, or important changes to how the compiler does something. -**When in doubt, ask on [zulip][z]. We would hate for you to put a lot of work +**When in doubt, ask on [zulip][z]. It would be a shame to put a lot of work into a PR that ends up not getting merged!** ### Performance From 6258881a7280ca4d267f56c00abd6d4e533d3713 Mon Sep 17 00:00:00 2001 From: mark Date: Thu, 18 Jun 2020 12:09:50 -0500 Subject: [PATCH 21/22] address a bunch of review comments --- src/getting-started.md | 35 +++++++++++++++++++++++++++++++---- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/src/getting-started.md b/src/getting-started.md index 628326763..5dc9f4d71 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -163,6 +163,20 @@ things up. ### Building and Testing `rustc` +Here is a summary of the different commands for reference, but you probably +should still read the rest of the section: + +| Command | When to use it | +| --- | --- | +| `x.py check` | Quick check to see if things compile; rust-analyzer can run this automatically for you | +| `x.py build --stage 1` | Build just the 1st stage of the compiler; this is faster than building stage 2 and usually good enough | +| `x.py build --stage 1 --keep-stage 1` | Build the 1st stage of the compiler and skips rebuilding the library; this is useful after you've done an ordinary stage1 build to skip compilation time, but it can cause weird problems. (Just do a regular build to resolve.) | +| `x.py test --stage 1` | Run the test suite using the stage1 compiler (first build) | +| `x.py test --stage 1 --keep-stage 1` | Run the test suite using the stage1 compiler (subsequent builds) | +| `x.py test --stage 1 --bless [--keep-stage 1]` | Run the test suite using the stage1 compiler _and_ update expected test output. | +| `x.py build` | Do a full 2-stage build. You almost never want to do this. | +| `x.py test` | Do a full 2-stage build and run all tests. You almost never want to do this. | + To do a full 2-stage build of the whole compiler, you should run this (after updating `config.toml` as mentioned above): @@ -206,7 +220,7 @@ different test suites [in this chapter][testing]. [uitests]: ./tests/adding.html#ui [testing]: https://rustc-dev-guide.rust-lang.org/tests/intro.html -``` +```sh # First build ./x.py test --stage 1 src/test/ui @@ -214,6 +228,13 @@ different test suites [in this chapter][testing]. ./x.py test --stage 1 src/test/ui --keep-stage 1 ``` +If your changes impact test output, you can use `--bless` to automatically +update the `.stderr` files of the affected tests: + +```sh +./x.py test --stage 1 src/test/ui --keep-stage 1 --bless +``` + 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: @@ -223,7 +244,9 @@ this with: ``` This command is really fast (relative to the other commands). It usually -completes in a couple of minutes on my laptop. +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: @@ -447,10 +470,14 @@ relatively lightweight mechanism for getting feedback on large changes to the compiler (as opposed to a full RFC or a design meeting with the team). Example of things that might require MCPs include major refactorings, changes -to important types, or important changes to how the compiler does something. +to important types, or important changes to how the compiler does something, or +smaller user-facing changes. **When in doubt, ask on [zulip][z]. It would be a shame to put a lot of work -into a PR that ends up not getting merged!** +into a PR that ends up not getting merged!** [See this document][mcpinfo] for +more info on MCPs. + +[mcpinfo]: https://forge.rust-lang.org/compiler/mcp.html ### Performance From 7dc886defdc1b02b7c57d4851cafc7044b355b8d Mon Sep 17 00:00:00 2001 From: mark Date: Thu, 18 Jun 2020 12:11:43 -0500 Subject: [PATCH 22/22] fix line length --- src/getting-started.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/getting-started.md b/src/getting-started.md index 5dc9f4d71..4cd997200 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -433,7 +433,8 @@ approval of the relevant teams. After that, the feature gate can be removed and the feature turned on for all users. -[For more details on this process, see this chapter on implementing new features.](./implementing_new_features.md) +For more details on this process, see [this chapter on implementing new +features.](./implementing_new_features.md) ### Breaking Changes