Update and copyedit README for rustc
Lindsey pointed out that the location of librustsyntax was out-of-date, so I fixed that; noticed a lot of other out-of-date info; and updated it. I also obliterated all passive voice. Yay! Closes #2382
This commit is contained in:
parent
0343b0553b
commit
a4f0021f89
1 changed files with 35 additions and 20 deletions
|
@ -1,10 +1,17 @@
|
||||||
An informal guide to reading and working on the rustc compiler.
|
An informal guide to reading and working on the rustc compiler.
|
||||||
==================================================================
|
==================================================================
|
||||||
|
|
||||||
If you wish to expand on this document, or have one of the
|
If you wish to expand on this document, or have a more experienced
|
||||||
slightly-more-familiar authors add anything else to it, please get in
|
Rust contributor add anything else to it, please get in touch:
|
||||||
touch or file a bug. Your concerns are probably the same as someone
|
|
||||||
else's.
|
https://github.com/mozilla/rust/wiki/Note-development-policy
|
||||||
|
("Communication" subheading)
|
||||||
|
|
||||||
|
or file a bug:
|
||||||
|
|
||||||
|
https://github.com/mozilla/rust/issues
|
||||||
|
|
||||||
|
Your concerns are probably the same as someone else's.
|
||||||
|
|
||||||
|
|
||||||
High-level concepts
|
High-level concepts
|
||||||
|
@ -12,14 +19,20 @@ High-level concepts
|
||||||
|
|
||||||
Rustc consists of the following subdirectories:
|
Rustc consists of the following subdirectories:
|
||||||
|
|
||||||
syntax/ - pure syntax concerns: lexer, parser, AST.
|
|
||||||
front/ - front-end: attributes, conditional compilation
|
front/ - front-end: attributes, conditional compilation
|
||||||
middle/ - middle-end: resolving, typechecking, translating
|
middle/ - middle-end: resolving, typechecking, generating LLVM code
|
||||||
back/ - back-end: linking and ABI
|
back/ - back-end: linking and ABI
|
||||||
|
metadata/ - serializer and deserializer for data required by
|
||||||
|
separate compilation
|
||||||
driver/ - command-line processing, main() entrypoint
|
driver/ - command-line processing, main() entrypoint
|
||||||
util/ - ubiquitous types and helper functions
|
util/ - ubiquitous types and helper functions
|
||||||
lib/ - bindings to LLVM
|
lib/ - bindings to LLVM
|
||||||
pretty/ - pretty-printing
|
|
||||||
|
The files concerned purely with syntax -- that is, the AST, parser,
|
||||||
|
pretty-printer, lexer, macro expander, and utilities for traversing
|
||||||
|
ASTs -- are in a separate crate called "rustsyntax", whose files are
|
||||||
|
in ./../librustsyntax if the parent directory of front/, middle/,
|
||||||
|
back/, and so on is . .
|
||||||
|
|
||||||
The entry-point for the compiler is main() in driver/rustc.rs, and
|
The entry-point for the compiler is main() in driver/rustc.rs, and
|
||||||
this file sequences the various parts together.
|
this file sequences the various parts together.
|
||||||
|
@ -28,10 +41,9 @@ this file sequences the various parts together.
|
||||||
The 3 central data structures:
|
The 3 central data structures:
|
||||||
------------------------------
|
------------------------------
|
||||||
|
|
||||||
#1: syntax/ast.rs defines the AST. The AST is treated as immutable
|
#1: ../librustsyntax/ast.rs defines the AST. The AST is treated as immutable
|
||||||
after parsing despite containing some mutable types (hashtables
|
after parsing, but it depends on mutable context data structures
|
||||||
and such). There are three interesting details to know about this
|
(mainly hash maps) to give it meaning.
|
||||||
structure:
|
|
||||||
|
|
||||||
- Many -- though not all -- nodes within this data structure are
|
- Many -- though not all -- nodes within this data structure are
|
||||||
wrapped in the type spanned<T>, meaning that the front-end has
|
wrapped in the type spanned<T>, meaning that the front-end has
|
||||||
|
@ -55,7 +67,7 @@ The 3 central data structures:
|
||||||
|
|
||||||
#3: lib/llvm.rs defines the exported types ValueRef, TypeRef,
|
#3: lib/llvm.rs defines the exported types ValueRef, TypeRef,
|
||||||
BasicBlockRef, and several others. Each of these is an opaque
|
BasicBlockRef, and several others. Each of these is an opaque
|
||||||
pointer to an LLVM type, manipulated through the lib.llvm
|
pointer to an LLVM type, manipulated through the lib::llvm
|
||||||
interface.
|
interface.
|
||||||
|
|
||||||
|
|
||||||
|
@ -65,13 +77,16 @@ Control and information flow within the compiler:
|
||||||
- main() in driver/rustc.rs assumes control on startup. Options are
|
- main() in driver/rustc.rs assumes control on startup. Options are
|
||||||
parsed, platform is detected, etc.
|
parsed, platform is detected, etc.
|
||||||
|
|
||||||
- front/parser.rs is driven over the input files.
|
- librustsyntax/parse/parser.rs parses the input files and produces an
|
||||||
|
AST that represents the input crate.
|
||||||
|
|
||||||
- Multiple middle-end passes (middle/resolve.rs, middle/typeck.rs) are
|
- Multiple middle-end passes (middle/resolve.rs, middle/typeck.rs)
|
||||||
run over the resulting AST. Each pass generates new information
|
analyze the semantics of the resulting AST. Each pass generates new
|
||||||
about the AST which is stored in various side data structures.
|
information about the AST and stores it in various environment data
|
||||||
|
structures. The driver is in charge of passing the correct
|
||||||
|
environments to each compiler pass that needs to refer to them.
|
||||||
|
|
||||||
- Finally middle/trans.rs is applied to the AST, which performs a
|
- Finally middle/trans.rs translates the Rust AST to LLVM bitcode in a
|
||||||
type-directed translation to LLVM-ese. When it's finished
|
type-directed way. When it's finished synthesizing LLVM values,
|
||||||
synthesizing LLVM values, rustc asks LLVM to write them out in some
|
rustc asks LLVM to write them out in some form (.bc, .o) and
|
||||||
form (.bc, .o) and possibly run the system linker.
|
possibly run the system linker.
|
||||||
|
|
Loading…
Reference in a new issue