diff --git a/src/README b/src/README index 4a843a64a09..bc7351f357e 100644 --- a/src/README +++ b/src/README @@ -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 diff --git a/src/comp/README b/src/comp/README index 3598a221b99..dab8fc0a5cd 100644 --- a/src/comp/README +++ b/src/comp/README @@ -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.