src/doc/rustc-dev-guide/README.md

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