]>
Commit | Line | Data |
---|---|---|
cdc7bbd5 | 1 | [![CI](https://github.com/rust-lang/rustc-dev-guide/actions/workflows/ci.yml/badge.svg)](https://github.com/rust-lang/rustc-dev-guide/actions/workflows/ci.yml) |
60c5eb7d XL |
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 | ||
74b04a01 | 9 | [You can read the latest version of the guide here.](https://rustc-dev-guide.rust-lang.org/) |
a1dfa0c6 XL |
10 | |
11 | You may also find the rustdocs [for the compiler itself][rustdocs] useful. | |
6a06907d XL |
12 | Note that these are not intended as a guide; it's recommended that you search |
13 | for the docs you're looking for instead of reading them top to bottom. | |
a1dfa0c6 | 14 | |
6a06907d | 15 | [rustdocs]: https://doc.rust-lang.org/nightly/nightly-rustc |
a1dfa0c6 | 16 | |
136023e0 XL |
17 | For documentation on developing the standard library, see |
18 | [`std-dev-guide`](https://std-dev-guide.rust-lang.org/). | |
19 | ||
a1dfa0c6 XL |
20 | ### Contributing to the guide |
21 | ||
6a06907d | 22 | The guide is useful today, but it has a lot of work still to go. |
532ac7d7 | 23 | |
a1dfa0c6 XL |
24 | If you'd like to help improve the guide, we'd love to have you! You can find |
25 | plenty of issues on the [issue | |
74b04a01 | 26 | tracker](https://github.com/rust-lang/rustc-dev-guide/issues). Just post a |
a1dfa0c6 XL |
27 | comment on the issue you would like to work on to make sure that we don't |
28 | accidentally duplicate work. If you think something is missing, please open an | |
29 | issue about it! | |
30 | ||
31 | **In general, if you don't know how the compiler works, that is not a | |
32 | problem!** In that case, what we will do is to schedule a bit of time | |
33 | for you to talk with someone who **does** know the code, or who wants | |
34 | to pair with you and figure it out. Then you can work on writing up | |
35 | what you learned. | |
36 | ||
37 | In general, when writing about a particular part of the compiler's code, we | |
38 | recommend that you link to the relevant parts of the [rustc | |
39 | rustdocs][rustdocs]. | |
40 | ||
ba9703b0 XL |
41 | ### Build Instructions |
42 | ||
ba9703b0 XL |
43 | To build a local static HTML site, install [`mdbook`](https://github.com/rust-lang/mdBook) with: |
44 | ||
45 | ``` | |
6a06907d | 46 | > cargo install mdbook mdbook-linkcheck mdbook-toc |
ba9703b0 XL |
47 | ``` |
48 | ||
49 | and execute the following command in the root of the repository: | |
50 | ||
51 | ``` | |
52 | > mdbook build | |
53 | ``` | |
54 | ||
55 | The build files are found in the `book` directory. | |
56 | ||
57 | ### Link Validations | |
58 | ||
6a06907d XL |
59 | We use `mdbook-linkcheck` to validate URLs included in our documentation. |
60 | `linkcheck` will be run automatically when you build with the instructions in the section above. | |
61 | ||
62 | ### Table of Contents | |
a1dfa0c6 | 63 | |
6a06907d XL |
64 | We use `mdbook-toc` to auto-generate TOCs for long sections. You can invoke the preprocessor by |
65 | including the `<!-- toc -->` marker at the place where you want the TOC. | |
a1dfa0c6 | 66 | |
6a06907d | 67 | ### Pre-commit script |
ba9703b0 | 68 | |
6a06907d XL |
69 | We also test that line lengths are less than 100 columns. To test this locally, |
70 | you can run `ci/check_line_lengths.sh`. | |
ba9703b0 | 71 | |
6a06907d | 72 | You can also set this to run automatically. |
ba9703b0 | 73 | |
6a06907d XL |
74 | On Linux: |
75 | ||
76 | ```bash | |
77 | ln -s ../../ci/check_line_lengths.sh .git/hooks/pre-commit | |
ba9703b0 XL |
78 | ``` |
79 | ||
6a06907d | 80 | On Windows: |
ba9703b0 | 81 | |
6a06907d XL |
82 | ```powershell |
83 | New-Item -Path .git/hooks/pre-commit -ItemType HardLink -Value <absolute_path/to/check_line_lengths.sh> | |
84 | ``` | |
60c5eb7d XL |
85 | |
86 | ## How to fix toolstate failures | |
87 | ||
6a06907d XL |
88 | > **NOTE**: Currently, we do not track the rustc-dev-guide toolstate due to |
89 | [spurious failures](https://github.com/rust-lang/rust/pull/71731), | |
90 | but we leave these instructions for when we do it again in the future. | |
91 | ||
60c5eb7d XL |
92 | 1. You will get a ping from the toolstate commit. e.g. https://github.com/rust-lang-nursery/rust-toolstate/commit/8ffa0e4c30ac9ba8546b7046e5c4ccc2b96ebdd4 |
93 | ||
94 | 2. The commit contains a link to the PR that caused the breakage. e.g. https://github.com/rust-lang/rust/pull/64321 | |
95 | ||
96 | 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 | |
97 | ||
6a06907d | 98 | 4. Follow the check-actions link to get to the Actions page for that build |
60c5eb7d | 99 | |
74b04a01 | 100 | 5. There will be approximately 1 billion different jobs for the build. They are for different configurations and platforms. The rustc-dev-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. |
60c5eb7d XL |
101 | |
102 | 6. Click the Run build step in the job to get the console log for the step. | |
103 | ||
104 | 7. Click on the log and Ctrl-f to get a search box in the log | |
105 | ||
6a06907d | 106 | 8. Search for rustc-dev-guide. This gets you to the place where the links are checked. It is usually ~11K lines into the log. |
60c5eb7d XL |
107 | |
108 | 9. Look at the links in the log near that point in the log | |
109 | ||
74b04a01 | 110 | 10. Fix those links in the rustc-dev-guide (by making a PR in the rustc-dev-guide repo) |
60c5eb7d | 111 | |
74b04a01 | 112 | 11. Make a PR on the rust-lang/rust repo to update the rustc-dev-guide git submodule in src/docs/rustc-dev-guide. |
60c5eb7d XL |
113 | To make a PR, the following steps are useful. |
114 | ||
115 | ```bash | |
116 | # Assuming you already cloned the rust-lang/rust repo and you're in the correct directory | |
74b04a01 | 117 | git submodule update --remote src/doc/rustc-dev-guide |
60c5eb7d | 118 | git add -u |
74b04a01 | 119 | git commit -m "Update rustc-dev-guide" |
60c5eb7d | 120 | # Note that you can use -i, which is short for --incremental, in the following command |
6a06907d | 121 | ./x.py test --incremental src/doc/rustc-dev-guide # This is optional and should succeed anyway |
60c5eb7d XL |
122 | # Open a PR in rust-lang/rust |
123 | ``` | |
124 | ||
125 | 12. Wait for PR to merge | |
126 | ||
74b04a01 | 127 | VoilĂ ! |