start a getting started guide
This commit is contained in:
mark
Who? Me?!
parent
7c51350dfc
commit
4cbb4c384e
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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?
|
||||
Loading…
Reference in New Issue