From a4f0021f897630f8e12ef59b83d1859b9031c224 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Thu, 17 May 2012 10:10:18 -0700 Subject: [PATCH] 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 --- src/rustc/README.txt | 55 ++++++++++++++++++++++++++++---------------- 1 file changed, 35 insertions(+), 20 deletions(-) diff --git a/src/rustc/README.txt b/src/rustc/README.txt index 9ee501c4c3b..adf9492e1ed 100644 --- a/src/rustc/README.txt +++ b/src/rustc/README.txt @@ -1,10 +1,17 @@ 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. +If you wish to expand on this document, or have a more experienced +Rust contributor add anything else to it, please get in touch: + +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 @@ -12,14 +19,20 @@ High-level concepts Rustc consists of the following subdirectories: -syntax/ - pure syntax concerns: lexer, parser, AST. 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 +metadata/ - serializer and deserializer for data required by + separate compilation driver/ - command-line processing, main() entrypoint util/ - ubiquitous types and helper functions 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 this file sequences the various parts together. @@ -28,10 +41,9 @@ this file sequences the various parts together. The 3 central data structures: ------------------------------ -#1: syntax/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: ../librustsyntax/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 @@ -55,7 +67,7 @@ The 3 central data structures: #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 + pointer to an LLVM type, manipulated through the lib::llvm interface. @@ -65,13 +77,16 @@ Control and information flow within the compiler: - 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. +- 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 - run over the resulting AST. Each pass generates new information - about the AST which is stored in various side data structures. +- 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 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 - 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. +- Finally middle/trans.rs 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.