Rust: more forge docs for mentoring are needed

[nikomatsakis]

I've been finding that there are a lot of undocumented things you have to learn if you want to get started hacking on rustc. If we want to encourage people to get involved -- and we do! -- we should try to ensure that things are as well-documented as possible. I think that these docs should all be on The Rust Forge.

This issue is intended as a clearing house to track things that it would be useful to document. Here are some suggestions. I will try to move items from comments up here into the top issue (or feel free to do so yourself, if you have write permissions). Also feel free to open a separate issue on a particular topic (and link to it from here).

• [ ] How to build the compiler and how to run the compiler you built
  
  
  
  • First off, explaining about --stage 1 and --incremental arguments
  
  
  • Then, once you run ./x.py build --incremental, it's not obvious where to find compiled executable or how to run it
  
  
  • 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)
  
  
• [ ] 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 etc) (from this comment)
  
  
  
  • 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)
  
  

[nikomatsakis]

cc @rust-lang/docs

[steveklabnik]

This would be wonderful and amazing and I really, really want it.

[michaelwoerister]

A list of the various debugging outputs the compiler supports (--unpretty, MIR dump, CGU partitions, dep-graph etc):

• 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)

UPDATE(nikomatsakis): promoted to main comment

[GuillaumeGomez]

I think we talked about this a while ago but didn't consider it as a priority back then. Might be worth (a lot!!) to give it another try.

[steveklabnik]

@nikomatsakis i'm assuming you filed this here and not against https://github.com/rust-lang-nursery/rust-forge for visibility reasons? technically it should be over there

[est31]

How to run rustc in gdb (inside the rustbuild environment) has been a question that commonly came up. Its non trivial because of all the env var setting. See also #39888

[cramertj]

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.

[pmatos]

@nikomatsakis , @steveklabnik as a followup to https://internals.rust-lang.org/t/understanding-the-compiler/5012 I would like to help with this. If I were to start writing some docs for this, which tools/markup should I use and where should it be hosted?

A side note, I am not familiar with rustc however I find that sometimes learning through documentation writing is a very useful thing to do both for the writer and for the reader.

[steveklabnik]

@pmatos https://github.com/rust-lang-nursery/rust-forge

[est31]

+1 to @cramertj 's idea, you are very likely to run into #39751 or #39396 sooner or later, so pointing out the workarounds is a good idea.

[mgattozzi]

I talked with @nikomatsakis about this at the Boston Rust meetup and he told me to write up a list for this. Here are a few things I think should also be covered:

• Documentation for rustc types should be added. Currently we have to go to @Manishearth's site to get access to the internal docs. New comers might not know what a Ty or Ctx is.
• 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.
• 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)
• 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
• 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.

I'm sure there's more but I feel this would be a good starting point if we want to revitalize rust-forge as a one stop shop for all things rustc. I never had heard about it and it would really help expand helping on the compiler. The Rust community is smart, they just need some documentation to help them along and to contribute. I know I'll be helping out with this, so please let me know how I can help advance the above goals and others.

[Manishearth]

I can help answer qs about internal types for documentation, but probably will never get around to doing it myself. I did do a preliminary pass a few years ago adding basic docs to the most common types.

[nikomatsakis]

Some thoughts I had:

• We should be publishing the crate docs somewhere "official" (many thanks to @Manishearth for filling the gap)
• 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

[Manishearth]

Please please please official internals docs 😄

[gaurikholkar]

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

[mgattozzi]

I'm still working on trying to get forge to self host docs but haven't had enough time to work through the CI stuff yet to get it to build them.

[steveklabnik]

We now have the rustc guide, and the compiler docs are hosted. I'm going to close this bug, as it's not clear to me that it's usefully tracking anything anymore.