]>
Commit | Line | Data |
---|---|---|
60c5eb7d XL |
1 | ![Travis CI badge](https://api.travis-ci.com/rust-lang/rustc-guide.svg?branch=master) |
2 | ||
3 | ||
532ac7d7 | 4 | This is a collaborative effort to build a guide that explains how rustc |
a1dfa0c6 XL |
5 | works. The aim of the guide is to help new contributors get oriented |
6 | to rustc, as well as to help more experienced folks in figuring out | |
7 | some new part of the compiler that they haven't worked on before. | |
8 | ||
416331ca | 9 | [You can read the latest version of the guide here.](https://rust-lang.github.io/rustc-guide/) |
a1dfa0c6 XL |
10 | |
11 | You may also find the rustdocs [for the compiler itself][rustdocs] useful. | |
12 | ||
13 | [rustdocs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ | |
14 | ||
a1dfa0c6 XL |
15 | ### Contributing to the guide |
16 | ||
532ac7d7 XL |
17 | The guide is useful today, but it has a lot of work still go. |
18 | ||
a1dfa0c6 XL |
19 | If you'd like to help improve the guide, we'd love to have you! You can find |
20 | plenty of issues on the [issue | |
532ac7d7 | 21 | tracker](https://github.com/rust-lang/rustc-guide/issues). Just post a |
a1dfa0c6 XL |
22 | comment on the issue you would like to work on to make sure that we don't |
23 | accidentally duplicate work. If you think something is missing, please open an | |
24 | issue about it! | |
25 | ||
26 | **In general, if you don't know how the compiler works, that is not a | |
27 | problem!** In that case, what we will do is to schedule a bit of time | |
28 | for you to talk with someone who **does** know the code, or who wants | |
29 | to pair with you and figure it out. Then you can work on writing up | |
30 | what you learned. | |
31 | ||
32 | In general, when writing about a particular part of the compiler's code, we | |
33 | recommend that you link to the relevant parts of the [rustc | |
34 | rustdocs][rustdocs]. | |
35 | ||
36 | To help prevent accidentally introducing broken links, we use the | |
37 | `mdbook-linkcheck`. If installed on your machine `mdbook` will automatically | |
38 | invoke this link checker, otherwise it will emit a warning saying it couldn't | |
39 | be found. | |
40 | ||
41 | ```bash | |
42 | > cargo install mdbook-linkcheck | |
43 | ``` | |
44 | ||
45 | You will need `mdbook` version `>= 0.2`. `linkcheck` will be run automatically | |
46 | when you run `mdbook build`. | |
60c5eb7d XL |
47 | |
48 | ## How to fix toolstate failures | |
49 | ||
50 | 1. You will get a ping from the toolstate commit. e.g. https://github.com/rust-lang-nursery/rust-toolstate/commit/8ffa0e4c30ac9ba8546b7046e5c4ccc2b96ebdd4 | |
51 | ||
52 | 2. The commit contains a link to the PR that caused the breakage. e.g. https://github.com/rust-lang/rust/pull/64321 | |
53 | ||
54 | 3. If you go to that PR's thread, there is a post from bors with a link to the CI status: https://github.com/rust-lang/rust/pull/64321#issuecomment-529763807 | |
55 | ||
56 | 4. Follow the check-azure link to get to the Azure website for that build: https://dev.azure.com/rust-lang/e71b0ddf-dd27-435a-873c-e30f86eea377/_build/results?buildId=7780 | |
57 | ||
58 | 5. There will be approximately 1 billion different jobs for the build. They are for different configurations and platforms. The rustc-guide build only runs on the Linux x86_64-gnu-tools job. So click on that job in the list, which is about 60% down in the list. | |
59 | ||
60 | 6. Click the Run build step in the job to get the console log for the step. | |
61 | ||
62 | 7. Click on the log and Ctrl-f to get a search box in the log | |
63 | ||
64 | 8. Search for rustc-guide. This gets you to the place where the links are checked. It is usually ~11K lines into the log | |
65 | ||
66 | 9. Look at the links in the log near that point in the log | |
67 | ||
68 | 10. Fix those links in the rustc-guide (by making a PR in the rustc-guide repo) | |
69 | ||
70 | 11. Make a PR on the rust-lang/rust repo to update the rustc-guide git submodule in src/docs/rustc-guide. | |
71 | To make a PR, the following steps are useful. | |
72 | ||
73 | ```bash | |
74 | # Assuming you already cloned the rust-lang/rust repo and you're in the correct directory | |
75 | git submodule update --remote src/doc/rustc-guide | |
76 | git add -u | |
77 | git commit -m "Update rustc-guide" | |
78 | # Note that you can use -i, which is short for --incremental, in the following command | |
79 | ./x.py test --incremental --stage 1 src/doc/rustc-guide # This is optional and should succeed anyway | |
80 | # Open a PR in rust-lang/rust | |
81 | ``` | |
82 | ||
83 | 12. Wait for PR to merge | |
84 | ||
85 | Voila! |