From 41a7177d6a4f54b690b057fc17d213300da15d5d Mon Sep 17 00:00:00 2001 From: Ms2ger Date: Fri, 20 Mar 2015 12:55:07 +0100 Subject: [PATCH 1/2] Update librustc's README.txt for some code changes and reformat it. --- src/librustc/README.txt | 102 +++++++++++++++++++++------------------- 1 file changed, 53 insertions(+), 49 deletions(-) diff --git a/src/librustc/README.txt b/src/librustc/README.txt index 9b364768208eb..31812e19aee86 100644 --- a/src/librustc/README.txt +++ b/src/librustc/README.txt @@ -16,17 +16,17 @@ Your concerns are probably the same as someone else's. The crates of rustc =================== -Rustc consists of four crates altogether: `libsyntax`, `librustc`, -`librustc_back`, and `librustc_trans` (the names and divisions are not -set in stone and may change; in general, a finer-grained division of -crates is preferable): +Rustc consists of a number of crates, including `libsyntax`, +`librustc`, `librustc_back`, `librustc_trans`, and `librustc_driver` +(the names and divisions are not set in stone and may change; +in general, a finer-grained division of crates is preferable): -- `libsyntax` contains those things concerned purely with syntax -- +- `libsyntax` contains those things 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 - "syntax", whose files are in ./../libsyntax, where . is the current - directory (that is, the parent directory of front/, middle/, back/, - and so on). + utilities for traversing ASTs – are in a separate crate called + "syntax", whose files are in `./../libsyntax`, where `.` is the + current directory (that is, the parent directory of front/, middle/, + back/, and so on). - `librustc` (the current directory) contains the high-level analysis passes, such as the type checker, borrow checker, and so forth. @@ -41,31 +41,35 @@ crates is preferable): of miscellany. In general it contains code that runs towards the end of the compilation process. +- `librustc_driver` invokes the compiler from `libsyntax`, then the + analysis phases from `librustc`, and finally the lowering and + codegen passes from `librustc_trans`. + Roughly speaking the "order" of the three crates is as follows: libsyntax -> librustc -> librustc_trans | | +-----------------+-------------------+ | - librustc_trans/driver + librustc_driver -Here the role of `librustc_trans/driver` is to invoke the compiler -from libsyntax, then the analysis phases from librustc, and finally -the lowering and codegen passes from librustc_trans. Modules in the rustc crate ========================== -The rustc crate itself consists of the following subdirectories +The rustc crate itself consists of the following submodules (mostly, but not entirely, in their own directories): -session - options and data that pertain to the compilation session as a whole -middle - middle-end: name resolution, typechecking, LLVM code - generation -metadata - encoder and decoder for data required by - separate compilation -util - ubiquitous types and helper functions -lib - bindings to LLVM +- session: options and data that pertain to the compilation session as + a whole +- middle: middle-end: name resolution, typechecking, LLVM code + generation +- metadata: encoder and decoder for data required by separate + compilation +- plugin: infrastructure for compiler plugins +- lint: infrastructure for compiler warnings +- util: ubiquitous types and helper functions +- lib: bindings to LLVM The entry-point for the compiler is main() in the librustc_trans crate. @@ -73,34 +77,34 @@ crate. The 3 central data structures: ------------------------------ -#1: ./../libsyntax/ast.rs defines the AST. The AST is treated as immutable - after parsing, but it depends on mutable context data structures - (mainly hash maps) to give it meaning. +1. `./../libsyntax/ast.rs` defines the AST. The AST is treated as + immutable after parsing, but it depends on mutable context data + structures (mainly hash maps) to give it meaning. - - Many -- though not all -- nodes within this data structure are - wrapped in the type `spanned`, 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`, 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`. -#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 `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. -#3: lib/llvm.rs (in librustc_trans) 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. `./../librustc_llvm/lib.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: @@ -109,10 +113,10 @@ Control and information flow within the compiler: - main() in lib.rs assumes control on startup. Options are parsed, platform is detected, etc. -- ./../libsyntax/parse/parser.rs parses the input files and produces an AST - that represents the input crate. +- `./../libsyntax/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) +- Multiple middle-end passes (`middle/resolve.rs`, `middle/typeck.rs`) analyze the semantics of the resulting AST. Each pass generates new information about the AST and stores it in various environment data structures. The driver passes environments to each compiler pass @@ -121,4 +125,4 @@ Control and information flow within the compiler: - Finally, the `trans` module in `librustc_trans` translates the Rust AST to LLVM bitcode in a type-directed way. 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. + form (`.bc`, `.o`) and possibly run the system linker. From 3bdb5c3078a69becbf249739c8099ac9acb3513d Mon Sep 17 00:00:00 2001 From: Ms2ger Date: Fri, 20 Mar 2015 13:28:06 +0100 Subject: [PATCH 2/2] Make librustc's markdown README.txt claim to be markdown. This allows github to render it with formatting. --- src/librustc/{README.txt => README.md} | 0 src/librustc_trans/README.txt | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename src/librustc/{README.txt => README.md} (100%) diff --git a/src/librustc/README.txt b/src/librustc/README.md similarity index 100% rename from src/librustc/README.txt rename to src/librustc/README.md diff --git a/src/librustc_trans/README.txt b/src/librustc_trans/README.txt index 3904db4433c89..1f416d5404d27 100644 --- a/src/librustc_trans/README.txt +++ b/src/librustc_trans/README.txt @@ -1 +1 @@ -See the README.txt in ../librustc. +See the README.md in ../librustc.