Overview Chapter Followup

[mark-i-m]

This issue exists to track things we want to improve on. Please add things here:

• Replace bullets with prose.
• Perhaps move some of the content about command line parsing, lexing, and parsing to the appropriate chapters.
• More info on type checking and type inference.
• Fix some of the TODOs
• add more links to other parts of the guide
• add diagrams
• answer unresolved questions at the bottom
• figure out where the following happen and add them back to the list of steps
  • type checking
  • trait solving
  • const eval
  • size optimizations
• Perhaps use more content from https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp/topic/history.20of.20typeck.20and.20borrowck about HAIR
• find out if there are other reasons to use query system beyond incremental
• improve descriptions of bootstrapping.
• verify info about parallel rustc effort

[mark-i-m]

cc @rust-lang/wg-rustc-dev-guide

[jyn514]

Replace bullets with prose

This goal is surprising to me, why prose? I find bullets easier to read.

find out if there are other reasons to use query system beyond incremental

You don't need to catalogue all the necessary information ahead of time (you can have unknown knowns). For example lints wouldn't need to state ahead of time whether they needed typeck to run or not: https://discord.com/channels/442252698964721669/443151243398086667/724028959209291817

improve descriptions of bootstrapping

I'm interested in helping with this.

[tshepang]

I also find bullets more easy... prose can be intimidating.

[mark-i-m]

This goal is surprising to me, why prose? I find bullets easier to read.

That's helpful feedback. I think the original motivation was that the bullet points in this chapter already contain paragraphs, so prose may be a bit more natural...

I'm interested in helping with this.

Awesome! Thanks :)

So IIRC, that was referring to this para: https://rustc-dev-guide.rust-lang.org/overview.html#bootstrapping

Basically, there was a feeling that it moves too fast and wouldn't make sense to new comers. Any thoughts?

[jyn514]

• There should be a link to https://en.wikipedia.org/wiki/Bootstrapping_(compilers)
• The first question everyone has is 'where did the first compiler come from?' We should link to https://github.com/rust-lang/rust/tree/ef75860a0a72f79f97216f8aaa5b388d98da6480/src/boot, even though it doesn't help people build rustc I think it will help understanding what's going on.

• one of the major users of Rust is Rust

This is really confusing. It would be better phrased as

one of the major users of Rust is the rust compiler

• There's no mention of src/bootstrap here.
• There's no overview of different stages. This is especially bad because rustc numbers them differently than most compilers.

In general I think it would be better to have a separate page for bootstrap and replace this section with a link to that page. Otherwise there's too much in too little time.

I have more thoughts but I think they would be better placed in a PR making these changes directly :P

[jyn514]

Oh hmm I see there's a separate building/bootstrap.md page. Maybe most of this section could be moved there?