1 An informal guide to reading and working on the rustc compiler.
2 ==================================================================
4 If you wish to expand on this document, or have a more experienced
5 Rust contributor add anything else to it, please get in touch:
7 * https://internals.rust-lang.org/
8 * https://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust
12 https://github.com/rust-lang/rust/issues
14 Your concerns are probably the same as someone else's.
19 Rustc consists of a number of crates, including `libsyntax`,
20 `librustc`, `librustc_back`, `librustc_trans`, and `librustc_driver`
21 (the names and divisions are not set in stone and may change;
22 in general, a finer-grained division of crates is preferable):
24 - `libsyntax` contains those things concerned purely with syntax –
25 that is, the AST, parser, pretty-printer, lexer, macro expander, and
26 utilities for traversing ASTs – are in a separate crate called
27 "syntax", whose files are in `./../libsyntax`, where `.` is the
28 current directory (that is, the parent directory of front/, middle/,
31 - `librustc` (the current directory) contains the high-level analysis
32 passes, such as the type checker, borrow checker, and so forth.
33 It is the heart of the compiler.
35 - `librustc_back` contains some very low-level details that are
36 specific to different LLVM targets and so forth.
38 - `librustc_trans` contains the code to convert from Rust IR into LLVM
39 IR, and then from LLVM IR into machine code, as well as the main
40 driver that orchestrates all the other passes and various other bits
41 of miscellany. In general it contains code that runs towards the
42 end of the compilation process.
44 - `librustc_driver` invokes the compiler from `libsyntax`, then the
45 analysis phases from `librustc`, and finally the lowering and
46 codegen passes from `librustc_trans`.
48 Roughly speaking the "order" of the three crates is as follows:
50 libsyntax -> librustc -> librustc_trans
52 +-----------------+-------------------+
57 Modules in the rustc crate
58 ==========================
60 The rustc crate itself consists of the following submodules
61 (mostly, but not entirely, in their own directories):
63 - session: options and data that pertain to the compilation session as
65 - middle: middle-end: name resolution, typechecking, LLVM code
67 - metadata: encoder and decoder for data required by separate
69 - plugin: infrastructure for compiler plugins
70 - lint: infrastructure for compiler warnings
71 - util: ubiquitous types and helper functions
72 - lib: bindings to LLVM
74 The entry-point for the compiler is main() in the librustc_driver
77 The 3 central data structures:
78 ------------------------------
80 1. `./../libsyntax/ast.rs` defines the AST. The AST is treated as
81 immutable after parsing, but it depends on mutable context data
82 structures (mainly hash maps) to give it meaning.
84 - Many – though not all – nodes within this data structure are
85 wrapped in the type `spanned<T>`, meaning that the front-end has
86 marked the input coordinates of that node. The member `node` is
87 the data itself, the member `span` is the input location (file,
88 line, column; both low and high).
90 - Many other nodes within this data structure carry a
91 `def_id`. These nodes represent the 'target' of some name
92 reference elsewhere in the tree. When the AST is resolved, by
93 `middle/resolve.rs`, all names wind up acquiring a def that they
94 point to. So anything that can be pointed-to by a name winds
97 2. `middle/ty.rs` defines the datatype `sty`. This is the type that
98 represents types after they have been resolved and normalized by
99 the middle-end. The typeck phase converts every ast type to a
100 `ty::sty`, and the latter is used to drive later phases of
101 compilation. Most variants in the `ast::ty` tag have a
102 corresponding variant in the `ty::sty` tag.
104 3. `./../librustc_llvm/lib.rs` defines the exported types
105 `ValueRef`, `TypeRef`, `BasicBlockRef`, and several others.
106 Each of these is an opaque pointer to an LLVM type,
107 manipulated through the `lib::llvm` interface.
110 Control and information flow within the compiler:
111 -------------------------------------------------
113 - main() in lib.rs assumes control on startup. Options are
114 parsed, platform is detected, etc.
116 - `./../libsyntax/parse/parser.rs` parses the input files and produces
117 an AST that represents the input crate.
119 - Multiple middle-end passes (`middle/resolve.rs`, `middle/typeck.rs`)
120 analyze the semantics of the resulting AST. Each pass generates new
121 information about the AST and stores it in various environment data
122 structures. The driver passes environments to each compiler pass
123 that needs to refer to them.
125 - Finally, the `trans` module in `librustc_trans` translates the Rust
126 AST to LLVM bitcode in a type-directed way. When it's finished
127 synthesizing LLVM values, rustc asks LLVM to write them out in some
128 form (`.bc`, `.o`) and possibly run the system linker.