In my previous post, I talked about the idea of drafting a “Rust Compiler Book”. I wanted to talk about how we might go about this. I think there are a few interesting questions to discuss:
- Where to host the book?
- How to describe and delegate the work?
Where to host the book
Currently, we have documentation scattered about in various places:
- The Forge, the source for which lives in this github repo
- markdown files in the codebase itself, typically (but not always) named README.md:
- for example, the rustc README
- or the README that describes types and the type context
- the
COMPILER_TESTS.md
file - the
CONTRIBUTING.md
file
There are some pros/cons to each setup. I think that the README files and things are quite scattered and I have the feeling that many people do not find them. On the other hand, the forge appears to be even less well known.
I think what I want is, to some extent, neither of those things. I think I would prefer a “Rust Contributor’s Book” that is structured using rustbook – like the Rust book itself – so that there is a clear table of contents down the left-hand side. I anticipate that people will want to skim around and jump to sections of interest.
Same repo or a different repo?
One of the motivations for having README.md files was so that edits to those files could be done “atomically” in the same PR that changes the code. I also thought people would discover the comments more naturally.
I think that the discoverability of a “book form” is much higher than the READMEs. We can always have links in any given module that direct you to the appropriate chapter in the book:
//! Trait resolution. See the [corresponding chapter from the Rust Compiler Book][c].
//!
//! [c]: ...
But the question still arises whether to have the book in rust-lang/rust or in some other repo. The atomicity of changes is a plus, but I’m not sure how important that is. If we put things in a separate repo, then we don’t have to block on bors, which is also a plus. Ultimately, I am inclined towards a separate repo.
How to describe and delegate the work
I envision the process being roughly like this. We’ll lay out a rough table of contents. People can sign up to write chapters or sections. They can do this in one of three ways:
- If you know how the code works, then you can just write it.
- Of course you are welcome to try and read into the code as well.
- Otherwise, you can schedule some time with me or other mentors, and we can discuss together how the code works, and then you can write it.
Rustdoc. This is independent, but I think that as part of this work we should also make an effort to write rustdoc comments, and we should figure out what it will take to host the compiler comments somewhere public. Writing comments is a good way to help learn the codebase, as well. =)
A rough table of contents
I am thinking something like this.
- How to build the compiler and run what you built
- Describes config.toml settings you want
- Describes common
x.py
commands- e.g.,
./x.py build --incremental src/libstd
- e.g.,
- Effective use of
RUST_LOG
- Handy options, like
-Ztreat-err-as-bug
or-Zdump-mir
- Using the compiler testing framework
- How to run tests
- How debug tests that are failing
- e.g., run the test file by hand
- The compiler source
- The crate structure
- The phases of the IR
- AST vs HIR vs MIR
- Representing types
- the
ty
module, which needs a name btw
- the
- Queries and the tcx arena structure
- The various forms of ids (
NodeId
,DefId
,HirId
, etc) and how they are used- e.g., the way we make hashtables alongside the main IR
- The parser
- Macro expansion
- Name resolution
- HIR lowering
- Representing types (
ty
module in depth)- how interning works
- Type inference
- snapshots
- type folding
- resolution
- Trait resolution
- Type checking
FnCtxt
- MIR construction
- MIR borrowck
- MIR optimizations
- Trans