From 75497d550b79b0db075ed46160147e7b7ab6f6ff Mon Sep 17 00:00:00 2001 From: Michael Bryan Date: Mon, 12 Mar 2018 18:51:08 +0800 Subject: [PATCH] Addressed some of @nrc and @mark-i-m's comments --- src/appendix-code-index.md | 23 ++++++++++++++--------- src/rustc-driver.md | 13 +++++++++---- 2 files changed, 23 insertions(+), 13 deletions(-) diff --git a/src/appendix-code-index.md b/src/appendix-code-index.md index 2097d61a..f6dcb9c3 100644 --- a/src/appendix-code-index.md +++ b/src/appendix-code-index.md @@ -6,12 +6,17 @@ compiler. Item | Kind | Short description | Chapter | Declaration ----------------|----------|-----------------------------|--------------------|------------------- -`CodeMap` | struct | The CodeMap maps the AST nodes to their source code | [The parser](the-parser.html) | [src/libsyntax/codemap.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/codemap.rs) -`CompileState` | struct | State that is passed to a callback at each compiler pass | [The Rustc Driver](rustc-driver.html) | [src/librustc_driver/driver.rs](https://github.com/rust-lang/rust/blob/master/src/librustc_driver/driver.rs) -`ast::Crate` | struct | Syntax-level representation of a parsed crate | | [src/librustc/hir/mod.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/ast.rs) -`hir::Crate` | struct | Top-level data structure representing the crate being compiled | | [src/librustc/hir/mod.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/hir/mod.rs) -`ParseSess` | struct | This struct contains information about a parsing session | [The parser](the-parser.html) | [src/libsyntax/parse/mod.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/parse/mod.rs) -`StringReader` | struct | This is the lexer used during parsing. It consumes characters from the raw source code being compiled and produces a series of tokens for use by the rest of the parser | [The parser](the-parser.html) | [src/libsyntax/parse/lexer/mod.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/parse/lexer/mod.rs) -`Session` | struct | The data associated with a compilation session | [the Parser](the-parser.html), [The Rustc Driver](rustc-driver.html) | [src/librustc/session/mod.html](https://github.com/rust-lang/rust/blob/master/src/librustc/session/mod.rs) -`TraitDef` | struct | This struct contains a trait's definition with type information | [The `ty` modules](ty.html) | [src/librustc/ty/trait_def.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/ty/trait_def.rs) -`TyCtxt<'cx, 'tcx, 'tcx>` | type | The "typing context". This is the central data structure in the compiler. It is the context that you use to perform all manner of queries. | [The `ty` modules](ty.html) | [src/librustc/ty/context.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/ty/context.rs) +`CodeMap` | struct | The CodeMap maps the AST nodes to their source code | [The parser] | [src/libsyntax/codemap.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/codemap.rs) +`CompileState` | struct | State that is passed to a callback at each compiler pass | [The Rustc Driver] | [src/librustc_driver/driver.rs](https://github.com/rust-lang/rust/blob/master/src/librustc_driver/driver.rs) +`ast::Crate` | struct | Syntax-level representation of a parsed crate | [The parser] | [src/librustc/hir/mod.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/ast.rs) +`hir::Crate` | struct | More abstract, compiler-friendly form of a crate's AST | [The Hir] | [src/librustc/hir/mod.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/hir/mod.rs) +`ParseSess` | struct | This struct contains information about a parsing session | [the Parser] | [src/libsyntax/parse/mod.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/parse/mod.rs) +`Session` | struct | The data associated with a compilation session | [the Parser], [The Rustc Driver] | [src/librustc/session/mod.html](https://github.com/rust-lang/rust/blob/master/src/librustc/session/mod.rs) +`StringReader` | struct | This is the lexer used during parsing. It consumes characters from the raw source code being compiled and produces a series of tokens for use by the rest of the parser | [The parser] | [src/libsyntax/parse/lexer/mod.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/parse/lexer/mod.rs) +`TraitDef` | struct | This struct contains a trait's definition with type information | [The `ty` modules] | [src/librustc/ty/trait_def.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/ty/trait_def.rs) +`TyCtxt<'cx, 'tcx, 'tcx>` | type | The "typing context". This is the central data structure in the compiler. It is the context that you use to perform all manner of queries. | [The `ty` modules] | [src/librustc/ty/context.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/ty/context.rs) + +[The HIR]: hir.html +[The parser]: the-parser.html +[The Rustc Driver]: rustc-driver.html +[The `ty` modules]: ty.html diff --git a/src/rustc-driver.md b/src/rustc-driver.md index b21cc366..7e6eb7e2 100644 --- a/src/rustc-driver.md +++ b/src/rustc-driver.md @@ -8,7 +8,7 @@ managing state such as the [`CodeMap`] \(maps AST nodes to source code), stuff). The `rustc_driver` crate also provides external users with a method for running code at particular times during the compilation process, allowing third parties to effectively use `rustc`'s internals as a library for -analysing a crate. +analysing a crate or emulating the compiler in-process (e.g. the RLS). For those using `rustc` as a library, the `run_compiler()` function is the main entrypoint to the compiler. Its main parameters are a list of command-line @@ -20,10 +20,12 @@ of each phase. From `rustc_driver`'s perspective, the main phases of the compiler are: 1. *Parse Input:* Initial crate parsing -2. *Configure and Expand:* Resolve `#[cfg]` attributes and expand macros -3. *Run Analysis Passes:* Run the resolution, typechecking, region checking +2. *Configure and Expand:* Resolve `#[cfg]` attributes, name resolution, and + expand macros +3. *Run Analysis Passes:* Run trait resolution, typechecking, region checking and other miscellaneous analysis passes on the crate -4. *Translate to LLVM:* Turn the analysed program into executable code +4. *Translate to LLVM:* Translate to the in-memory form of LLVM IR and turn it + into an executable/object files The `CompileController` then gives users the ability to inspect the ongoing compilation process @@ -37,6 +39,9 @@ compilation process The `CompileState`'s various `state_after_*()` constructors can be inspected to determine what bits of information are available to which callback. +> **Warning:** By its very nature, the internal compiler APIs are always going +> to be unstable. That said, we do try not to break things unnecessarily. + ## A Note On Lifetimes The Rust compiler is a fairly large program containing lots of big data