---
tags: dev-guide, rustc
---

# Rustc Dev Guide WG - Master Document

- [Agenda](https://hackmd.io/75x4U2e1Qp2f-lg7V09nGA)
- [Check-ins](https://hackmd.io/Umz8k0PwRb-YVUUEK8i0aQ)

## Tasks

- [ ] [Define how would we want to structure the guide](https://hackmd.io/5BnDamiMSFOO8A_S5xggYQ?both)
- Make it more engaging to read?
- Move procedures to forge or to an appendix?
- https://rust-lang.github.io/rustc-guide/stability.html
- https://rust-lang.github.io/rustc-guide/implementing_new_features.html
- https://rust-lang.github.io/rustc-guide/stabilization_guide.html
- Reorganize part 1 in general
- think about a section that contains debugging/profiling/walkthrough/tools/etc.
- where to put the contributing stuff
- where to put procedures about various things, like stabilizing features?
- [ ] Technical debt (lots of potential cleanup, followup work, lots of open issues)
- mark-i-m: I particularly want to go through open issues and triage them systematically and fix low-hanging fruit. I know this is tedious work, but I feel like we need to do it at some point...
- [ ] Write a walkthrough section about what the compiler does to your code
- It may also be nice to have a concrete example that shows all the compilation phases, artifacts and structures generated along the way.
- walk through compilation of simple program
- link to other chapters for details
- This is more like what the compiler does and how it works high level
- [@Chris Simpkins] Succinct summary of how to visualize each representation stage of the compile process (e.g., `cargo rustc -- -Zunpretty=hir-tree` for HIR)
- Other ideas about walk-through
- More or less an expansion of the "High-level overview of the compiler source" section)
- Content (or links to):
- compiler high level structure
- system requirements & dependencies
- compiler module structure
- crate dependencies
- compiler configuration
- compiler inputs
- compiler outputs
- compiler state
- Walk-through of compiling a meaningful example
- [ ] Write a walkthrough about how a full feature is implemented
- Show how a particular feature was implemented by explaining every corner of the compiler that was touched
- Explain all the technical aspects considered when implementing
- This is more like what is needed top to bottom level to implement a full feature
- https://github.com/rust-lang/rustc-guide/issues/584
- Centril said: Or-patterns have fully recorded their implementation history, so it might be a good "from start to finish" example: https://github.com/rust-lang/rust/issues/54883
- [ ] Mermaid -- add diagrams throughout the guide
- [x] Collect a set of PRs that help understanding some parts of the compiler
- Would be nice if we can collect PRs that are interesting to understand certain things
- [Issue created](https://github.com/rust-lang/rustc-dev-guide/issues/619)
- [x] [@spastorino] Schedule a lecture about LLVM with @Alex Crichton
- Alex can do a lecture with maybe not really up to date content
- mw can do a Q&A session
- asked nikic too
- [x] [@Chris Simpkins] Write a blog post about the Overview chapter effort
- The idea would be like a call for action, for people to help us shape a good Overview chapter
- Could be something like ... we are writing an Overview chapter, here is an idea of what could look like, please give your insights on things you would include
- [Blog post outline / drafts](https://hackmd.io/dXf8Ydq4R4SDrbY1VpPfUA)
- [x] [@mark-i-am] Schedule a lecture about codegen mir -> llvm IR with @nagisa
- nagisa not available for a lecture, but they gave us some notes, which we turned into a few small chapters on codegen/backend
- Collecting holes/questions about backend stuff and incrementally filling in holes: doc is [here](https://hackmd.io/fTJHEkb5TXuKh2ClBL_c_w)
- This is ongoing work...
- [x] [@spastorino] Changing name to rustc-dev-guide or rust-compiler-dev-guide (rcdg?) as per https://github.com/rust-lang/rustc-guide/issues/470?
- [x] [@mark-i-am] Document our sprint like process
- [x] [@spastorino] Schedule meetings for the next couple of months
- [x] [@spastorino] Schedule a lecture about monomorphization/type memory layout with @oli
- @oli doesn't have time ATM for this :(
- [x] [@spastorino] Schedule a lecture about Parallel with @nikomatsakis, @simulacrum or @Alex Crichton
- Everyone agreed that would be nice, the working group is a bit on hold for now on the other hand
- @simulacrum said that he can answer question but can't come up with a general explanation
- This won't happen for now
- [x] Write an Overview chapter
- Overview of the whole picture of the compiler. Main components, what they do and where they live. Main data structures used along and more or less what they are about.
- Merged PR: https://github.com/rust-lang/rustc-dev-guide/pull/633
- Also posted to Inside Rust blog
- Some followup work collected in this issue: https://github.com/rust-lang/rustc-dev-guide/issues/674

## Topics to cover

In priority order ...

- Monomorphization, Type Memory Layout, Codegen, LLVM
- Type checking (completing existing ty chapter)
- Name Resolution
- Errors/Diagnostics chapter
- MIR
- Constants, Promoted Constants in MIR
- Construction of MIR
- Borrow Check: Moves and initialization
- MIR Type check
- Various parts of NLL
- Traits
- Region Constraints
- SLG solver
- Macros, hygiene, proc macros, custom derives, etc.
- We can use petrochenkov's notes from the two meetings we had
- Perhaps we can do this after `Ty`?
- Lexing and Parsing
- MIR
- Optimizations
- Profiling
- Debugging