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?