Update README files
This commit is contained in:
Brian Anderson
parent
f2d76bcd7d
commit
fcbdac96dd
@ -4,6 +4,10 @@ Source layout:
|
||||
|
||||
comp/ The self-hosted compiler
|
||||
|
||||
lib/ The standard library
|
||||
|
||||
rustllvm/ LLVM support code
|
||||
|
||||
rt/ The runtime system
|
||||
rt/rust_*.cpp - The majority of the runtime services
|
||||
rt/isaac - The PRNG used for pseudo-random choices in the runtime
|
||||
@ -11,7 +15,7 @@ rt/bigint - The bigint library used for the 'big' type
|
||||
rt/uthash - Small hashtable-and-list library for C, used in runtime
|
||||
rt/{sync,util} - Small utility classes for the runtime.
|
||||
|
||||
test/ Testsuite (for both bootstrap and self-hosted)
|
||||
test/ Testsuite
|
||||
test/compile-fail - Tests that should fail to compile
|
||||
test/run-fail - Tests that should compile, run and fail
|
||||
test/run-pass - Tests that should compile, run and succeed
|
||||
|
||||
@ -2,8 +2,9 @@ An informal guide to reading and working on the rustc compiler.
|
||||
==================================================================
|
||||
|
||||
If you wish to expand on this document, or have one of the
|
||||
slightly-more-familiar authors add anything else to it, please get in touch or
|
||||
file a bug. Your concerns are probably the same as someone else's.
|
||||
slightly-more-familiar authors add anything else to it, please get in
|
||||
touch or file a bug. Your concerns are probably the same as someone
|
||||
else's.
|
||||
|
||||
|
||||
High-level concepts
|
||||
@ -13,65 +14,63 @@ Rustc consists of the following subdirectories:
|
||||
|
||||
front/ - front-end: lexer, parser, AST.
|
||||
middle/ - middle-end: resolving, typechecking, translating
|
||||
back/ - back-end: linking and ABI
|
||||
driver/ - command-line processing, main() entrypoint
|
||||
util/ - ubiquitous types and helper functions
|
||||
lib/ - bindings to LLVM
|
||||
pretty/ - pretty-printing
|
||||
|
||||
The entry-point for the compiler is main() in driver/rustc.rs, and this file
|
||||
sequences the various parts together.
|
||||
The entry-point for the compiler is main() in driver/rustc.rs, and
|
||||
this file sequences the various parts together.
|
||||
|
||||
|
||||
The 3 central data structures:
|
||||
------------------------------
|
||||
|
||||
#1: front/ast.rs defines the AST. The AST is treated as immutable after
|
||||
parsing despite containing some mutable types (hashtables and such).
|
||||
There are three interesting details to know about this structure:
|
||||
#1: front/ast.rs defines the AST. The AST is treated as immutable
|
||||
after parsing despite containing some mutable types (hashtables
|
||||
and such). There are three interesting details to know about this
|
||||
structure:
|
||||
|
||||
- Many -- though not all -- nodes within this data structure are wrapped
|
||||
in the type spanned[T], meaning that the front-end has marked the
|
||||
input coordinates of that node. The member .node is the data itself,
|
||||
the member .span is the input location (file, line, column; both low
|
||||
and high).
|
||||
- Many -- though not all -- nodes within this data structure are
|
||||
wrapped in the type spanned[T], meaning that the front-end has
|
||||
marked the input coordinates of that node. The member .node is
|
||||
the data itself, the member .span is the input location (file,
|
||||
line, column; both low and high).
|
||||
|
||||
- Many other nodes within this data structure carry a def_id. These
|
||||
nodes represent the 'target' of some name reference elsewhere in the
|
||||
tree. When the AST is resolved, by middle/resolve.rs, all names wind
|
||||
up acquiring a def that they point to. So anything that can be
|
||||
pointed-to by a name winds up with a def_id.
|
||||
- Many other nodes within this data structure carry a
|
||||
def_id. These nodes represent the 'target' of some name
|
||||
reference elsewhere in the tree. When the AST is resolved, by
|
||||
middle/resolve.rs, all names wind up acquiring a def that they
|
||||
point to. So anything that can be pointed-to by a name winds
|
||||
up with a def_id.
|
||||
|
||||
- Many nodes carry an additional type 'ann', for annotations. These
|
||||
nodes are those that later stages of the middle-end add information
|
||||
to, augmenting the basic structure of the tree. Currently that
|
||||
includes the calculated type of any node that has a type; it will also
|
||||
likely include typestates, layers and effects, when such things are
|
||||
calculated.
|
||||
#2: middle/ty.rs defines the datatype sty. This is the type that
|
||||
represents types after they have been resolved and normalized by
|
||||
the middle-end. The typeck phase converts every ast type to a
|
||||
ty::sty, and the latter is used to drive later phases of
|
||||
compilation. Most variants in the ast::ty tag have a
|
||||
corresponding variant in the ty::sty tag.
|
||||
|
||||
#2: middle/ty.rs defines the datatype ty.t, with its central member ty.struct.
|
||||
This is the type that represents types after they have been resolved and
|
||||
normalized by the middle-end. The typeck phase converts every ast type to
|
||||
a ty.t, and the latter is used to drive later phases of compilation. Most
|
||||
variants in the ast.ty tag have a corresponding variant in the ty.struct
|
||||
tag.
|
||||
|
||||
#3: lib/llvm.rs defines the exported types ValueRef, TypeRef, BasicBlockRef,
|
||||
and several others. Each of these is an opaque pointer to an LLVM type,
|
||||
manipulated through the lib.llvm interface.
|
||||
#3: lib/llvm.rs defines the exported types ValueRef, TypeRef,
|
||||
BasicBlockRef, and several others. Each of these is an opaque
|
||||
pointer to an LLVM type, manipulated through the lib.llvm
|
||||
interface.
|
||||
|
||||
|
||||
Control and information flow within the compiler:
|
||||
-------------------------------------------------
|
||||
|
||||
- main() in driver/rustc.rs assumes control on startup. Options are parsed,
|
||||
platform is detected, etc.
|
||||
- main() in driver/rustc.rs assumes control on startup. Options are
|
||||
parsed, platform is detected, etc.
|
||||
|
||||
- front/parser.rs is driven over the input files.
|
||||
|
||||
- Multiple middle-end passes (middle/resolve.rs, middle/typeck.rs) are run
|
||||
over the resulting AST. Each pass produces a new AST with some number of
|
||||
annotations or modifications.
|
||||
- Multiple middle-end passes (middle/resolve.rs, middle/typeck.rs) are
|
||||
run over the resulting AST. Each pass generates new information
|
||||
about the AST which is stored in various side data structures.
|
||||
|
||||
- Finally middle/trans.rs is applied to the AST, which performs a
|
||||
type-directed translation to LLVM-ese. When it's finished synthesizing LLVM
|
||||
values, rustc asks LLVM to write them out as an executable, on which the
|
||||
normal LLVM pipeline (opt, llc, as) was run.
|
||||
type-directed translation to LLVM-ese. When it's finished
|
||||
synthesizing LLVM values, rustc asks LLVM to write them out in some
|
||||
form (.bc, .o) and possibly run the system linker.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user