---
title: Rustc Dev Guide WG - Reading Club
tags: dev-guide, rustc
---

# Rustc Dev Guide WG - Reading Club

## Chapters 22 to 30

### spastorino

- overview: it would be great to build a diagram, showing phases, how they communicate, what's their interface, etc. This https://github.com/rust-lang/rustc-dev-guide/issues/1725 may be a good start.
- would be great to have some walkthrough examples, where mainly certain high level things could be explained with examples
- this section is not greatly organized

### jieyouxu

Also mainly thoughts on the current docs, not really technical:

- General feedback
- Diagnostics: creation, emission, translations etc. not given a proper summary / overview
- Lints: lint infra, distinction between early/late/internal lints not cohesively explained
- Agree with per-compiler-crate overview missing
- Would be nice if there was some kind of listing for the various compiler crates like:
| crate name | path | basic overview | entry point | key contacts |
| - | - | - | - | - |
| rustc_resolve | `compiler/rustc_resolve` | resolve stuff | `ResolveCtxt::new` or whatever | anonymous_person |
- Re dev-guide maintenance for these: it doesn't have to be *perfect*, but having something established is nice: easier to change parts than to write the whole thing from scratch
- "Overview of the compiler":
- Seems like sometimes it goes into too much details, and sometimes too little: mixed detail level?
- Entry-points are definitely useful, does it fit here though?
- Should source code organization be discussed *here*?
- Maybe diagnostics should get its own chapter? `DiagnosticBuilder` -> didn't nnethercote rename it?
- One sentence for *many* steps:
> Macro expansion, AST validation, name resolution, and early linting also take place during this stage.
- Queries are not given a proper introduction here
- Lints never mentioned
- "High-level overview of the compiler source code":
- Could use a diagram for the crates dependency structure!
- Big picture could use a big picture!
- Some of the compiler source code subheadings could use a little more overview and not simply delegate to the relevant chapters (maybe?).
- "Bootstrapping":
- Could build steps be visualized? There is `--dry-run -vv` but it might be nice in graphical format like a `.dot` file
- Can the build steps from commonly run commands during dev be visualized?
- Do we have a table of all the possible env vars?

### Mario Carneiro

* > In theory, the stage1 compiler is functionally identical to the stage2 compiler, but in practice there are subtle differences. In particular, the stage1 compiler itself was built by stage0 and hence not by the source in your working directory. This means that the ABI generated by the stage0 compiler may not match the ABI that would have been made by the stage1 compiler, which can cause problems for dynamic libraries, tests, and tools using rustc_private.

Does the compiler not use "dynamic libraries, tests, and tools using rustc_private"? Are they banned in rustc? Otherwise I can see it being possible to not be able to change ABI because the stage1 -> stage2 build fails.

* The chapters 26.2 and 26.3 appear to have been written separately and repeat themselves

### tbkhi - mainly views on the status of the documentation without much perspective on technical specifics

Various uses of `sugar`, `desugar`, `monomorphize`, `lowered`, `codegen`. Some examples of each would help illustrate the differences. Maybe give views of example HIR, THIR, MIR, etc.

Lack of overall summary providing context for _all_ of the compiler crates. Whether that is description tags for each of the compiler crates, or a more comprehensive view as to how they interact during a compile job.

Some of the stages being described might benefit from more specific src references, i.e. `query.md:119:123`. Where it points to the exact function being called, rather than being very general about the methods involved i.e. `incremental-compilation-in-detail.md:377:378`.

In places it seems like a lot of description goes into fundamental concepts (i.e. Hashing) and related implications.