1# Getting Started 2 3<!-- toc --> 4 5This documentation is _not_ intended to be comprehensive; it is meant to be a 6quick guide for the most useful things. For more information, [see this 7chapter on how to build and run the compiler](./building/how-to-build-and-run.md). 8 9## Asking Questions 10 11The compiler team (or `t-compiler`) usually hangs out in Zulip [in this 12"stream"][z]; it will be easiest to get questions answered there. 13 14[z]: https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler 15 16**Please ask questions!** A lot of people report feeling that they are "wasting 17expert time", but nobody on `t-compiler` feels this way. Contributors are 18important to us. 19 20Also, if you feel comfortable, prefer public topics, as this means others can 21see the questions and answers, and perhaps even integrate them back into this 22guide :) 23 24### Experts 25 26Not all `t-compiler` members are experts on all parts of `rustc`; it's a pretty 27large project. To find out who has expertise on different parts of the 28compiler, [consult this "experts map"][map]. 29 30It's not perfectly complete, though, so please also feel free to ask questions 31even if you can't figure out who to ping. 32 33[map]: https://github.com/rust-lang/compiler-team/blob/master/content/experts/map.toml 34 35### Etiquette 36 37We do ask that you be mindful to include as much useful information as you can 38in your question, but we recognize this can be hard if you are unfamiliar with 39contributing to Rust. 40 41Just pinging someone without providing any context can be a bit annoying and 42just create noise, so we ask that you be mindful of the fact that the 43`t-compiler` folks get a lot of pings in a day. 44 45## Cloning and Building 46 47The main repository is [`rust-lang/rust`][repo]. This contains the compiler, 48the standard library (including `core`, `alloc`, `test`, `proc_macro`, etc), 49and a bunch of tools (e.g. `rustdoc`, the bootstrapping infrastructure, etc). 50 51[repo]: https://github.com/rust-lang/rust 52 53There are also a bunch of submodules for things like LLVM, `clippy`, `miri`, 54etc. You don't need to clone these immediately, but the build tool will 55automatically clone and sync them (more on this later). 56 57[**Take a look at the "Suggested Workflows" chapter for some helpful 58advice.**][suggested] 59 60[suggested]: ./building/suggested.md 61 62### System Requirements 63 64[**See this chapter for detailed software requirements.**](./building/prerequisites.md) 65Most notably, you will need Python 2 or 3 to run `x.py`. 66 67There are no hard hardware requirements, but building the compiler is 68computationally expensive, so a beefier machine will help, and I wouldn't 69recommend trying to build on a Raspberry Pi :P 70 71- Recommended >=30GB of free disk space; otherwise, you will have to keep 72 clearing incremental caches. More space is better, the compiler is a bit of a 73 hog; it's a problem we are aware of. 74- Recommended >=8GB RAM. 75- Recommended >=2 cores; having more cores really helps. 76- You will need an internet connection to build; the bootstrapping process 77 involves updating git submodules and downloading a beta compiler. It doesn't 78 need to be super fast, but that can help. 79 80Building the compiler takes more than half an hour on my moderately powerful 81laptop. The first time you build the compiler, LLVM will also be built unless 82you use CI-built LLVM ([see below][configsec]). 83 84[configsec]: #configuring-the-compiler 85 86Like `cargo`, the build system will use as many cores as possible. Sometimes 87this can cause you to run low on memory. You can use `-j` to adjust the number 88concurrent jobs. If a full build takes more than ~45 minutes to an hour, 89you are probably spending most of the time swapping memory in and out; 90try using `-j1`. 91 92On a slow machine, the build times for rustc are very painful. Consider using 93`./x.py check` instead of a full build and letting the automated tests run 94when you push to GitHub. 95 96If you don't have too much free disk space, you may want to turn off 97incremental compilation ([see below][configsec]). This will make 98compilation take longer (especially after a rebase), 99but will save a ton of space from the incremental caches. 100 101### Cloning 102 103You can just do a normal git clone: 104 105```sh 106git clone https://github.com/rust-lang/rust.git 107``` 108 109You don't need to clone the submodules at this time. But if you want to, you 110can do the following: 111 112```sh 113# first time 114git submodule update --init --recursive 115 116# subsequent times (to pull new commits) 117git submodule update 118``` 119 120### Configuring the Compiler 121 122The compiler has a configuration file which contains a ton of settings. We will 123provide some recommendations here that should work for most, but [check out 124this chapter for more info][config]. 125 126[config]: ./building/how-to-build-and-run.md#create-a-configtoml 127 128In the top level of the repo: 129 130```sh 131$ ./x.py setup 132``` 133 134This will walk you through an interactive setup for `x.py` that looks like this: 135 136``` 137$ ./x.py setup 138Welcome to the Rust project! What do you want to do with x.py? 139a) Contribute to the standard library 140b) Contribute to the compiler 141c) Contribute to the compiler, and also modify LLVM or codegen 142d) Install Rust from source 143Please choose one (a/b/c/d): a 144`x.py` will now use the configuration at /home/joshua/rustc2/src/bootstrap/defaults/config.toml.library 145To get started, try one of the following commands: 146- `x.py check` 147- `x.py build` 148- `x.py test library/std` 149- `x.py doc` 150For more suggestions, see https://rustc-dev-guide.rust-lang.org/building/suggested.html 151``` 152 153Note that by default, `./x.py setup` will use CI-built LLVM if available for your 154platform so that you don't need to build LLVM in addition to building the 155compiler. In some circumstances, such as when updating the version of LLVM used 156by `rustc`, you may want to temporarily disable this feature. See the ["Updating 157LLVM" section] for more. 158 159If you want to download LLVM from CI without running `./x.py setup`, you can set 160the `download-ci-llvm` option to `true` in your `config.toml`: 161 162```toml 163[llvm] 164download-ci-llvm = true 165``` 166 167["Updating LLVM" section]: https://rustc-dev-guide.rust-lang.org/backend/updating-llvm.html?highlight=download-ci-llvm#feature-updates 168 169### `x.py` Intro 170 171`rustc` is a _bootstrapping_ compiler, which means that it is written in Rust 172and thus needs to be compiled by itself. So where do you 173get the original compiler from? We use the current beta compiler 174to build a new compiler. Then, we use that compiler to build itself. Thus, 175`rustc` has a 2-stage build. You can read more about bootstrapping 176[here][boot], but you don't need to know much more to contribute. 177 178[boot]: ./building/bootstrapping.md 179 180We have a special tool `x.py` that drives this process. It is used for 181building the compiler, the standard libraries, and `rustdoc`. It is also used 182for driving CI and building the final release artifacts. 183 184Unfortunately, a proper 2-stage build takes a long time depending on your 185hardware, but it is the only correct way to build everything (e.g. it's what 186the CI and release processes use). **However, in most cases, you can get by 187without a full 2-stage build**. In the following section, we give instructions 188for how to do "the correct thing", but then we also give various tips to speed 189things up. 190 191### Building and Testing `rustc` 192 193Here is a summary of the different commands for reference, but you probably 194should still read the rest of the section: 195 196| Command | When to use it | 197| --- | --- | 198| `./x.py check` | Quick check to see if things compile; [rust-analyzer can run this automatically for you][rust-analyzer] | 199| `./x.py build --stage 0 [library/std]` | Build only the standard library, without building the compiler | 200| `./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 | 201| `./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.) | 202| `./x.py test [--keep-stage 1]` | Run the test suite using the stage1 compiler | 203| `./x.py test --bless [--keep-stage 1]` | Run the test suite using the stage1 compiler _and_ update expected test output. | 204| `./x.py build --stage 2 compiler/rustc` | Do a full 2-stage build. You almost never want to do this. | 205| `./x.py test --stage 2` | Do a full 2-stage build and run all tests. You almost never want to do this. | 206 207To do a full 2-stage build of the whole compiler, you should run this (after 208updating `config.toml` as mentioned above): 209 210```sh 211./x.py build --stage 2 compiler/rustc 212``` 213 214In the process, this will also necessarily build the standard libraries, and it 215will build `rustdoc` (which doesn't take too long). 216 217To build and test everything: 218 219```sh 220./x.py test 221``` 222 223For most contributions, you only need to build stage 1, which saves a lot of time: 224 225```sh 226# Build the compiler (stage 1) 227./x.py build library/std 228 229# Subsequent builds 230./x.py build --keep-stage 1 library/std 231``` 232 233This will take a while, especially the first time. Be wary of accidentally 234touching or formatting the compiler, as `x.py` will try to recompile it. 235 236**NOTE**: The `--keep-stage 1` will _assume_ that the stage 0 standard library 237does not need to be rebuilt, which is usually true, which will save some time. 238However, if you are changing certain parts of the compiler, this may lead to 239weird errors. Feel free to ask on [zulip][z] if you are running into issues. 240 241This runs a ton of tests and takes a long time to complete. If you are 242working on `rustc`, you can usually get by with only the [UI tests][uitests]. These 243test are mostly for the frontend of the compiler, so if you are working on LLVM 244or codegen, this shortcut will _not_ test your changes. You can read more about the 245different test suites [in this chapter][testing]. 246 247[rust-analyzer]: ./building/suggested.html#configuring-rust-analyzer-for-rustc 248[uitests]: ./tests/adding.html#ui 249[testing]: https://rustc-dev-guide.rust-lang.org/tests/intro.html 250 251```sh 252# First build 253./x.py test src/test/ui 254 255# Subsequent builds 256./x.py test src/test/ui --keep-stage 1 257``` 258 259If your changes impact test output, you can use `--bless` to automatically 260update the `.stderr` files of the affected tests: 261 262```sh 263./x.py test src/test/ui --keep-stage 1 --bless 264``` 265 266While working on the compiler, it can be helpful to see if the code just 267compiles (similar to `cargo check`) without actually building it. You can do 268this with: 269 270```sh 271./x.py check 272``` 273 274This command is really fast (relative to the other commands). It usually 275completes in a couple of minutes on my laptop. **A common workflow when working 276on the compiler is to make changes and repeatedly check with `./x.py check`. 277Then, run the tests as shown above when you think things should work.** 278 279Finally, the CI ensures that the codebase is using consistent style. To format 280the code: 281 282```sh 283# Actually format 284./x.py fmt 285 286# Just check formatting, exit with error 287./x.py fmt --check 288``` 289 290*Note*: we don't use stable `rustfmt`; we use a pinned version with a special 291config, so this may result in different style from normal `rustfmt` if you have 292format-on-save turned on. It's a good habit to run `./x.py fmt` before every 293commit, as this reduces conflicts later. The pinned version is built under 294`build/<target>/stage0/bin/rustfmt`, so if you want, you can use it for a 295single file or for format-on-save in your editor, which can be faster than `./x.py fmt`. 296You'll have to pass the <!-- date: 2021-09 --> `--edition=2021` argument 297yourself when calling `rustfmt` directly. 298 299One last thing: you can use `RUSTC_LOG=XXX` to get debug logging. [Read more 300here][logging]. Notice the `C` in `RUSTC_LOG`. Other than that, it uses normal 301[`env_logger`][envlog] or `tracing` syntax. 302 303[envlog]: https://crates.io/crates/env_logger 304[logging]: ./tracing.md 305 306### Building and Testing `std`/`core`/`alloc`/`test`/`proc_macro`/etc. 307 308As before, technically the proper way to build one of these libraries is to use 309the stage-2 compiler, which of course requires a 2-stage build, described above 310(`./x.py build`). 311 312In practice, though, you don't need to build the compiler unless you are 313planning to use a recently added nightly feature. Instead, you can just build 314stage 0, which uses the current beta compiler. 315 316```sh 317./x.py build --stage 0 318``` 319 320```sh 321./x.py test --stage 0 library/std 322``` 323 324(The same works for `library/alloc`, `library/core`, etc.) 325 326### Building and Testing `rustdoc` 327 328`rustdoc` uses `rustc` internals (and, of course, the standard library), so you 329will have to build the compiler and `std` once before you can build `rustdoc`. 330As before, you can use `./x.py build` to do this. The first time you build, 331the stage-1 compiler will also be built. 332 333```sh 334# First build 335./x.py build 336 337# Subsequent builds 338./x.py build --keep-stage 1 339``` 340 341As with the compiler, you can do a fast check build: 342 343```sh 344./x.py check 345``` 346 347Rustdoc has two types of tests: content tests and UI tests. 348 349```sh 350# Content tests 351./x.py test src/test/rustdoc 352 353# UI tests 354./x.py test src/test/rustdoc-ui 355 356# Both at once 357./x.py test src/test/rustdoc src/test/rustdoc-ui 358``` 359 360### Contributing code to other Rust projects 361 362There are a bunch of other projects that you can contribute to outside of the 363`rust-lang/rust` repo, including `clippy`, `miri`, `chalk`, and many others. 364 365These repos might have their own contributing guidelines and procedures. Many 366of them are owned by working groups (e.g. `chalk` is largely owned by 367WG-traits). For more info, see the documentation in those repos' READMEs. 368 369### Other ways to contribute 370 371There are a bunch of other ways you can contribute, especially if you don't 372feel comfortable jumping straight into the large `rust-lang/rust` codebase. 373 374The following tasks are doable without much background knowledge but are 375incredibly helpful: 376 377- [Cleanup crew][iceb]: find minimal reproductions of ICEs, bisect 378 regressions, etc. This is a way of helping that saves a ton of time for 379 others to fix an error later. 380- [Writing documentation][wd]: if you are feeling a bit more intrepid, you could try 381 to read a part of the code and write doc comments for it. This will help you 382 to learn some part of the compiler while also producing a useful artifact! 383- [Working groups][wg]: there are a bunch of working groups on a wide variety 384 of rust-related things. 385 386[iceb]: ./notification-groups/cleanup-crew.md 387[wd]: ./contributing.md#writing-documentation 388[wg]: https://rust-lang.github.io/compiler-team/working-groups/ 389 390 391## Contributor Procedures 392 393There are some official procedures to know about. This is a tour of the 394highlights, but there are a lot more details, which we will link to below. 395 396### Code Review 397 398When you open a PR on the `rust-lang/rust` repo, a bot called `@rust-highfive` will 399automatically assign a reviewer to the PR. The reviewer is the person that will 400approve the PR to be tested and merged. If you want a specific reviewer (e.g. a 401team member you've been working with), you can specifically request them by 402writing `r? @user` (e.g. `r? @eddyb`) in either the original post or a followup 403comment (you can see [this comment][r?] for example). 404 405Please note that the reviewers are humans, who for the most part work on `rustc` 406in their free time. This means that they can take some time to respond and review 407your PR. It also means that reviewers can miss some PRs that are assigned to them. 408 409To try to move PRs forward, the Triage WG regularly goes through all PRs that 410are waiting for review and haven't been discussed for at least 2 weeks. If you 411don't get a review within 2 weeks, feel free to ask the Triage WG on 412Zulip ([#t-release/triage]). They have knowledge of when to ping, who might be 413on vacation, etc. 414 415The reviewer may request some changes using the GitHub code review interface. 416They may also request special procedures (such as a [crater] run; [see 417below][break]) for some PRs. 418 419[r?]: https://github.com/rust-lang/rust/pull/78133#issuecomment-712692371 420[#t-release/triage]: https://rust-lang.zulipchat.com/#narrow/stream/242269-t-release.2Ftriage 421[break]: #breaking-changes 422 423When the PR is ready to be merged, the reviewer will issue a command to 424`@bors`, the CI bot. Usually, this is `@bors r+` or `@bors r=user` to approve 425a PR (there are few other commands, but they are less relevant here). 426You can see [this comment][r+] for example. This puts the PR in [bors's queue][bors] 427to be tested and merged. Be patient; this can take a while and the queue can 428sometimes be long. PRs are never merged by hand. 429 430[r+]: https://github.com/rust-lang/rust/pull/78133#issuecomment-712726339 431[bors]: https://bors.rust-lang.org/queue/rust 432 433### Bug Fixes or "Normal" code changes 434 435For most PRs, no special procedures are needed. You can just open a PR, and it 436will be reviewed, approved, and merged. This includes most bug fixes, 437refactorings, and other user-invisible changes. The next few sections talk 438about exceptions to this rule. 439 440Also, note that it is perfectly acceptable to open WIP PRs or GitHub [Draft 441PRs][draft]. Some people prefer to do this so they can get feedback along the 442way or share their code with a collaborator. Others do this so they can utilize 443the CI to build and test their PR (e.g. if you are developing on a laptop). 444 445[draft]: https://github.blog/2019-02-14-introducing-draft-pull-requests/ 446 447### New Features 448 449Rust has strong backwards-compatibility guarantees. Thus, new features can't 450just be implemented directly in stable Rust. Instead, we have 3 release 451channels: stable, beta, and nightly. 452 453- **Stable**: this is the latest stable release for general usage. 454- **Beta**: this is the next release (will be stable within 6 weeks). 455- **Nightly**: follows the `master` branch of the repo. This is the only 456 channel where unstable, incomplete, or experimental features are usable with 457 feature gates. 458 459In order to implement a new feature, usually you will need to go through [the 460RFC process][rfc] to propose a design, have discussions, etc. In some cases, 461small features can be added with only an FCP ([see below][break]). If in doubt, ask the 462compiler, language, or libs team (whichever is most relevant). 463 464[rfc]: https://github.com/rust-lang/rfcs/blob/master/README.md 465 466After a feature is approved to be added, a tracking issue is created on the 467`rust-lang/rust` repo, which tracks the progress towards the implementation of 468the feature, any bugs reported, and eventually stabilization. 469 470The feature then needs to be implemented behind a feature gate, which prevents 471it from being accidentally used. 472 473Finally, somebody may propose stabilizing the feature in an upcoming version of 474Rust. This requires a Final Comment Period ([see below][break]) to get the 475approval of the relevant teams. 476 477After that, the feature gate can be removed and the feature turned on for all users. 478 479For more details on this process, see [this chapter on implementing new 480features.](./implementing_new_features.md) 481 482### Breaking Changes 483 484As mentioned above, Rust has strong backwards-compatibility guarantees. To this 485end, we are reluctant to make breaking changes. However, sometimes they are 486needed to correct compiler bugs (e.g. code that compiled but should not) or 487make progress on some features. 488 489Depending on the scale of the breakage, there are a few different actions that 490can be taken. If the reviewer believes the breakage is very minimal (i.e. very 491unlikely to be actually encountered by users), they may just merge the change. 492More often, they will request a Final Comment Period (FCP), which calls for 493rough consensus among the members of a relevant team. The team members can 494discuss the issue and either accept, reject, or request changes on the PR. 495 496If the scale of breakage is large, a deprecation warning may be needed. This is 497a warning that the compiler will display to users whose code will break in the 498future. After some time, an FCP can be used to move forward with the actual 499breakage. 500 501If the scale of breakage is unknown, a team member or contributor may request a 502[crater] run. This is a bot that will compile all crates.io crates and many 503public github repos with the compiler with your changes. A report will then be 504generated with crates that ceased to compile with or began to compile with your 505changes. Crater runs can take a few days to complete. 506 507[crater]: https://github.com/rust-lang/crater 508 509### Major Changes 510 511The compiler team has a special process for large changes, whether or not they 512cause breakage. This process is called a Major Change Proposal (MCP). MCP is a 513relatively lightweight mechanism for getting feedback on large changes to the 514compiler (as opposed to a full RFC or a design meeting with the team). 515 516Example of things that might require MCPs include major refactorings, changes 517to important types, or important changes to how the compiler does something, or 518smaller user-facing changes. 519 520**When in doubt, ask on [zulip][z]. It would be a shame to put a lot of work 521into a PR that ends up not getting merged!** [See this document][mcpinfo] for 522more info on MCPs. 523 524[mcpinfo]: https://forge.rust-lang.org/compiler/mcp.html 525 526### Performance 527 528Compiler performance is important. We have put a lot of effort over the last 529few years into [gradually improving it][perfdash]. 530 531[perfdash]: https://perf.rust-lang.org/dashboard.html 532 533If you suspect that your change may cause a performance regression (or 534improvement), you can request a "perf run" (your reviewer may also request one 535before approving). This is yet another bot that will compile a collection of 536benchmarks on a compiler with your changes. The numbers are reported 537[here][perf], and you can see a comparison of your changes against the latest 538master. 539 540[perf]: https://perf.rust-lang.org 541 542## Other Resources 543 544- This guide: talks about how `rustc` works 545- [The t-compiler zulip][z] 546- [The compiler's documentation (rustdocs)](https://doc.rust-lang.org/nightly/nightly-rustc/) 547- [The Forge](https://forge.rust-lang.org/) has more documentation about various procedures. 548- `#contribute` and `#rustdoc` on [Discord](https://discord.gg/rust-lang). 549