Double-check we did everything from rust-lang/rust#40902

[pnkfelix]

rust-lang/rust#40902 had a long-ish ongoing list of items that we wanted to document somewhere official.

It was closed sometime after the rustc-guide was created, since it was no longer actionable within the rust-lang/rust repo. But I think there is some evidence that good ideas of things to document are still embedded in that issue and its comment thread.

[igaray]

I reviewed the linked closed issue, and found the following: Items which have not been address should have new issues created and be checked, and once all items are checked this issue could be closed. Comments helping me find the unchecked boxed are appreciated!

• [x] How to build the compiler and how to run the compiler you built

  • [x] First off, explaining about --stage 1 and --incremental arguments
  • [x] Then, once you run ./x.py build --incremental, it's not obvious where to find compiled executable or how to run it
  • [x] For bonus points, we could publish some kind of rustup toolchain instructions, so that you can just type rustc and have it work (that's how my setup works, at least, I should document it publicly)

  Already documented here and here

• [ ] Advice on effective use of RUST_LOG

  • [ ] Common modules you may want to log
  • [ ] Direct the output into a file
  • [ ] -Z verbose for more details

• [ ] A list of the various debugging outputs the compiler supports

  • [ ] --unpretty,
  • [ ] MIR dump,
  • [ ] CGU partitions,
  • [ ] dep-graph
  • [ ] which commandline arguments or environment variables are needed to generate them
  • [ ] the kind of filtering they support (e.g. just dump MIR for one function)

• [ ] Tools directories nuke command

  Another useful inclusion would be the "nuke the tools directories" command. 
  I use `alias nuketools="rm -rf $RUSTDIR/build/*/*-tools"` to remove affected 
  files when there are version conflicts.

• [x] Documentation for rustc types should be added.

  Currently we have to go to @Manishearth's site to get access to the internal docs. 
  Newcomers might not know what a Ty or Ctx is.

The rustc docs are hosted and the ty lecture efforts cover those types.

• [x] In the same vein the internal types should be documented.

  There's next to nothing on them and if you don't know what they are you're 
  left fumbling trying to figure them out. 
  Now if you hack on rustc all the time this isn't a problem, but newcomers 
  don't understand them (Like what's a Span? A Ty?). I think there's a good 
  amount of expert bias here and documenting would reduce the mentoring burden 
  for rustc's core team and could increase contribution.

Also covered by the Ty lecture documentation efforts.

• [x] Documenting the design of the compiler

  for new rustc hackers rather than more advanced ones (but having docs for the 
  advanced users would be great too)

The overview chapter issue covers this.

• [x] Compiler tricks like how to make compilation faster

      (using a stage1 rather than stage2 build for testing) or other small 
      things would go a long way to ergonomics

Already documented here and here

• [x] Documenting how x.py works and the most common use cases for it to make fast builds or how it works if people want to work on it.

• [ ] We should generate a list of all types in the compiler, sorted by how often they are used, and make sure that the top N have doc comments and useful explanations

• [ ] A write-up on building from source on a Mac particularly the dependencies installation would be great!

[jyn514]

I think a lot of the debugging has since been documented in https://rustc-dev-guide.rust-lang.org/compiler-debugging.html and https://rustc-dev-guide.rust-lang.org/mir/debugging.html.