From ba655766c8bc4927cd4d6ac5f46d94d09b48fb8b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=AE=B8=E6=9D=B0=E5=8F=8B=20Jieyou=20Xu=20=28Joe=29?= Date: Mon, 1 Apr 2024 15:25:28 +0100 Subject: [PATCH 1/6] overview: split chapter into high-level overview and a walkthrough --- src/SUMMARY.md | 3 +- src/overview/overview.md | 60 +++++++++++++++++++ src/{overview.md => overview/walkthrough.md} | 61 +------------------- 3 files changed, 63 insertions(+), 61 deletions(-) create mode 100644 src/overview/overview.md rename src/{overview.md => overview/walkthrough.md} (82%) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index bb3aaf177..4272cfe71 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -67,7 +67,8 @@ # High-level Compiler Architecture - [Prologue](./part-2-intro.md) -- [Overview of the compiler](./overview.md) +- [Overview of the compiler](./overview/overview.md) + - [Compiling a Program: A Walkthrough](./overview/walkthrough.md) - [The compiler source code](./compiler-src.md) - [Queries: demand-driven compilation](./query.md) - [The Query Evaluation Model in Detail](./queries/query-evaluation-model-in-detail.md) diff --git a/src/overview/overview.md b/src/overview/overview.md new file mode 100644 index 000000000..72429fb43 --- /dev/null +++ b/src/overview/overview.md @@ -0,0 +1,60 @@ +# Overview of the compiler + +> **WORK IN PROGRESS** + +# References + +- Command line parsing + - Guide: [The Rustc Driver and Interface](rustc-driver.md) + - Driver definition: [`rustc_driver`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/) + - Main entry point: [`rustc_session::config::build_session_options`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/config/fn.build_session_options.html) +- Lexical Analysis: Lex the user program to a stream of tokens + - Guide: [Lexing and Parsing](the-parser.md) + - Lexer definition: [`rustc_lexer`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lexer/index.html) + - Main entry point: [`rustc_lexer::cursor::Cursor::advance_token`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lexer/cursor/struct.Cursor.html#method.advance_token) +- Parsing: Parse the stream of tokens to an Abstract Syntax Tree (AST) + - Guide: [Lexing and Parsing](the-parser.md) + - Guide: [Macro Expansion](macro-expansion.md) + - Guide: [Name Resolution](name-resolution.md) + - Parser definition: [`rustc_parse`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/index.html) + - Main entry points: + - [Entry point for first file in crate](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/passes/fn.parse.html) + - [Entry point for outline module parsing](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_expand/module/fn.parse_external_mod.html) + - [Entry point for macro fragments][parse_nonterminal] + - `AST` definition: [`rustc_ast`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/ast/index.html) + - Feature gating: **TODO** + - Early linting: **TODO** +- The High Level Intermediate Representation (HIR) + - Guide: [The HIR](hir.md) + - Guide: [Identifiers in the HIR](hir.md#identifiers-in-the-hir) + - Guide: [The `HIR` Map](hir.md#the-hir-map) + - Guide: [Lowering `AST` to `HIR`](ast-lowering.md) + - How to view `HIR` representation for your code `cargo rustc -- -Z unpretty=hir-tree` + - Rustc `HIR` definition: [`rustc_hir`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/index.html) + - Main entry point: **TODO** + - Late linting: **TODO** +- Type Inference + - Guide: [Type Inference](type-inference.md) + - Guide: [The ty Module: Representing Types](ty.md) (semantics) + - Main entry point (type inference): [`InferCtxtBuilder::enter`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/infer/struct.InferCtxtBuilder.html#method.enter) + - Main entry point (type checking bodies): [the `typeck` query](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyCtxt.html#method.typeck) + - These two functions can't be decoupled. +- The Mid Level Intermediate Representation (MIR) + - Guide: [The `MIR` (Mid level IR)](mir/index.md) + - Definition: [`rustc_middle/src/mir`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/index.html) + - Definition of sources that manipulates the MIR: [`rustc_mir_build`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_build/index.html), [`rustc_mir_dataflow`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_dataflow/index.html), [`rustc_mir_transform`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/index.html) +- The Borrow Checker + - Guide: [MIR Borrow Check](borrow_check.md) + - Definition: [`rustc_borrowck`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_borrowck/index.html) + - Main entry point: [`mir_borrowck` query](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_borrowck/fn.mir_borrowck.html) +- `MIR` Optimizations + - Guide: [MIR Optimizations](mir/optimizations.md) + - Definition: [`rustc_mir_transform`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/index.html) + - Main entry point: [`optimized_mir` query](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/fn.optimized_mir.html) +- Code Generation + - Guide: [Code Generation](backend/codegen.md) + - Generating Machine Code from `LLVM-IR` with LLVM - **TODO: reference?** + - Main entry point: [`rustc_codegen_ssa::base::codegen_crate`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/base/fn.codegen_crate.html) + - This monomorphizes and produces `LLVM-IR` for one codegen unit. It then + starts a background thread to run LLVM, which must be joined later. + - Monomorphization happens lazily via [`FunctionCx::monomorphize`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/mir/struct.FunctionCx.html#method.monomorphize) and [`rustc_codegen_ssa::base::codegen_instance `](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/base/fn.codegen_instance.html) diff --git a/src/overview.md b/src/overview/walkthrough.md similarity index 82% rename from src/overview.md rename to src/overview/walkthrough.md index 36de212d6..757c1668c 100644 --- a/src/overview.md +++ b/src/overview/walkthrough.md @@ -1,6 +1,4 @@ -# Overview of the compiler - - +# Compiling a Program: A Walkthrough This chapter is about the overall process of compiling a program -- how everything fits together. @@ -383,60 +381,3 @@ For more details on bootstrapping, see - Where do phases diverge for cross-compilation to machine code across different platforms? --> - -# References - -- Command line parsing - - Guide: [The Rustc Driver and Interface](rustc-driver.md) - - Driver definition: [`rustc_driver`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/) - - Main entry point: [`rustc_session::config::build_session_options`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/config/fn.build_session_options.html) -- Lexical Analysis: Lex the user program to a stream of tokens - - Guide: [Lexing and Parsing](the-parser.md) - - Lexer definition: [`rustc_lexer`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lexer/index.html) - - Main entry point: [`rustc_lexer::cursor::Cursor::advance_token`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lexer/cursor/struct.Cursor.html#method.advance_token) -- Parsing: Parse the stream of tokens to an Abstract Syntax Tree (AST) - - Guide: [Lexing and Parsing](the-parser.md) - - Guide: [Macro Expansion](macro-expansion.md) - - Guide: [Name Resolution](name-resolution.md) - - Parser definition: [`rustc_parse`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/index.html) - - Main entry points: - - [Entry point for first file in crate](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/passes/fn.parse.html) - - [Entry point for outline module parsing](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_expand/module/fn.parse_external_mod.html) - - [Entry point for macro fragments][parse_nonterminal] - - `AST` definition: [`rustc_ast`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/ast/index.html) - - Feature gating: **TODO** - - Early linting: **TODO** -- The High Level Intermediate Representation (HIR) - - Guide: [The HIR](hir.md) - - Guide: [Identifiers in the HIR](hir.md#identifiers-in-the-hir) - - Guide: [The `HIR` Map](hir.md#the-hir-map) - - Guide: [Lowering `AST` to `HIR`](ast-lowering.md) - - How to view `HIR` representation for your code `cargo rustc -- -Z unpretty=hir-tree` - - Rustc `HIR` definition: [`rustc_hir`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/index.html) - - Main entry point: **TODO** - - Late linting: **TODO** -- Type Inference - - Guide: [Type Inference](type-inference.md) - - Guide: [The ty Module: Representing Types](ty.md) (semantics) - - Main entry point (type inference): [`InferCtxtBuilder::enter`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/infer/struct.InferCtxtBuilder.html#method.enter) - - Main entry point (type checking bodies): [the `typeck` query](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyCtxt.html#method.typeck) - - These two functions can't be decoupled. -- The Mid Level Intermediate Representation (MIR) - - Guide: [The `MIR` (Mid level IR)](mir/index.md) - - Definition: [`rustc_middle/src/mir`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/index.html) - - Definition of sources that manipulates the MIR: [`rustc_mir_build`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_build/index.html), [`rustc_mir_dataflow`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_dataflow/index.html), [`rustc_mir_transform`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/index.html) -- The Borrow Checker - - Guide: [MIR Borrow Check](borrow_check.md) - - Definition: [`rustc_borrowck`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_borrowck/index.html) - - Main entry point: [`mir_borrowck` query](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_borrowck/fn.mir_borrowck.html) -- `MIR` Optimizations - - Guide: [MIR Optimizations](mir/optimizations.md) - - Definition: [`rustc_mir_transform`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/index.html) - - Main entry point: [`optimized_mir` query](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/fn.optimized_mir.html) -- Code Generation - - Guide: [Code Generation](backend/codegen.md) - - Generating Machine Code from `LLVM-IR` with LLVM - **TODO: reference?** - - Main entry point: [`rustc_codegen_ssa::base::codegen_crate`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/base/fn.codegen_crate.html) - - This monomorphizes and produces `LLVM-IR` for one codegen unit. It then - starts a background thread to run LLVM, which must be joined later. - - Monomorphization happens lazily via [`FunctionCx::monomorphize`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/mir/struct.FunctionCx.html#method.monomorphize) and [`rustc_codegen_ssa::base::codegen_instance `](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/base/fn.codegen_instance.html) From ded643450b88c5b4e3e82c096a3863696891a2e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=AE=B8=E6=9D=B0=E5=8F=8B=20Jieyou=20Xu=20=28Joe=29?= Date: Mon, 1 Apr 2024 15:35:58 +0100 Subject: [PATCH 2/6] overview(R0): add initial draft - Transfer everything from HackMD into a PR. --- src/overview/overview.md | 627 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 605 insertions(+), 22 deletions(-) diff --git a/src/overview/overview.md b/src/overview/overview.md index 72429fb43..c5dc1bffe 100644 --- a/src/overview/overview.md +++ b/src/overview/overview.md @@ -1,60 +1,643 @@ +> Thank you to everyone who contributed to this overview! + +> **NOTES ON THE OVERALL CHAPTER STRUCTURE** +> +> We _embrace_ the query architecture and talk about areas _backwards_ compared +> to traditional compiler texts. Since information dependence of the various +> `rustc` areas form a Direct Acyclic Graph (DAG) at the query view (not acyclic +> at the areas view), it makes sense to start at the root -- the final +> executable -- and traverse the graph in a breadth-first traversal, all the way +> until we get to name resolution. At that point, we can zoom out and talk about +> the non-querified areas (in either reverse order like the querified areas, or +> forwards order like traditional passes-based compilers, depending on which +> order feels more natural). + +> We also want to contextualize each area and _why_ they exist -- what problems +> do they solve? + +In this chapter, we aim to describe `rustc` at a very high-level to show how the +various areas work together. We introduce the _demand-driven architecture_ and +the organization of `rustc` areas by their information dependency into a graph. +For each area, we describe their purpose and motivation, and provide a small +summary with links to chapters that go into more detail. We explain the +distinction between early lints and late lints. We also briefly explore the +compiler's error handling and reporting. + # Overview of the compiler -> **WORK IN PROGRESS** +> **UNDER CONSTRUCTION** + +> - This section lacks motivation and reasoning for the query architecture. + +> **FIXME** Trait solving isn't correct here as it's a bit of a cross-cutting +> concern between multiple areas. +> +> **UNRESOLVED QUESTIONS** How do we describe the relationship between trait +> solving and the areas that it intertwines with? How do we describe error +> handling and `rustc_interface`? Where/how do we describe distinction between +> early lints and late lints? Do we talk about them briefly in this section +> already? + +Conventional compiler texts often describe traditional compilers as being +organized into linear _passes_, where a pass eagerly produces information for a +subsequent pass to consume. `rustc` is organized a bit differently. `rustc` for +the most part adopts an "demand-driven" system, where one area provides +information for another area that demands it via lazily-computed _queries_. If +we view the compiler's knowledge about a crate as a database, then queries are +functions which asks the database for information. Initially, this database of +information is empty. It can be populated on-demand by area requests for +information by queries. Queries can demand information from other sub-queries, +which in turn can demand information from area providers. This information +dependency flow forms a directed acyclic graph (DAG) at the item granularity +whose nodes are queries and leaves are areas which provide the demanded +information. + +> **UNDER CONSTRUCTION** Insert a query diagram to illustrate the above point. + +Ideally, the entire compiler would be organized as queries. However, as of the +time of writing (March 2024), `rustc` still has several areas which are not yet +querified and work like conventional passes. The following diagram illustrates +this distinction as well as the information dependency between areas. We will +explain each area in more detail in the next section. + +> **FIXME** What do we want the arrows to **actually** mean? + +```graphviz +digraph rustc_areas { + graph [pad="0.5", nodesep="0.5", ranksep="0.3", compound=true]; + node [color=Black, shape=box]; + edge [color=Blue]; + + Executable [shape=oval, label="Executables, cdylibs, staticlibs"] + Libraries [shape=oval, label="rlibs, dylibs"] + "Source Code" [shape=oval] + + Executable->{"LLVM", "GCC", "Cranelift"} [color="darkgreen", style="bold", arrowhead=none] + Libraries->{"LLVM", "GCC", "Cranelift"} [color="darkgreen", style="bold", arrowhead=none] + "LLVM"->{"SSA Code Generation"} [color="darkgreen", style="bold", arrowhead=none] + "GCC"->{"SSA Code Generation"} [color="darkgreen", style="bold", arrowhead=none] + "Cranelift"->{"Monomorphization Collection"} [color="darkgreen", style="bold", arrowhead=none] + "Libraries"->{"Metadata Encoding"} [color="darkgreen", style="bold", arrowhead=none] + + subgraph cluster_querified { + graph[style=dashed, bgcolor="lightblue"] + + subgraph cluster_trait_solving_dependent { + graph[style=solid] + "SSA Code Generation"->{"Monomorphization Collection"} + "Monomorphization Collection"->{"MIR Building, Transformations and Analysis"} + "Metadata Encoding"->{"MIR Building, Transformations and Analysis"} + "MIR Building, Transformations and Analysis"->{"THIR Building and Analysis"} + "THIR Building and Analysis"->{"HIR Body Type-checking"} + "HIR Body Type-checking"->{"HIR Well-formedness Checking"} + + label = "Trait-solving dependent" + labelloc=t + labeljust=r + } + + "SSA Code Generation" -> "Trait System" [ltail=cluster_trait_solving_dependent lhead=cluster_querified]; + + "HIR Well-formedness Checking"->{"HIR Type Lowering"} + "HIR Type Lowering"->{"HIR Building"} + "HIR Building"->"Late Name Resolution" [color="red", style="dashed", dir=back] + + "Trait System"->{"HIR Well-formedness Checking", "HIR Body Type-checking", "THIR Building and Analysis", "MIR Building, Transformations and Analysis"} + + label = "Querified" + labelloc=t + labeljust=r + } + + subgraph cluster_non_querified { + graph[style=dashed, bgcolor=lightyellow] + "Late Name Resolution" + "Late Name Resolution"->{"AST Validation"}[color="red", style="dashed", dir=back] + "AST Validation"->{"Macro Expansion, Metadata Loading and Early Name Resolution"} [color="red", style="dashed", dir=back] + {"Macro Expansion, Metadata Loading and Early Name Resolution"}->{"Parsing"} [color="red", style="dashed", dir=back] + {"Parsing"}->{"Macro Expansion, Metadata Loading and Early Name Resolution"} [color="red", style="dashed", dir=back] + "Parsing"->{"Tokenization"} [color="red", style="dashed", dir=back] + "Tokenization" + + + label="Non-querified" + labelloc=t + labeljust=r + } + + "Source Code" + {"Tokenization"}->"Source Code" [color="red", style="dashed", dir=back] + + subgraph cluster_legend { + rankdir=LR + node [shape=plaintext, width=0] + label = "Legend"; + {rank=same; key, key2 } + key [label=< + + + +
Pull-based Dependency 
Push-based Dependency 
Code Generation Pathway 
>] + key2 [label=< + + + +
 
 
 
>] + key:i1:e -> key2:i1:w [color="blue"] + key:i2:e -> key2:i2:w [color="red", style="dashed"] + key:i3:e -> key2:i3:w [color="darkgreen", style="bold"] + } +} +``` + +> **UNDER CONSTRUCTION** Actually explain the graph. Motivate why we are +> describing areas backwards compared to the order of how passes are described +> in conventional compilers, so the next section actually makes sense in terms +> of its ordering. One benefit of doing ordering this way is that it kinda +> forces you to have to talk about the inputs and outputs of each area, and also +> kinda have to motivate _why_ each area exists -- what purpose do they serve? + +## Brief Summaries of the Areas + +> **UNDER CONSTRUCTION** This section lacks exhaustive list of areas and their +> summaries. This should ideally be ordered based on a BFS traversal related to +> the information dependency presented in the previous section. + +We now summarize areas following the order of their information dependency. To +produce the final executable, we take one of the several code generation +pathways. For example, to produce an executable following the LLVM pathway, we +rely on the synthesis of LLVM IR from SSA code generation. Code generation in +turn relies on information produced by Monomorphization Collection, and so on. +We keep following the dependencies for the querified areas until we reach HIR +Lowering, which depends on information from non-querified areas of the compiler. +At that boundary, we make a distinction between the pull-based information +dependency of querified areas versus push-based information dependency of the +non-querified areas. We flip our direction, and trace from the source code until +Late Name Resolution. + +To pass information between areas, the compiler uses various _Intermediate +Representations_ (IRs), which provide common interfaces to allow areas to +communicate with each other. These include but are not limited to: + +- Tokens +- Abstract Syntax Tree (AST) +- High-Level Intermediate Representation (HIR) +- Mid-Level Intermediate Representation (MIR) + +These various IRs gradually transform surface Rust syntax by simplications of +language constructs and enriches the information available to lower-level areas +by many analyses. + +### Querified Areas + +> 🚧 **XXX DO NOT KEEP: EXAMPLE AREA SUMMARY** 🚧 + +> - A succinct summary of the responsibility of the area. +> - Introduce the inputs. Briefly motivate why the inputs are why they are. +> - Motivate the area's existence -- what does it do to / with the inputs? Why? +> - Introduce the outputs. Briefly motivate why the outputs are what they are. +> - Want to know more? Link to details chapter here. Link to "Additional +> References" section below. + +> :warning: **Where does trait system come in?** / **Where do we describe the +> trait system here?** AFAIK, it's both dependent and and provides information +> to multiple areas. Link: + +#### Static-Single Assignment (SSA) Code Generation + +Static Single Assignment (SSA) code generation is responsible for lowering +Mid-Level Intermediate Representation (MIR) into SSA form (another kind of IR) +which has the property that each variable is assigned to exactly once and is +defined before use. Lowering into SSA form simplifies and enables more +optimizations since it simplifies the properties of variables. It also makes it +easier for code generation backends to handle. This area abstracts the common +code generation logic and interfaces which code generation backends will need to +implement. + +In order to lower MIR to SSA, we depend on Monomohprization Collection to +collect _Mono Items_ such as functions, methods and closures which contribute to +code generation. + +See [Code +Generation](https://rustc-dev-guide.rust-lang.org/backend/codegen.html) for more +details. + +#### Monomorphization Collection + +Monomorphization collection is the area responsible for collecting _Mono Items_ +which contribute to code generation: functions, methods, closures, statics, drop +glue, constants, VTables and object shims. Functions need to be _monomorphized_ +-- they might have generic type parameters, in which case the compiler has to +instantiate the functions with the provided type arguments. + +See +[Monomorphization](https://rustc-dev-guide.rust-lang.org/backend/monomorph.html) +for more details. + +#### Metadata Encoding + +Rust libraries are compiled to archives which consists of object code and +_metadata_. Metadata is used by downstream crates to understand the interface of +upstream crates: including (but are not limited to) exported items, function +signatures, type definitions and MIR for generic functions[^proc-macro]. In this +sense, metadata can be compared to precompiled C headers. Metadata Encoding is +the area responsible for serializing this information into a common binary +format that can be understood by both upstream and downstream crates. + +Metadata is serialized via types which implement [`Encodable`], some of which +are derived while others are hand-written implementations. Symmetrically, +metadata can be read back by [`Decodable`] derives and manual deserialization +implementations. + +[^proc-macro]: proc macro metadata has a trimmed down version which _only_ + contains the exported macros without anything else defined inside the proc + macro. + +See [Libraries and +Metadata](https://rustc-dev-guide.rust-lang.org/backend/libs-and-metadata.html) +for more details. + +#### Mid-level Intermediate Representation (MIR) Building, Transformations and Analysis + +Mid-level Intermediate Representation (MIR) is an Intermediate Representation +that is lowered from Typed High-level Intermediate Representation (THIR). +Compared to its precursor THIR, MIR has three key properties that are distinct: + +1. _Simplified constructs_: MIR simplifies a lot of the surface language + syntactical constructs. For example, matches are lowered into a series of + [`SwitchInt`]s and branches. +2. _Explicit semantic constructs_: MIR makes various semantic aspects of Rust + that does not appear in the surface syntax explicit. This includes things + like drops, drop flags, unwinding, codegen intrinsics retags, and others. +3. _Dataflow-aware_: MIR is designed to be dataflow-aware, and removes lexical + information still present in THIR to enable dataflow-based analysis. + +A series of transformations are performed on MIR to prepare it for use by +codegen, Compile-Time Function Evaluation (CTFE), and other analyses. MIR has +three dialects which are distinguished by semantic changes. Within each dialect, +MIR has phases which represent additional constraints on the well-formedness of +MIR within a particular dialect. Dialects and phases are made explicit so that +different consumers of MIR can be provided with a flavor of MIR that has +desirable properties suitable for each of them. Some of the analyses include +borrow-checking, drop elaboration, coroutine transformations, const promotion, +further well-formedness checking and some late type-checking. + +```graphviz +digraph mir_transformations { + graph [pad="0.5", nodesep="0.5", ranksep="0.3"] + node [color=Black, shape=box, width=5, height=0.5] + edge [color=Blue] + + built -> analysis_initial + analysis_post_cleanup -> runtime_initial + + subgraph cluster_built { + label = "Built Dialect" + graph[style=bold, bgcolor="lightyellow", labeljust=l] + built [label="No Distinct Phases"] + } + + subgraph cluster_analysis { + label="Analysis Dialect" + graph[style=bold, bgcolor="lightblue", labeljust=l] + analysis_initial [label="Initial"] + analysis_post_cleanup [label="Post Cleanup"] + analysis_initial -> analysis_post_cleanup + } + + subgraph cluster_runtime { + label="Runtime Dialect" + graph[style=bold, bgcolor="darkseagreen1", labeljust=l] + runtime_initial [label="Initial"] + runtime_post_cleanup [label="Post Cleanup"] + runtime_optimized [label="Optimized"] + runtime_initial -> runtime_post_cleanup + runtime_post_cleanup -> runtime_optimized + } + + subgraph cluster_legend { + rankdir=LR + node [shape=plaintext, width=0, height=0.5] + label = "Legend"; + {rank=same; key, key2 } + key [label=< + +
Transformation 
>] + key2 [label=< + +
 
>] + key:i1:e -> key2:i1:w [color="blue"] + } + + labelloc=b + label="Mid-level Intermediate Representation (MIR) Dialects and Phases" +} +``` + +MIR optimizations generally are opportunistic: because we're before +monomorphization, there are e.g. constants related to generic parameters whose +value we cannot know. When an opportunity does arise, however, MIR optimizations +try to achieve one or both of the following objectives: + +1. to reduce the amount of work for the codegen backends, and +2. to produce simpler or more optimizable backend output. + +See [Mid-level Intermediate +Representation](https://rustc-dev-guide.rust-lang.org/mir/index.html) for more +details. + +#### Typed High-level Intermediate Representation (THIR) Building and Analysis + +Typed High-level Intermediate Representation (THIR) is a further desugared +version of High-level Intermediate Representation (HIR) with full type +information embedded. THIR is the last IR where lexical structure is meaningful +for analysis in the chain of lowering from HIR to THIR to MIR and beyond, where +lower-level IRs transition from being lexically-aware to being dataflow-aware. +For example, unsafeck is performed on THIR and not MIR because we care about the +lexical structure -- whether something exists inside an `unsafe` block +lexically. To further simplify tree-based reasoning, THIR has several +simplifications over HIR: + +- Explicit auto-deref/auto-ref and coercions. +- Method calls are desugared into regular function calls. +- Overloaded operators like `+` are lowered into function calls or builtin + operations. +- Match ergonomics are desugared. + +With the aforementioned properties, the construction of THIR synthesizes enough +information for MIR building, and makes lowering to MIR easier and less +error-prone than if HIR was attempted to be directly lowered to MIR. + +See [The Typed High-level Intermediate +Representation](https://rustc-dev-guide.rust-lang.org/thir.html) for more +details. -# References +#### HIR Body Type-checking + +> 🚧 **TODO** 🚧 (Remove the cat meme when complete with draft) + +![](https://hackmd.io/_uploads/ry2CM6gAa.jpg) + +High-level Intermediate Representation (HIR) is a higher-level IR than THIR. +When compared to MIR, HIR resembles the surface Rust syntax more closely. When +compared to AST, HIR has desugared constructs (such as desugaring `for` loops +into `loop`s) to make analysis easier. + +The goal of HIR body typechecking is to infer types and other information +necessary for THIR/MIR building. HIR body type-checking recursively walks and +checks each expression. This process produces information such as the type of +each expression. During the process, type inference, implicit cocercions, trait +bound checking and method resolution is performed. Notably, + +- Method resolution is not performed in (early/late) Name Resolution because + type information is required. +- Type inference is performed on HIR and not MIR because HIR maps closer to the + surface Rust syntax (and retains the tree-based structure), which enables more + descriptive errors and suggestions to be produced. +- MIR building requires method resolution information from HIR type-checking to + guide the lowering. + +When compared to MIR typeck where all types are specified, HIR typeck has to +infer types. HIR typeck also checks all closures together with their parent body +while MIR typeck/borrowck checks them separately. + +See [Type checking](https://rustc-dev-guide.rust-lang.org/type-checking.html) +for more details. + +#### HIR Well-formedness Checking + +A type is _well-formed_ (WF) when it satisfies a set of requirements which are +fundamental to the type's validity. The requirements are type-specific, for +example: + +- For a tuple to be WF, all elements except for the last needs to be `Sized`. +- For an algebraic data type (struct/enum/union) to be WF, its generics need to + satisfy the `where` clauses on the ADT. + +The notion of well-formedness can be inductively extended for entities that +contain types, such as trait predicates. A trait predicate `T0: Trait` +is well-formed if `T0` and `P1, ...` are well-formed in addition to `Trait`'s +`where` clauses being satisfied. + +HIR well-formedness checking is an early collection of checks on mostly surface +Rust syntax (such as parameters, local variables and return types) which are run +before further type-checking and inference, for two purposes: + +1. For better error-reporting: a program which is not WF is more likely to give + hard-to-understand or spurious errors. +2. To enable making simplifying assumptions in later HIR typeck: such as not + having to check if a tuple's fields are `Sized` when type checking a + `tuple.0` expression. + +Note that HIR WF checking are not the only place where WF checks take place: +there are further WF checks in THIR/MIR to complement HIR WF checks. + +#### The Trait System + +> 🚧 **TODO** 🚧 I don't know how to describe the Trait System at all here. + +#### HIR Type Lowering + +HIR Type Lowering converts the more surface-syntax-like HIR type system entities +(types, lifetimes/regions, constants in type positions) into +[`rustc_middle::ty`](https://rustc-dev-guide.rust-lang.org/ty.html) +representations to express the semantics of the type. + +See the [The `ty` module: representing +types](https://rustc-dev-guide.rust-lang.org/ty.html) for more information. + +#### HIR Building + +HIR building is the lowering from Abstract Syntax Tree (AST) into HIR. HIR is +further desugared from AST to simplify analysis. There are sanity checks on the +lowered HIR to catch obvious lowering mistakes. + +See [AST Lowering](https://rustc-dev-guide.rust-lang.org/ast-lowering.html) for +more details. + +### Non-Querified Areas + +We now flip our direction of traversal, and start from Source Code. + +#### Tokenization + +The compiler takes the input, a stream of Unicode characters, and transforms it +into a sequence of +[`Token`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/token/index.html)s +called a +[`TokenStream`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/tokenstream/struct.TokenStream.html). +This has multiple benefits: + +- Separation of concerns: the lexer can be concerned with lower-level details + such as interning identifiers, collecting numeric literals, identifying + keywords and operators, associating source locations with the token, and + generate useful error reports for these cases. This simplifies the job of the + parser as it can then work with tokens, which is a higher level construct than + Unicode characters. +- Simplifying the grammar: with a separate lexer, the parser can focus on + accepting a valid program according to a grammar defined in terms of _tokens_ + instead of individual Unicode characters. + +See [Lexing and Parsing](https://rustc-dev-guide.rust-lang.org/the-parser.html) +for more details. + +#### Parsing + +Given a token stream, the compiler builds a Abstract Syntax Tree (AST) that has +a tree structure to enable tree-based reasoning and effectively represent the +syntactical structure of the program. Rust has a macro system, which means that +macros will need to be expanded in order to construct the full AST. Initially, a +pre-expansion AST is constructed with placeholders for macros that are pending +expansion. + +See [Lexing and Parsing](https://rustc-dev-guide.rust-lang.org/the-parser.html) +for more details. + +#### Macro Expansion, Metadata Loading, Early Name Resolution and Late Name Resolution + +After the pre-expansion AST is constructed, the compiler tries to build the full +AST for a crate which has all macros expanded and all modules inlined. +Unresolved macros are iteratively expanded, which requires resolving imports and +macro names early (i.e. Early Name Resolution), but not other names yet. + +For import suggestions, the compiler may try to perform speculative crate +loading via reading crate metadata that does not produce diagnostics for the +speculatively loaded crate for import suggestion candidates. + +See [Macro +Expansion](https://rustc-dev-guide.rust-lang.org/macro-expansion.html) and [Name +Resolution](https://rustc-dev-guide.rust-lang.org/name-resolution.html) for more +details. + +#### Abstract Syntax Tree (AST) Validation + +Some basic sanity checks are performed on the AST, such as not having more than +`u16::MAX` parameters, to catch some obvious user errors as well as errors in +AST construction / macro expansion. + +See [AST Validation](https://rustc-dev-guide.rust-lang.org/ast-validation.html) +for more details. + +## Additional References and Resources + +> **UNDER CONSTRUCTION** This section lacks additional references + +### The Query System + +- Detailed description of the query system: + . +- Design document of On-Demand Compilation and Incremental Compilation: + . + +### Areas + +> **UNDER CONSTRUCTION** This should retain _key entry points_ from the previous +> overview version. Can be very useful. We should expand it a bit. This section +> lacks additional references. - Command line parsing + - Guide: [The Rustc Driver and Interface](rustc-driver.md) - - Driver definition: [`rustc_driver`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/) - - Main entry point: [`rustc_session::config::build_session_options`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/config/fn.build_session_options.html) + - Driver definition: + [`rustc_driver`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/) + - Main entry point: + [`rustc_session::config::build_session_options`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/config/fn.build_session_options.html) + - Lexical Analysis: Lex the user program to a stream of tokens + - Guide: [Lexing and Parsing](the-parser.md) - - Lexer definition: [`rustc_lexer`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lexer/index.html) - - Main entry point: [`rustc_lexer::cursor::Cursor::advance_token`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lexer/cursor/struct.Cursor.html#method.advance_token) + - Lexer definition: + [`rustc_lexer`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lexer/index.html) + - Main entry point: + [`rustc_lexer::cursor::Cursor::advance_token`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lexer/cursor/struct.Cursor.html#method.advance_token) + - Parsing: Parse the stream of tokens to an Abstract Syntax Tree (AST) + - Guide: [Lexing and Parsing](the-parser.md) - Guide: [Macro Expansion](macro-expansion.md) - Guide: [Name Resolution](name-resolution.md) - - Parser definition: [`rustc_parse`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/index.html) + - Parser definition: + [`rustc_parse`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/index.html) - Main entry points: - - [Entry point for first file in crate](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/passes/fn.parse.html) - - [Entry point for outline module parsing](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_expand/module/fn.parse_external_mod.html) + + - [Entry point for first file in + crate](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/passes/fn.parse.html) + - [Entry point for outline module + parsing](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_expand/module/fn.parse_external_mod.html) - [Entry point for macro fragments][parse_nonterminal] - - `AST` definition: [`rustc_ast`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/ast/index.html) + + - `AST` definition: + [`rustc_ast`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/ast/index.html) - Feature gating: **TODO** - Early linting: **TODO** + - The High Level Intermediate Representation (HIR) + - Guide: [The HIR](hir.md) - Guide: [Identifiers in the HIR](hir.md#identifiers-in-the-hir) - Guide: [The `HIR` Map](hir.md#the-hir-map) - Guide: [Lowering `AST` to `HIR`](ast-lowering.md) - - How to view `HIR` representation for your code `cargo rustc -- -Z unpretty=hir-tree` - - Rustc `HIR` definition: [`rustc_hir`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/index.html) + - How to view `HIR` representation for your code `cargo rustc -- -Z + unpretty=hir-tree` + - Rustc `HIR` definition: + [`rustc_hir`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/index.html) - Main entry point: **TODO** - Late linting: **TODO** + - Type Inference + - Guide: [Type Inference](type-inference.md) - Guide: [The ty Module: Representing Types](ty.md) (semantics) - - Main entry point (type inference): [`InferCtxtBuilder::enter`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/infer/struct.InferCtxtBuilder.html#method.enter) - - Main entry point (type checking bodies): [the `typeck` query](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyCtxt.html#method.typeck) + - Main entry point (type inference): + [`InferCtxtBuilder::enter`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/infer/struct.InferCtxtBuilder.html#method.enter) + - Main entry point (type checking bodies): [the `typeck` + query](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyCtxt.html#method.typeck) + - These two functions can't be decoupled. + - The Mid Level Intermediate Representation (MIR) + - Guide: [The `MIR` (Mid level IR)](mir/index.md) - - Definition: [`rustc_middle/src/mir`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/index.html) - - Definition of sources that manipulates the MIR: [`rustc_mir_build`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_build/index.html), [`rustc_mir_dataflow`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_dataflow/index.html), [`rustc_mir_transform`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/index.html) + - Definition: + [`rustc_middle/src/mir`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/index.html) + - Definition of sources that manipulates the MIR: + [`rustc_mir_build`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_build/index.html), + [`rustc_mir_dataflow`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_dataflow/index.html), + [`rustc_mir_transform`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/index.html) + - The Borrow Checker + - Guide: [MIR Borrow Check](borrow_check.md) - - Definition: [`rustc_borrowck`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_borrowck/index.html) - - Main entry point: [`mir_borrowck` query](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_borrowck/fn.mir_borrowck.html) + - Definition: + [`rustc_borrowck`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_borrowck/index.html) + - Main entry point: [`mir_borrowck` + query](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_borrowck/fn.mir_borrowck.html) + - `MIR` Optimizations + - Guide: [MIR Optimizations](mir/optimizations.md) - - Definition: [`rustc_mir_transform`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/index.html) - - Main entry point: [`optimized_mir` query](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/fn.optimized_mir.html) + - Definition: + [`rustc_mir_transform`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/index.html) + - Main entry point: [`optimized_mir` + query](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/fn.optimized_mir.html) + - Code Generation + - Guide: [Code Generation](backend/codegen.md) - Generating Machine Code from `LLVM-IR` with LLVM - **TODO: reference?** - - Main entry point: [`rustc_codegen_ssa::base::codegen_crate`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/base/fn.codegen_crate.html) + - Main entry point: + [`rustc_codegen_ssa::base::codegen_crate`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/base/fn.codegen_crate.html) + - This monomorphizes and produces `LLVM-IR` for one codegen unit. It then starts a background thread to run LLVM, which must be joined later. - - Monomorphization happens lazily via [`FunctionCx::monomorphize`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/mir/struct.FunctionCx.html#method.monomorphize) and [`rustc_codegen_ssa::base::codegen_instance `](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/base/fn.codegen_instance.html) + - Monomorphization happens lazily via + [`FunctionCx::monomorphize`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/mir/struct.FunctionCx.html#method.monomorphize) + and + [`rustc_codegen_ssa::base::codegen_instance`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/base/fn.codegen_instance.html) + +[`decodable`]: + https://doc.rust-lang.org/nightly/nightly-rustc/rustc_serialize/trait.Decodable.html +[`encodable`]: + https://doc.rust-lang.org/nightly/nightly-rustc/rustc_serialize/trait.Encodable.html +[`switchint`]: + https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/enum.TerminatorKind.html#variant.SwitchInt From 73a402b8bb708c41f94188e135928d321eeb8ebd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=AE=B8=E6=9D=B0=E5=8F=8B=20Jieyou=20Xu=20=28Joe=29?= Date: Mon, 8 Apr 2024 14:46:01 +0100 Subject: [PATCH 3/6] overview(R1): flip traversal order, add SVGs, tidy up remarks - Change querified area summary order to correspond to "normal" code->codegen direction. - Add SVGs generated based on the graphviz sources. - Remove some editorial remarks. --- src/overview/img/cat-meme.jpg | Bin 0 -> 50358 bytes src/overview/img/high-level-overview.svg | 355 ++++++++++++++++++ src/overview/img/mir-dialects-phases.svg | 110 ++++++ src/overview/overview.md | 449 +++++++++++------------ 4 files changed, 674 insertions(+), 240 deletions(-) create mode 100644 src/overview/img/cat-meme.jpg create mode 100644 src/overview/img/high-level-overview.svg create mode 100644 src/overview/img/mir-dialects-phases.svg diff --git a/src/overview/img/cat-meme.jpg b/src/overview/img/cat-meme.jpg new file mode 100644 index 0000000000000000000000000000000000000000..feb7093e0edc056ce763be91bed141552e99605a GIT binary patch literal 50358 zcmce;1yoznwk{mp-MzTGTYyr$G!%CzE(MB12?Qxnyg(_%ix+n&?$AOh?wSBaiX;^p z3WS#)yXT$PanC*f_}^O$b~1L>o_pGwd#-QIwQpB$cL3zNnmU>Q3=9AO1N{fMT?eQG zurPnO-$yKT!^Xw_-SBa7ac~Ln2?+`C2?z*@$%qMwNQnptNGM21$;inm$O(xlsVK>* z(BH{_6T$d>B^EY5`a*Id0wVO;|FGQ-04VS=zG3{p!k_?PQea?FVBC%X*wB39VEm;4 z{?;%sv9NJ)@$d-dt+i_;ox9nqkD&=e+OVw;83!QtKm{Te1ym0ODz$V zUX0Iqw`q{Za2C!b>EIVlKuAkR&%nsd!^_7nASEp$D<`j@eosSFOIt_R$k@cx%-q7# z(aG7x)y>_*KOitDI3)CG%(K|I_~!|U8JRD$US+?|$t@`@E3c@0TUFiM(%RPE@vgIL zXn16FZ2bL)iMjcO#iiwy)io$=cW?jm!Qs&{;_J8XKQ4YEFMs`(3j=`lSFzB?zY6v* za-o%gfr*V)Dc*0nFffDB|5y~*IPBuMlxh$09{EynNJQaN-%T%W8YJM9G=$SQ_{|d1 za!EnC5x+(Ii)8;Z!J_{^N%jxH{!6Yk05KK@+IUzL02RPh9*Uvn!v7Xf3PF0_0-hDb z-vSux&$P+e;8S)jMK?^hfML69t`imHqHZMKwWQg}!7V`Z764zq1rR8bp`^{;cSS;m zr6WGs+yY#00dd<%ofQb8TK*2kEr59ON6V z`32w~owrepw}5{zjg}kqce&U9Cbt$B;4kcn{*pys)&DoC|9b9kEdNz)%t>$mEVTAN zUH=cQ8T?T{Sbs25X$IggBL9m$w79TxhtLW`TjXE0Ec)cH^7a3VEnAt(F0;L0;tSO2)9*3HCk^=EVZH~RcP{0Q_4@PE3Th&JF4`ndeNZ~gE5 z8WaP1WB$l5Mp*nGJooPwRQca5_-ERNdw+C(P{tpa{)Zp^tDgVjanq<2v}gUpL;qR6 z{(p>zKiRu{67UBC=KoCK9|LOOPXtQ;q~U)siyk5W?DYG8lvhjWuMYk{QJK-7N$CBN zi^e~@%AZO6*>LuMjtqa)+8^D@??2GmpZTr&`bQGwAAVb|A02E`uKsTMB9246(s_*f zkGP!rQ!B1@OgJ+axYDd{7-{w%^^rE6Oi}csf^WzvI_N(qHJPi5Z{$9*FM&SNlB%br z%75sKFIo6Rjd~zR>%I{NK3*j?zyR}1ZuAaS+I?73WU03TqnSMqnKjCI##+34Elx4= zNEaH!(xfqT8Y?4K1$ZMweI`hd=6}}% zXihLxasK;{I~-lT9ZgA7o#_smios1s4Jjg9#6GlPU-1eQf3a!1x+);Ozad6I&ynLq$dINgxo~A1B@NK>_4jcn+OPpJi)%`J z)gCm_s^X1OB~5gzOmT@e&X8p=)5NAY(EyBXSX-^#{V8iSPW&*rCqvBS;jzw+K>}-P zM#%@Jn$pOL2|s*gd};gGHziC~lZuBQm&^<{H0i6{^5w7t8CZ^N4+*MO`2ZD>0?FGW z)H&LhkzhAuCi+pf7D0@D7Tr^UlA$K9v@U{Ic5VR{7oxJkc`Z{{*Sisljxu5f zMKYThw!aD&14G>%>59SvNqSUcw*{YB7sl|ktvEgZ!V#}YTq}VukNtE8a|WC4X>4qK z_QjVkVG!wdtHEH>0bQGajIAKIvKG`QG&NCm25r(#_?~0GdhV!#J5pv{?~&`+;i*LzR5ZgO)M6 zWyN-Vqgvcl?0r3TD!!Z&D+%2@su^r?TZ?I_cDRi?S7W|z!X2Ub*~mS#Ggh3`=S3bnF1n>dgU`7)DCm%E)Hz9YM5Hdv~Y2eiNyDI!+Wc8ken4%PztdfM~F`QjuV8C9C zB`w13**W)doX52e!tWZ042Rh`g{LWpy=|m+;|=_*JrN8=k_sb#(2nOIY z)E>@Vq-;Op_Fsr#a9`^<$-J^V>c?trptiL`(v4j>z}A+28BAfldwCB@|ByEiOVdJ? zxbFRXrhw=GkFUI?Bn4@_D&!IL5%Unb9vzs^njUPa7&=XGWb_RFInDjEM32S_Nx5UX z(O$~^lvc?cTzstL&QeqTsYBtP3ZNJWMGpg9^5Ql8JURj&{GbovGhD=|kCU=lF!#P< z?kxCgdY{_@o!Qs*r*9_2jphT5xvCa)Nsm$#mGL&OIlGX%SH55!WVlK~n=q%^>%2{$ z6N!_I<2CL`A*JX_2_@Ih*u<{bQChsM)w@sHRv{)xONe9tS_{-W4?aF>`SF)*iuY;2 z)uA-OVxjS?Bl|3;ud@^j1Sa!>S-l#mS_$EXFugQ~lf-hK}5-r(LV0n}6% zX!I74>>qM43_W(u6i3n5qj@@+&m`ee+SKI<1>TyeDt$?BQ=+f*fPqP`gIK^Qp+HH`v#e>en;g+=H8{~l z8G`quDI8{1XEaPFGaXu7H}71MIbjvMT8R5dBA!spQf!4@x?FJn?a_C}*_Er11LnZ` z=Clbi+-W!jMmJ(dKY8Vf93Sn{O5D1vgSowUF8o>&FZoo*LPmzh%q_(@P`T&u>jY@6 z_x=s2JOT^#Nirl4T9g_=>rq7CdJCWh^DUn}@?s1pGNH0FZw4qs#4vmvTi+txn6! zKln*gwg`Jx&PZwil#{~vn5+K7pJrPgss8ENX}g{66E~FLu6ge_VI<; z{hx5f35OKAM+V$qOUanBo*e4!u?{B=fnT`KJ9P`Ex!v?g6?l%Qv@Q=#lOV$^i*y#G z^Z2CRix#_(d3%epQtnjYMIOj;CV#VpQ3Z0O8*c1E+^1KMr!Q3O@W5I~<=qBKwHj*= z%JnJVP+tn?7n%&Zk5e>XRsq(9i`@K#gV%N4@WWtaa|q179J#4X=Nz=Tws1&AN~REIbxZegrW!$ z998(Z6;xak5;64k>^{b4eJ=b@E6l`Ayeus?Pl6L4w+2b8{!cQPe@=2Ro6=!*ra#qZ zKQ9OgZJj+D8Yr+{GI7{2H~+To#ReNsdvvAs+&_&uO_euNTPgZ1{mX zV`L(A!0&DoUTO%eSAINK7z@aMliTm1%y!`l&pIF2PK#h!4p7z`Ue2bpPzusi<1!R~ zQOtm+xSC__%wX*&o;j&oUDnBSH)u8&(h^(w{1)H_SzETadFuo}y~u>xh|qP+Ssuw; ze)8&@c#aR9e&v)7Hy0FR*fT1Bnx$N+R%bIUc9Q{dZy>tHL_ksl`dL?wvF?MKm#pd_DYs(nhvDWlq`8JoZ_8K$dU| zpefqRF#*L z>XE4J3(K2M@T1-7=TCXcw%8Efg){56mc#u&{cZ~Nj|ng?K4549_WYiN;4=4SneI2* ze%y=Txqi}y{BdP|&4#dxmm;woAG!c?%mr-99HX$<)?KWSg~8U8rL0csZd_5V?Xoyj z0)=yBmMi+3g{><4yz!`kqN|iT$mcr{x6l2qqL=cZHOHd{$Pu_r>K2fo@>+Ox3^lUd zRumn98zO1}cO9`JdBCD@ZW#Vx*r2stvgZDy6z-@vO;XP1^>UYaL2^8NrpAk9eBG?s zS5g+9{jFrDW-yhtjNReoT(dYKdruqcO&&%wF(PNeCu$t*oPBe5TcgzOEWKy+X2 zNY`1rW5>;bFWxE$kNaFy4`~M;d=d-ygc4Gy#hNn&IS$tmmr23dQzgcseUtYYEvrvF1 zOCf*G>^?|S4d#O$%7lFaAzz03$@-l|BY_MH_4O6PRd$|0Ry%eMIfgZQ3C&KIV6R>P z!!-Ydq=yuYQ8}@{l?zA-KR?YCg}B`?8TTP0q^?3*%i1llF=^UO465t8CoOvB-X}Bp zPT$$d5~{ws!rC^PhIoLO!K{e(%#zh>ETqLv0#u)Lzoc(DTZa~Qc5HI9VTE`Xnf`uT z(c1wuA+tAXp{ciFNzgX)i|Hb5!Am-AU2uoC?vcclXBbWF2qpVOk5ACYTCyiG*T`TBajuo{f0>95jDHI_TLaP|2?{C`it|ji~(YsVA_0+31B2w7~ z>%e*s>J6Wd35jRnX3mbz6>H;;l@^1ZUWBKq^qlz5l`&HRzsw$tQg}So%&c2y5_Z*V z?eFkz+*EBYz6C@!a%Ae9VIFmvW|vylrKVM^t*nb~#;wsL;LRFi+|_xEwcFSfw}0-? z93{dUeD2LSl1&Fgq7f=|<_u3(D~5@l%M;6*Zgtn9{jW z=<6}@?gm}JB!V^pdkwdPHK$@g)Th>)16OX*)-2#LX4qcg_uSd2Z__90a6LP?%3zAs z5QH9#=YzAc#q)0APRoKr^d5cg(ju)|^aRjtx+_BU|}@AaIs#Pn;~C` zK>{P6i3tk;D^l={;~|!;Iea?qS{;ob`ye6u3)l6ISI%YrkAL~#QRjl5h+0`$Sq!{d z3PPw6I}$Lv(HK7k$Waee|00d&DeD@^l}@sIv(};S9cQnMwHy3Jck&5uYhzQRsU8!b za8|0h2E8h%YE+CR(A_f}%W`X7!zFDz5~fFJ7xTbwY@` z!zzG6bQUmh{k9oXz5J*g`r>G5{WQ|t>Vx$do@ymC#_59rg|nft8xzsmH=QQ(4}~5L z086FNYXDZB?^Aj=dyGa_CbXko?yk&Wl_c_Un%gIErT|Rt8DOTV;^_hc|9e#DpL3%B z>SRPd~e+v=)nb^OFmj3BFLTa@0il_GSAL=u6a#(bh+#Hd9B|G6tWY?qk(s=q9RXryQ@JA%GIxXm0j?n}117nE-7Vr+0J_F;mS zP4wMI%`(?Oime0B`+q?juoB^TW01Ih>Oh;|dvMX`pDIJ4Rio`yY%BHbp(eoBN(gQsld=sf88PnGs^lNfdHq|ee*+!jJ+8Z=B-cRrSn;kX-Lakh?Duyg z9l^l+8J8aBe2Sc=j*}Pz%I>QZ_GWXvicZ*^%2J3i653B0@xdTVI!&4l8d^42p3I6bBS`E8dx+| zKcJ@c9pH(ZGqZQPRzjxjOebzJ#E$_nmLP3XVF_GuibXAxxHe3lBpKC>gFmQCxupY` z3WN>*4G{QG*7`R+iEWXa(vY$pDp~{ZN-PoMiJZs0==Afr_+`@ zvMC0Ad}`M8gqp>SQ)s>JwTLSL09={Y=HdG{!Q9?clMUTrU6V!x47MC(==MH)Nn%w?GvEx2!d-6ltEu8noT>OjLqfIhr0MdYWg zu7ZJ8>r#bQUcwm()P^j{g+uzcty4t;kF<6P|LI`0N4<>^(tYM873N5~w zmnx7nvpB1-d@R8CuIpNdE0P-1`~`q3%6!H{L_bj(1{X=trrn7hFqE5q zx?e8$R$jyW<#+y7^z>a#$qRPFp$vj%pG?A3$hn*O7b~JeE2BTDzk5AA>g^{32yXw# zd|d|6`4KM~$Nn))bl?`SRx_~80A%S!-Qw7qd>PWBimwlTm5pn^ETc}E~n>=PI zPS9iuVOT0Kk^2^eR#G^`hbIh9|c zEo`a7l3cY5a(3l zI|RKl%0^nN0xR!XaD-QstWs=R=`?Wq0jZzXboZ463aQF2AR{ zZmV4;H5)U$hoXL%8OVA3tgy1dtj8_F6U-d04`hj0PAN;C-hbos3+B9Vum6%P{K+sh zhh@65f2Rm>_~A+{#J9ESu?Sc90@K5Kiv8ao*R}Fo1Xy`N{6p>^Ke^y~bH>G*V!}K`aaE)nAj;} z=+q~%;-(LS2YW9&a}V{?=Ezn#VZqTTo@=U^GbOh2Rks7p*nmxSoi--JiG6DCH8O5C zphFW^!8li=$5|;ipPOZ{R>Sr!U_52|#usvfy;SRZz;=Q@!J~|rM0JC10cEphB%)C5 z*rp$NClrpZo>xLhP1w>VN7!m0!+`)mLR+*l%~$!;%7Xt2##)yc+K?Jrj)N*ro@BV_ zxd4f5X~?os`|P!Jpg&3M=|V=C__`WbSF#21w!rQaEG1VgymChk(QxH{=m#6!K5V4# zmCZFbyj7v$WD~)rfsBQtU>2WSI$}#QJ$8oAfd>E=0b(#A_1k-=jS7WkM(8(1^&Y(XbuHvhmXSkDQ)|u&Gc>Wj(X*B%D&0EksGiIPr?B z&`77j1M$SUEENTAi50nK`KZE{I; zBg@s4zXJeFx*W~!fu}Z81nE><8&-#Y?qnw_g*R-6l&qU4jb#rZ*!9#YIxuzeYbZxl zD5LU83%?)DU3m5FWF`B=+BLtbf}8CIwIQ&e=t7&FHh4szwQY!po{XF(&Py(I_z=0P z%To4Cs9@4~D2?l~~&E#wP8B7 zs^5J!(j2;M_)+Xxh8Xv_?P{I-aE1Vo!G&x$$pNDHsA-e{Qu$3tR-PFmdSvZYr@v1( z`1$b!_M>+i7>%;7A|r(!i#YUh^`-lBV})5)T*#*f7tZq#S05%%wl&WCVM$5hmP=&( zJMY4BDs&t*g`-Oxo>6_n98QKW(wtnsc5kO&ZJ!8(FKu@ zptk^7Msp2NsntH-CfTwRgl^Yx)3Y0-*ubSBdLC6V_NAv z)QfI)lV$%K#V)axXDLR^d$~Pw?K(~!K0onwJyz}hCeiUzwtJb-={Obl^+^a8s86Oj z#6^da_S0c>O?q3D;!B094-?-kt_aE}%HMQad=DOgM4_mWSUYk(RM1eKPEr2u{=T9F zQ4tFh%exA9hTfVm1Mm#>SdQk67t?jjzgsr`N9(kIj1B0M(VFkaF)U&aR7jVl~Hrd2zZv!d%00PH*6P!PF`%84T`M{d*T0@d;ec$MvX@$u@0=^Um*t{ znH>lByvb@G3pv!kS25R(6+Mp<^mxkLbW}tQmJY7i;B-)258Nd3zk!a1wh4A`km<}x ze_`>PKmDb@AuD$OY1{{N#lxrSLY}XBQy6}|648Qe<;QTL=5F zwXW51B{WBrL;Y5;m%PO9%g>1er2uIW4`JQ~5v`s6Bs;P`_Ae+N_;}2<+D&m4QUPx6 zX%L6_^uK(z6tI+71dWyBJd3Dw7Yh>+8^!Ftbcn01Kk;^hARa%}gv&v7qmW@9tzXfO*-2(WYX5Ruh7j7Jio_yA-N3xA? zksveQXu#4ik%`k5bDtfOd>^k8?p90WONhOnXv9k&mo7u&0P&r!qd;N!bhMOS8U?c3 zrg=_k(m-iFuk)T8!C|Sgc_C(UMhGC+`!~cO?U>G;;+(v1jcasFB1Zf7XTLlfBiIrd z4*zC{#?q7?!N^W-Kx49T!x}LsnUfb)KS%OpHIu8pfygJb*krA-5?=1oW**ZuEt_CO z?M}0zS4XpBMSFa9!_BT_@6Cf7+H688_4h9`gmk{%t341omcwKCu*;Jmjq`EXQGNK= zMJB8cOCJG@3BIV4G;fJRO+bV*r=pF?m`?2({Ax+*F(u#QX1Le95uN`XQsmKvHOQ+W zJ7TbK=&l{JN2UI3EwKY^&uUU;>g;Vlm+mLOkEM~m`Go?`+%!Qwey5|WC5;FMMPUKHirFFIqg#TrTVF$~~Tm*gHvbEO2Cg;=}Ga z8USGGNMRH}eQ1#WV{6Q;-0)W|Ue!ltAOW?|$5*hI=Cl-`Fc^poZ9uvXvx*_`E+Q&-nWh`v8pAU}BNl7ExBWmkI9Z&D6psb1Oj zO)iyx5_bm{``e8c3d|^xL3_1ExA^<7Xfw-Imt})ljXvy;DHOaVlAXbHZ!f7I*q1I! z+a^#_-sva1R$o%G6uwr0<-pqKe1OA#+in>eE*dLM+4rA0W}9F!!^#&Db@dO2_Sq7O zTE_=PW4f+^^vJYbqcRVpwYt40=xk}r8aFoQrOcs2;Bm5eK4Lyy*W?kNySPkx60~7m z^1>An)aC`fp@J2Z+HT3E(sVU-w`w{(q5D|KrK%$b=#a{K>a{BNS*vxaln@}0Ah3PR z7+C8q%|FMN6-*nn7L&U7v;MKxpuJLu0kWwQ*$1;D3XvR^K<1~Vf6gI(G8V2*uI|ti zjJp*Hf{#O86O{yOH@|dMG$JfFWcKDU_c?fHzDpZJxeaA)%s%6pA?!xFvSa#a(S;7b zRI)E_$W#}k1?{9|c?(Fo-{-|MFuinoYStk;NjrQ067L>z|H><*duQ@GYz_j&ZH1pD zVgIDE)bT(^odsxAlT>#oh8pD)R+$l3z#i4dY7^fBE2?160-uBk`KetHWyDkjU(8VM zZ*;}SpS@FdiO5$uIa-?%)I6~*Wd}SF+lw`PYNC+;iF7^oLTMd3J!+%1Q{QrB4c3^G z3i%;;Dm(h>$P2r>r2UD8RD-H?Aj1{3=@ z?y0QCTnxd-ho++n8R4v@@bU4rwy~Uxsh_#FdCcu|m)V)RGV(8|qV5=t8)*0&))r&e zzBkliVLPeW{i2ev-Of7-VsZZ^Q&nztoJ&)~U09Bv_*po5NwQb%j#Dvb<{*u+^R(%G zPt)IEf!(F%_$cIx>9qg5ccz6FlJdtbfL-+2cQOprBBVJ!7DXN6Gu$VE1ckn}TXTE0 z6#Q|Et~EFKEZ)f!E3OQHXFG$8KQeSMphT?a6x47 zgSOmbeGWY>o%6a!4&0qP*Y5}qFg2hAgnp8Qf!3kl8|!~6OtYcZ=zdkkM=&34;RZ8`~DOYdb!8RjqvFeh*ns7+rttMCiaR-2q0|}o z!R?d?4!BmLBjUc$noBp-Go9K8z6R_Hq%d;eV4f8GUd+z5bCI&PNT>kj*$V>x{Pi z&+E_1>KZNydh5f<;DWn&=#sBBys_*p`8gqBC3$$pC$skX*u{#gn@95k=Hibvi#r`K zu$XW^lTP;XPn0#xxOY^|N2~yOvIlPgEtN@NE!?!S;|zFI5*_3bYy9`|Xil zZZNg|7Z|3;)iS%E4+5P!9hro2{MR9_=tbRt<%8uOc|_%K*W-9yahV*L7c*p}-z*{O zL-KbAImMTJd(m$i6b)Z)E{ruSR9@+Woe=$lHet|Dy%lZINEOp%GaUq{wR$H^hmbnp z@pV7P24(oeaCeiu7|jOyMf1SPYz{T!TrwndH{hB1L~K|5;hm6j=lT)rW%(&)|0g2yLL zqDa--8O96%s^A}wXm}fK>Ol9AU#{*Who)h;@o=A=&F#2=DOclpDzm<2CA}x?EsaqN zt?tuI?*WBO=X``ZTsFE5IhuF29aW&Br?LpbZ5U|{+z7T*17-2CLXGAb&q|+@S`&Er zu*z9#B@7H~U}{Gkvu)U!CEo(@t`!lCR}T`$z8S}9 zbVXC%_mnd1d0@o#qO91SfD03Ym!Uq<{~$44XOkISpTVf)5A|6)W{W8l$rwTEjVj3Z z!1t=Wnw>jMa7r`oLpu|992qWQ*Nz3%`3)|DUmVjAWT&1mVJevDXq~B`r(Qn*EHV#m zbt_GxqwD(EEc9^1nRg!~J7uUUM{$5xu2;KI_KV&6;5T(iPH# zg-8pgkqi?j1mYyeEB>_4VrL+|pK2!We5oyQV4_v9HW=Kw)ql!aj|S11QRE?>Ltfs6 zl*kz9QDENlgAUw%tBIV&;FwqeM+4RAJBwGQ2h{D3eHFip>yXRpH%-?>aNr2KK4(Z8 z#zr>vb_=g#YCOLRJp4Fk$7KyDesgZiT(M|E8WsLHpuf$@Rygk>3^9X_ZAI8$N^F&n zdQAl`F!5yh^3+Buga;+ZPMo5qOgz6TVyz&5?*keItx@f`o=omEB+&k3W$H!xhRx&AGg@A=F$~^5~KD%k-qSWp{MWh{k5=yfe zJ65w>GuqwxE`v?keohtpBOPaSg%-&X(bJ_L0#XZ(3l&$apdC=scDw7?G!=4Q8|nWR zDR_VGn!Rqrl4(VF5lgiu^c4eUOY-ql8*6m8%Z6QtNO9>k)-u=~ zHceoqw!2OCr5~PT?Jn@~)l`JK#QSmX46&vOZQ;p##$p@z5nD4}XUuEN=umj7jJO5t zd^_BdK~}=1<06FNTUDVXeWhhcKLpo;)JVXF#oZSK*0M$%8RDJ6n7nJBX#HB$g3>zd z3z^<>c6OvYB^pz5RzY7TN2?Hi;k%^$d!XIoSwbUKNcHdNIP3W^jL53MS}N0%G=|p` zClHWQi%X8du|F+6HEmex&BWooHU0uM!$u7hK>pfA+sC^SzI1R8aaIJ=Ll)18)^T@4 zf4$&uU5+iKB;V3&xx*Wbt#EefZ(*EYKC!lpqSrqOvyDeUE?yzc5FLZtWI&)ERNqwx zah);f=wG7we#u`1aKE|uj-)2Nm=aK(rOdQCkX@SL2g};i99y27@(58h3|;^$!UHoP zT!+tb-3p1juZVwTCweb(FL={Tyyq}v+M581^#Zt~>}eF5U*^W>ZVuff^-2@aoMAQM|lM`6v_$;X&vp;jYh*~}c zkgXAEAgR!4SJc9T0$>eHILxNCZAR)@O2_7g_q(eV1{1@hA{cjcROXmRNu_)+(Q3z(GtsW8t*Ji( zc#Z69=_;!?SC#-T;jHPkZmhWQvsjq0s@-vycc#00co2b#+q+a63$BB!j|A7A z&HQDVLYoyBraE~r52Z$wu&p(xop)%{nJK2jHTS5g3>jON{f|stAS^s z239iZAImC@SfI&(JJ|+rXx8vHD;f25WbmPVifcBpep!1@-QYgByY-gTtfhh=C&D-2|=w6dbM<~ zQ{<;?EZqcWkh#PQ@yztpwq%Z**t!ip$0;c`ypSP5l~o>jCEnVqSs(9hL);;Q$5CC$ zF|w0ajjFt#M_o#8rU*_{2G@S4CS=EKZ4YXoWbqUp9l6;FrG@jLWvLwQj>X5Q^|v|T zXWZByDHg|wTq7}rS~c|jTl?$OJ3r^fKa+wmhhz_VT}fV3ptn$vJ#X)NCUHFfv4Ir5 zKPQt@@cr2YR(i@HoxNb=9tLx@ewfrenfm!7M2y)jAQruIkucy|Ziys*1-OjfR>?>ki|$91nYIrH@rd3e)Fo|adS=!D)yV~q{oyfqe!2LF;bJ( z=ixi?Qy~N^H>{#I`suFKgNu*J-OakBUj{ADSt+c491>JD;o|fpH;DpV0JFqE>pJm9 z1AVL^bmO$!aFA%i7X3T8OE+ypD6BiQ?)%UA3agw_$|I+)duINk@2{iMvU*7z=_gmD zz5Dk->c?o=t~ub-BMqy;L;a*Zp=cys$U4Mfh(T#RJXRq6D_LSLuy%Lot2`Xl#$6jX_j!imD(iJh8Ng&0`@mBI z(MXs``mk3%fO1~b3$@KkgAh#uVzvTlXU?U=3REnc`(LfiaSBz?Y}F3ZaqV;+0Ct?d zAv4qkSBgT9H2#13P*n)%j9wD*@!R&V!0Q zt>>c}c3VaVHW;mmL0etu38A9n6(41_C(b^E*C%&kpRqM9g1YLHoXOYA>=Rfpg3qk2<4-vv#uy6zG!FAFMI=j}+lvhafxr;eAYbQ6KXcm{EE7R7V*%r7`zsp6{!T|PEPZ{K|o6z6C;|KR22 zQ?YgRxqh!+-oGp-u`wJm(q@Ie-3Hwh>|0r?&g=1P-d)Y};Nya-@nXHfZV&94h_K0Obk z4l>-e3S~{1zA1>V_zc=|&PMQrtdI0jqG6+?9(j0?L95A})Hx+Mb1KM^gPUOHlt^rY z;L?UVo0EMe$?cmL-$rrS4cQ4gAz?}x z_QYPvtauMJ2o$_+y!8v}gTI2g5nAyoJB7JRMKUqf8_0&yjwa8J3x_Qok>qCE;nq-l zI&5`Dacd{a)dT5DPGj)OY4M?58(BP9y#_VX1&aS(fc3CvVQyT_w7H`#lotovYA{9Z zaXo3sE}nFt!=@nj3hVf5bOM6|odXIXU3c+Pfs~%MKsZko^h%J#Wn9lQwrBp#A<96T zmQHiP1k`gk!_4WV)<|QoK9~9sIpwGsi9LMZe#B$j#Qd|7ciEhMis_lYTOi3UR7K? zJ+8|dtr=IOvyj1H0*uSk@8&PgB^kHbjI}GKtw1yvTSZqZhq_F=%QufY8kK+Mc?Dys z3%GoBkmUqus$n|?a8yTo%)sT<>z@SWaK zx&|>A=hG0DCv4pPTA-uLoG7x}yBLT30zF9XcR8oH#zQ9dQ7-g6EDxbl&(vAY)JmS> zlGNss=t>UXT&ASq1zd)3`{!~K82V;4*t^$AfXG7f#vt?%Z=d*WnzW%JG(tN}yQcrS zz}3ITTfs^r*~8>zBeMC#T)c3^VLZyWO46=KLs!bU*pT$`M|}8oezFNm!~N1lTVAqiz4pPk z#{9MYtIwa0Kg00idHqB6_i5iVrzgkc9+cB5c#}|OEv8zb2(F+-R3QgrPm4zFm_KmO zz%?^{cBUxGFf#5WeS1D#tqGX+mH+W}xRUqdFEY1pQu!kT{FnDbv8OcQXh-^|Pegun zwuzE@SaN3qlwKp-$rvH)PaRc+$yANVvvx1xAJtpN5vk_>FeJA!d18k>&3DPDGqcM}qU9H=`VStEqF-Y1-tx$QRmHsk%XSgs zW*2Fhnq6YIW$C`QIFg-Bdoj%w^xk%xgp-dQ5APLcah*WL0c~Pf=|P=8ddF`RknGwL zF=EH2f_{+&4RUw**V3C`Y4OqxWWDo`b(~$kI#EnfdS4DGrtW+ga1NACihfq4?DP(0} zs)ntLynKp+IIYUGw}6XMBou+AHUnfv*Ia4Arpd1Fy4MviHMFI$m_2ARvDO{vJI{Ll z$;LSLlZ3C?sVi40&D*opk#*E071$M-g}71DDzmfrlD?%b8v7&ft#dTqJ7GaZQ4AL5 zvBVMFH73q{<13L+-CMw&wzF`~D?YFuqCYi)jfDsnA0HSlIJ!mWTWR+J;wr>(L&u@` z%oQNdt{q->J=q<3EcjHyFQvSTF<1_?W;a}TXA$C#4*0+7vx_}sUs(nf3vOAjul1x` z@#j(!r@nc{%vu&8O=A?uF?g0{cJnsiRNeHZNGY`9$W)fDBN$z8Lekr#&y^uQhFKl0 zb3s#X5`vzkU&f;!C8!wV6C->4CALf?#+BtiJpt&Mr&Mma*;j23xYe2 z9GwSrCndEa@x@?O_*i%NEdU1x=>x;RR)+YNS|Xnw3+6%H&ONE}JmEBZW25rUJB78% z8tz=1PQz~_(0MBMk1M7r-iuTudqrq;EeqeT56np%!%`ocHK{%e^w1NVg98r6ptmSpAH<3t=0uVOK0n%3E4 zCeFTI&G&y{@?53BdEzRH1GteP>*QFt;1T&q&h%kX-gf28QhuMkR10&Q$R?Et@95@*GG4mS@B7qd#OLrL$0YJ9D~5*3Jas{PZ#T z^6O8T?cQW>Wxi*j93=$irxM{FkrLrvzsM94sy$xbqKRdC-YY zo+oS^PYAsuy(6JF1wsim^xiw7(tGbkByJOI+M=IqNgy@6Fxuco6CKW&9cL9lc4c zGjc|W>rth~kGG8DVSZobzb=%f)icYuo=`b-e7E_AueT!otF-W(J2Kj)H*+SmM=qGh zPU4JXPtTS*sT3d;*ib3R`kK}f_bFbKrJUe7F-<}Sj)_Z1VdgJC>S|^4Z&Ymg$&kr! zx4ZTm+@DQ}SR#?o-w*cqnxd&Frm6$1t$Y+ zHJehvNK^_qwz%bPyyF|wy9R_MZPi)gsCe2O%NmWpIjzQhg(M6``7O&BP!JEVIX6FS zTdxf#tzlv&`O_(xLi4zb2jA5b@cTnQjAZKH3P2^`Y!-MK7Y?T>`P2Eo5gTCm240A7 z_-8f4|9c4kzfBlGUx?wfi3k6$?f@3Nq6A1RU7P0~L|Nnvh&(t7P%l~`* zNALd)`hO=3_@9ix@SbXb;Qv#`|I_vVH2Qx`gxh$i*Mj0jZv@GYDrS0~GCbMKvjvLu zwlbY#m;>|>k!h)zVsc|-+j4)+SXZ?`fSI%0R14Hw?2--q+o5+Ln!?`C{b#RWX#0B0 z6=hHPxcT3L@d5Ek;7GFI_l7;jVe$32R}XtD1>65Ngt9nZf2RRkrcDbxJ> z;kEoy6tET>$N2i=q~K)CoO2!rh07V6m}vS;h*rY3$I7d02eZ7DDo5bXT-Yp#@H-J; znDC0hR&ULL`>g$zTz1X*-taHm=M1>IqGG{rPe1Wxp5N&)mYZ#(f}CD(c*-FRbgxpr zdJ=9Wu})?Z9-+~$Jar-SqyJd)>CT28l#Kad+48GY4wiY=2en@KzWaDG@jIjH(g^`ekiNe6E@ z;*7}F;a{Kg{F=)>J^f{(OAF~Wx zIm-jp?>U<^0g(A%Vk`|uWPjZS72db###ApEsQaqk(Z?}MU2d~)nEbtl3{-#8b-H+& zzU=bn`7iF(M-F5@8nJm7x8R~T)%L#?u1z;l z{hs{<|6z?~I3gI6@lq{}77czmCz-dfZYSmN*ZH5Y%)1wy{~J0f&Yu7Ay)8|pfbG9Q z+wAz@vmcd7kG4;cPNve6&C7?Iaho_JYmK&VxBzBQ{5HkHb^b!w{IZztd%2517KML% zamV%5*GW=PrLgUbPR{5X)>Gj|EB_Xf=ctXEpV>xC)j=;|QQ5Z^KiiKK88@FSX$Lht zCQ!KhK6m-1cq%ibal4jhvXf|9Pr1uSdOlgK6#-Ka>3ZF!3KCmaVlpDwP-1 zbd;JHD~bK%UU{r`GB(}OSdU%Z+yB=zA6dKB>YAd`-$)(TSY9XMY$h#iYV|{xf5_eMx}OVY1hf&8XjL0=31-MUHgHG7%%FX@U&H8IwT9cUhE%ZaX`G)Dg;I{zhcD zK&lT1k*{H5G2PFO6%MY*$_S@v=BO(c&26}dpRd!ijggqe7yC97@iITgmMu0hQJ0$U zsyX4}5hdi`@-pAeIrb7@o0)jOB^q|so#j)ZEBIcp3g~{UI1+wZL2F_jM{cbh-gafI zuwbp`{*y63UaJN3GFW+%#Y+DE^0N~CzgPsbQ(fiz*?ofy@&#%GfN6QH_xw2ZXett* z9Vl!^8lMB32~pRhDQ0M4hKgQQe@d|daq8%&bh5fHKK~xG6qAYR^uhAY@3Qi+VB?zI zH@XR6AGLKE&YRPd3voD6Fo5Jq;!;Op3QE#lYN(cJ{(a=2x{;31Qew09(Lqw8aUWlq zEu7(bXmI9U(%UCh=zl1o$GyLwsMr3s;yck;%U#v|%r{niKkYVUL$&&GcA5l4+#=k# z!oMN%w=>^eEn|tuPWFM}hl}et$OkQ}nH^~ucIw*zuc?8K%K1}y#545kGx6>`C*RfW zZgs`PnairJc>%A{1FI#J&^NjUkq$}B#!$um+UiNuV {eP(=yeNaeKcGZcT=do_@ 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

?o2MjMcl+d!Pi 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

literal 0
HcmV?d00001

diff --git a/src/overview/img/high-level-overview.svg b/src/overview/img/high-level-overview.svg
new file mode 100644
index 000000000..ec92e2019
--- /dev/null
+++ b/src/overview/img/high-level-overview.svg
@@ -0,0 +1,355 @@
+
+
+rustc_areas
+
+
+cluster_querified
+
+Querified
+
+
+cluster_trait_solving_dependent
+
+Trait-solving dependent
+
+
+cluster_non_querified
+
+Non-querified
+
+
+cluster_legend
+
+Legend
+
+
+
+Executable
+
+Executables, cdylibs, staticlibs
+
+
+
+LLVM
+
+LLVM
+
+
+
+Executable->LLVM
+
+
+
+
+GCC
+
+GCC
+
+
+
+Executable->GCC
+
+
+
+
+Cranelift
+
+Cranelift
+
+
+
+Executable->Cranelift
+
+
+
+
+Libraries
+
+rlibs, dylibs
+
+
+
+Libraries->LLVM
+
+
+
+
+Libraries->GCC
+
+
+
+
+Libraries->Cranelift
+
+
+
+
+Metadata Encoding
+
+Metadata Encoding
+
+
+
+Libraries->Metadata Encoding
+
+
+
+
+Source Code
+
+Source Code
+
+
+
+SSA Code Generation
+
+SSA Code Generation
+
+
+
+LLVM->SSA Code Generation
+
+
+
+
+GCC->SSA Code Generation
+
+
+
+
+Monomorphization Collection
+
+Monomorphization Collection
+
+
+
+Cranelift->Monomorphization Collection
+
+
+
+
+SSA Code Generation->Monomorphization Collection
+
+
+
+
+
+Trait System
+
+Trait System
+
+
+
+SSA Code Generation->Trait System
+
+
+
+
+
+MIR Building, Transformations and Analysis
+
+MIR Building, Transformations and Analysis
+
+
+
+Monomorphization Collection->MIR Building, Transformations and Analysis
+
+
+
+
+
+Metadata Encoding->MIR Building, Transformations and Analysis
+
+
+
+
+
+THIR Building and Analysis
+
+THIR Building and Analysis
+
+
+
+MIR Building, Transformations and Analysis->THIR Building and Analysis
+
+
+
+
+
+HIR Body Type-checking
+
+HIR Body Type-checking
+
+
+
+THIR Building and Analysis->HIR Body Type-checking
+
+
+
+
+
+HIR Well-formedness Checking
+
+HIR Well-formedness Checking
+
+
+
+HIR Body Type-checking->HIR Well-formedness Checking
+
+
+
+
+
+HIR Type Lowering
+
+HIR Type Lowering
+
+
+
+HIR Well-formedness Checking->HIR Type Lowering
+
+
+
+
+
+Trait System->MIR Building, Transformations and Analysis
+
+
+
+
+
+Trait System->THIR Building and Analysis
+
+
+
+
+
+Trait System->HIR Body Type-checking
+
+
+
+
+
+Trait System->HIR Well-formedness Checking
+
+
+
+
+
+HIR Building
+
+HIR Building
+
+
+
+HIR Type Lowering->HIR Building
+
+
+
+
+
+Late Name Resolution
+
+Late Name Resolution
+
+
+
+HIR Building->Late Name Resolution
+
+
+
+
+
+AST Validation
+
+AST Validation
+
+
+
+Late Name Resolution->AST Validation
+
+
+
+
+
+Macro Expansion, Metadata Loading and Early Name Resolution
+
+Macro Expansion, Metadata Loading and Early Name Resolution
+
+
+
+AST Validation->Macro Expansion, Metadata Loading and Early Name Resolution
+
+
+
+
+
+Parsing
+
+Parsing
+
+
+
+Macro Expansion, Metadata Loading and Early Name Resolution->Parsing
+
+
+
+
+
+Parsing->Macro Expansion, Metadata Loading and Early Name Resolution
+
+
+
+
+
+Tokenization
+
+Tokenization
+
+
+
+Parsing->Tokenization
+
+
+
+
+
+Tokenization->Source Code
+
+
+
+
+
+key
+Pull-based Dependency 
+Push-based Dependency 
+Code Generation Pathway 
+
+
+
+key2
+ 
+ 
+ 
+
+
+
+key:e->key2:w
+
+
+
+
+
+key:e->key2:w
+
+
+
+
+
+key:e->key2:w
+
+
+
+
+
\ No newline at end of file
diff --git a/src/overview/img/mir-dialects-phases.svg b/src/overview/img/mir-dialects-phases.svg
new file mode 100644
index 000000000..9bf96889a
--- /dev/null
+++ b/src/overview/img/mir-dialects-phases.svg
@@ -0,0 +1,110 @@
+
+
+mir_transformations
+
+Mid-level Intermediate Representation (MIR) Dialects and Phases
+
+cluster_built
+
+Built Dialect
+
+
+cluster_analysis
+
+Analysis Dialect
+
+
+cluster_runtime
+
+Runtime Dialect
+
+
+cluster_legend
+
+Legend
+
+
+
+built
+
+No Distinct Phases
+
+
+
+analysis_initial
+
+Initial
+
+
+
+built->analysis_initial
+
+
+
+
+
+analysis_post_cleanup
+
+Post Cleanup
+
+
+
+analysis_initial->analysis_post_cleanup
+
+
+
+
+
+runtime_initial
+
+Initial
+
+
+
+analysis_post_cleanup->runtime_initial
+
+
+
+
+
+runtime_post_cleanup
+
+Post Cleanup
+
+
+
+runtime_initial->runtime_post_cleanup
+
+
+
+
+
+runtime_optimized
+
+Optimized
+
+
+
+runtime_post_cleanup->runtime_optimized
+
+
+
+
+
+key
+Transformation 
+
+
+
+key2
+ 
+
+
+
+key:e->key2:w
+
+
+
+
+
\ No newline at end of file
diff --git a/src/overview/overview.md b/src/overview/overview.md
index c5dc1bffe..42b406978 100644
--- a/src/overview/overview.md
+++ b/src/overview/overview.md
@@ -1,36 +1,14 @@
-> Thank you to everyone who contributed to this overview!
-
-> **NOTES ON THE OVERALL CHAPTER STRUCTURE**
->
-> We _embrace_ the query architecture and talk about areas _backwards_ compared
-> to traditional compiler texts. Since information dependence of the various
-> `rustc` areas form a Direct Acyclic Graph (DAG) at the query view (not acyclic
-> at the areas view), it makes sense to start at the root -- the final
-> executable -- and traverse the graph in a breadth-first traversal, all the way
-> until we get to name resolution. At that point, we can zoom out and talk about
-> the non-querified areas (in either reverse order like the querified areas, or
-> forwards order like traditional passes-based compilers, depending on which
-> order feels more natural).
-
-> We also want to contextualize each area and _why_ they exist -- what problems
-> do they solve?
+# Overview of the compiler
 
 In this chapter, we aim to describe `rustc` at a very high-level to show how the
 various areas work together. We introduce the _demand-driven architecture_ and
 the organization of `rustc` areas by their information dependency into a graph.
 For each area, we describe their purpose and motivation, and provide a small
-summary with links to chapters that go into more detail. We explain the
-distinction between early lints and late lints. We also briefly explore the
-compiler's error handling and reporting.
-
-# Overview of the compiler
+summary with links to chapters that go into more detail.
 
 > **UNDER CONSTRUCTION**
-
+>
 > - This section lacks motivation and reasoning for the query architecture.
-
-> **FIXME** Trait solving isn't correct here as it's a bit of a cross-cutting
-> concern between multiple areas.
 >
 > **UNRESOLVED QUESTIONS** How do we describe the relationship between trait
 > solving and the areas that it intertwines with? How do we describe error
@@ -62,6 +40,9 @@ explain each area in more detail in the next section.
 
 > **FIXME** What do we want the arrows to **actually** mean?
 
+![High-level overview](./img/high-level-overview.svg)
+
+
 
 ## Brief Summaries of the Areas
 
@@ -188,75 +163,180 @@ These various IRs gradually transform surface Rust syntax by simplications of
 language constructs and enriches the information available to lower-level areas
 by many analyses.
 
-### Querified Areas
+### Non-Querified Areas
 
-> 🚧 **XXX DO NOT KEEP: EXAMPLE AREA SUMMARY** 🚧
+We now flip our direction of traversal, and start from Source Code.
 
-> - A succinct summary of the responsibility of the area.
-> - Introduce the inputs. Briefly motivate why the inputs are why they are.
-> - Motivate the area's existence -- what does it do to / with the inputs? Why?
-> - Introduce the outputs. Briefly motivate why the outputs are what they are.
-> - Want to know more? Link to details chapter here. Link to "Additional
->   References" section below.
+#### Tokenization
 
-> :warning: **Where does trait system come in?** / **Where do we describe the
-> trait system here?** AFAIK, it's both dependent and and provides information
-> to multiple areas. Link: 
+The compiler takes the input, a stream of Unicode characters, and transforms it
+into a sequence of
+[`Token`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/token/index.html)s
+called a
+[`TokenStream`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/tokenstream/struct.TokenStream.html).
+This has multiple benefits:
 
-#### Static-Single Assignment (SSA) Code Generation
+- Separation of concerns: the lexer can be concerned with lower-level details
+  such as interning identifiers, collecting numeric literals, identifying
+  keywords and operators, associating source locations with the token, and
+  generate useful error reports for these cases. This simplifies the job of the
+  parser as it can then work with tokens, which is a higher level construct than
+  Unicode characters.
+- Simplifying the grammar: with a separate lexer, the parser can focus on
+  accepting a valid program according to a grammar defined in terms of _tokens_
+  instead of individual Unicode characters.
 
-Static Single Assignment (SSA) code generation is responsible for lowering
-Mid-Level Intermediate Representation (MIR) into SSA form (another kind of IR)
-which has the property that each variable is assigned to exactly once and is
-defined before use. Lowering into SSA form simplifies and enables more
-optimizations since it simplifies the properties of variables. It also makes it
-easier for code generation backends to handle. This area abstracts the common
-code generation logic and interfaces which code generation backends will need to
-implement.
+See [Lexing and Parsing](https://rustc-dev-guide.rust-lang.org/the-parser.html)
+for more details.
 
-In order to lower MIR to SSA, we depend on Monomohprization Collection to
-collect _Mono Items_ such as functions, methods and closures which contribute to
-code generation.
+#### Parsing
 
-See [Code
-Generation](https://rustc-dev-guide.rust-lang.org/backend/codegen.html) for more
+Given a token stream, the compiler builds a Abstract Syntax Tree (AST) that has
+a tree structure to enable tree-based reasoning and effectively represent the
+syntactical structure of the program. Rust has a macro system, which means that
+macros will need to be expanded in order to construct the full AST. Initially, a
+pre-expansion AST is constructed with placeholders for macros that are pending
+expansion.
+
+See [Lexing and Parsing](https://rustc-dev-guide.rust-lang.org/the-parser.html)
+for more details.
+
+#### Macro Expansion, Metadata Loading, Early Name Resolution and Late Name Resolution
+
+> **TODO**: this section needs a lot of work because I don't understand this
+> area too well so far
+
+After the pre-expansion AST is constructed, the compiler tries to build the full
+AST for a crate which has all macros expanded and all modules inlined.
+Unresolved macros are iteratively expanded, which requires resolving imports and
+macro names early (i.e. Early Name Resolution), but not other names yet.
+
+For import suggestions, the compiler may try to perform speculative crate
+loading via reading crate metadata that does not produce diagnostics for the
+speculatively loaded crate for import suggestion candidates.
+
+See [Macro
+Expansion](https://rustc-dev-guide.rust-lang.org/macro-expansion.html) and [Name
+Resolution](https://rustc-dev-guide.rust-lang.org/name-resolution.html) for more
 details.
 
-#### Monomorphization Collection
+#### AST Validation
 
-Monomorphization collection is the area responsible for collecting _Mono Items_
-which contribute to code generation: functions, methods, closures, statics, drop
-glue, constants, VTables and object shims. Functions need to be _monomorphized_
--- they might have generic type parameters, in which case the compiler has to
-instantiate the functions with the provided type arguments.
+Some basic sanity checks are performed on the AST, such as not having more than
+`u16::MAX` parameters, to catch some obvious user errors as well as errors in
+AST construction / macro expansion.
 
-See
-[Monomorphization](https://rustc-dev-guide.rust-lang.org/backend/monomorph.html)
+See [AST Validation](https://rustc-dev-guide.rust-lang.org/ast-validation.html)
 for more details.
 
-#### Metadata Encoding
+### Querified Areas
 
-Rust libraries are compiled to archives which consists of object code and
-_metadata_. Metadata is used by downstream crates to understand the interface of
-upstream crates: including (but are not limited to) exported items, function
-signatures, type definitions and MIR for generic functions[^proc-macro]. In this
-sense, metadata can be compared to precompiled C headers. Metadata Encoding is
-the area responsible for serializing this information into a common binary
-format that can be understood by both upstream and downstream crates.
+#### HIR Building
 
-Metadata is serialized via types which implement [`Encodable`], some of which
-are derived while others are hand-written implementations. Symmetrically,
-metadata can be read back by [`Decodable`] derives and manual deserialization
-implementations.
+High-level Intermediate Representation (HIR) is a lower-level IR than AST. When
+compared to AST, HIR has desugared constructs (such as desugaring `for` loops
+into `loop`s) to make analysis easier. When compared to MIR, HIR resembles the
+surface Rust syntax more closely. 
 
-[^proc-macro]: proc macro metadata has a trimmed down version which _only_
-    contains the exported macros without anything else defined inside the proc
-    macro.
+HIR building is the lowering from Abstract Syntax Tree (AST) into HIR. HIR is
+further desugared from AST to simplify analysis. There are sanity checks on the
+lowered HIR to catch obvious lowering mistakes.
 
-See [Libraries and
-Metadata](https://rustc-dev-guide.rust-lang.org/backend/libs-and-metadata.html)
+See [AST Lowering](https://rustc-dev-guide.rust-lang.org/ast-lowering.html) for
+more details.
+
+#### HIR Type Lowering
+
+HIR Type Lowering converts the more surface-syntax-like HIR type system entities
+(types, lifetimes/regions, constants in type positions) into
+[`rustc_middle::ty`](https://rustc-dev-guide.rust-lang.org/ty.html)
+representations to express the semantics of the type.
+
+See the [The `ty` module: representing
+types](https://rustc-dev-guide.rust-lang.org/ty.html) for more information.
+
+#### HIR Well-formedness Checking
+
+A type is _well-formed_ (WF) when it satisfies a set of requirements which are
+fundamental to the type's validity. The requirements are type-specific, for
+example:
+
+- For a tuple to be WF, all elements except for the last needs to be `Sized`.
+- For an algebraic data type (struct/enum/union) to be WF, its generics need to
+  satisfy the `where` clauses on the ADT.
+
+The notion of well-formedness can be inductively extended for entities that
+contain types, such as trait predicates. A trait predicate `T0: Trait`
+is well-formed if `T0` and `P1, ...` are well-formed in addition to `Trait`'s
+`where` clauses being satisfied.
+
+HIR well-formedness checking is an early collection of checks on mostly surface
+Rust syntax (such as parameters, local variables and return types) which are run
+before further type-checking and inference, for two purposes:
+
+1. For better error-reporting: a program which is not WF is more likely to give
+   hard-to-understand or spurious errors.
+2. To enable making simplifying assumptions in later HIR typeck: such as not
+   having to check if a tuple's fields are `Sized` when type checking a
+   `tuple.0` expression.
+
+Note that HIR WF checking are not the only place where WF checks take place:
+there are further WF checks in THIR/MIR to complement HIR WF checks.
+
+#### HIR Body Type-checking
+
+> 🚧 **TODO** 🚧 (remove the cat meme when complete with draft)
+
+
+
+The goal of HIR body typechecking is to catch mistakes that violate the rules of
+the type system, and infer types and other information necessary for THIR/MIR
+building. HIR body type-checking recursively walks and checks each expression.
+This process produces information such as the type of each expression. During
+the process, type inference, implicit cocercions, trait bound checking and
+method resolution is performed. Notably,
+
+- Method resolution is not performed in (early/late) Name Resolution because
+  type information is required.
+- Type inference is performed on HIR and not MIR because HIR maps closer to the
+  surface Rust syntax (and retains the tree-based structure), which enables more
+  descriptive errors and suggestions to be produced.
+- MIR building requires method resolution information from HIR type-checking to
+  guide the lowering.
+
+When compared to MIR typeck where all types are specified, HIR typeck has to
+infer types. HIR typeck also checks all closures together with their parent body
+while MIR typeck/borrowck checks them separately.
+
+See [Type checking](https://rustc-dev-guide.rust-lang.org/type-checking.html)
 for more details.
 
+#### Typed High-level Intermediate Representation (THIR) Building and Analysis
+
+Typed High-level Intermediate Representation (THIR) is a further desugared
+version of High-level Intermediate Representation (HIR) with full type
+information embedded. THIR is the last IR where lexical structure is meaningful
+for analysis in the chain of lowering from HIR to THIR to MIR and beyond, where
+lower-level IRs transition from being lexically-aware to being dataflow-aware.
+For example, unsafeck is performed on THIR and not MIR because we care about the
+lexical structure -- whether something exists inside an `unsafe` block
+lexically. To further simplify tree-based reasoning, THIR has several
+simplifications over HIR:
+
+- Explicit auto-deref/auto-ref and coercions.
+- Method calls are desugared into regular function calls.
+- Overloaded operators like `+` are lowered into function calls or builtin
+  operations.
+- Match ergonomics are desugared.
+
+With the aforementioned properties, the construction of THIR synthesizes enough
+information for MIR building, and makes lowering to MIR easier and less
+error-prone than if HIR was attempted to be directly lowered to MIR.
+
+See [The Typed High-level Intermediate
+Representation](https://rustc-dev-guide.rust-lang.org/thir.html) for more
+details.
+
 #### Mid-level Intermediate Representation (MIR) Building, Transformations and Analysis
 
 Mid-level Intermediate Representation (MIR) is an Intermediate Representation
@@ -282,6 +362,9 @@ desirable properties suitable for each of them. Some of the analyses include
 borrow-checking, drop elaboration, coroutine transformations, const promotion,
 further well-formedness checking and some late type-checking.
 
+![MIR Dialects and Phases](./img/mir-dialects-phases.svg)
+
+
 
 MIR optimizations generally are opportunistic: because we're before
 monomorphization, there are e.g. constants related to generic parameters whose
@@ -346,177 +430,62 @@ See [Mid-level Intermediate
 Representation](https://rustc-dev-guide.rust-lang.org/mir/index.html) for more
 details.
 
-#### Typed High-level Intermediate Representation (THIR) Building and Analysis
-
-Typed High-level Intermediate Representation (THIR) is a further desugared
-version of High-level Intermediate Representation (HIR) with full type
-information embedded. THIR is the last IR where lexical structure is meaningful
-for analysis in the chain of lowering from HIR to THIR to MIR and beyond, where
-lower-level IRs transition from being lexically-aware to being dataflow-aware.
-For example, unsafeck is performed on THIR and not MIR because we care about the
-lexical structure -- whether something exists inside an `unsafe` block
-lexically. To further simplify tree-based reasoning, THIR has several
-simplifications over HIR:
-
-- Explicit auto-deref/auto-ref and coercions.
-- Method calls are desugared into regular function calls.
-- Overloaded operators like `+` are lowered into function calls or builtin
-  operations.
-- Match ergonomics are desugared.
-
-With the aforementioned properties, the construction of THIR synthesizes enough
-information for MIR building, and makes lowering to MIR easier and less
-error-prone than if HIR was attempted to be directly lowered to MIR.
-
-See [The Typed High-level Intermediate
-Representation](https://rustc-dev-guide.rust-lang.org/thir.html) for more
-details.
-
-#### HIR Body Type-checking
-
-> 🚧 **TODO** 🚧 (Remove the cat meme when complete with draft)
-
-![](https://hackmd.io/_uploads/ry2CM6gAa.jpg)
-
-High-level Intermediate Representation (HIR) is a higher-level IR than THIR.
-When compared to MIR, HIR resembles the surface Rust syntax more closely. When
-compared to AST, HIR has desugared constructs (such as desugaring `for` loops
-into `loop`s) to make analysis easier.
-
-The goal of HIR body typechecking is to infer types and other information
-necessary for THIR/MIR building. HIR body type-checking recursively walks and
-checks each expression. This process produces information such as the type of
-each expression. During the process, type inference, implicit cocercions, trait
-bound checking and method resolution is performed. Notably,
-
-- Method resolution is not performed in (early/late) Name Resolution because
-  type information is required.
-- Type inference is performed on HIR and not MIR because HIR maps closer to the
-  surface Rust syntax (and retains the tree-based structure), which enables more
-  descriptive errors and suggestions to be produced.
-- MIR building requires method resolution information from HIR type-checking to
-  guide the lowering.
-
-When compared to MIR typeck where all types are specified, HIR typeck has to
-infer types. HIR typeck also checks all closures together with their parent body
-while MIR typeck/borrowck checks them separately.
-
-See [Type checking](https://rustc-dev-guide.rust-lang.org/type-checking.html)
-for more details.
-
-#### HIR Well-formedness Checking
-
-A type is _well-formed_ (WF) when it satisfies a set of requirements which are
-fundamental to the type's validity. The requirements are type-specific, for
-example:
-
-- For a tuple to be WF, all elements except for the last needs to be `Sized`.
-- For an algebraic data type (struct/enum/union) to be WF, its generics need to
-  satisfy the `where` clauses on the ADT.
-
-The notion of well-formedness can be inductively extended for entities that
-contain types, such as trait predicates. A trait predicate `T0: Trait`
-is well-formed if `T0` and `P1, ...` are well-formed in addition to `Trait`'s
-`where` clauses being satisfied.
-
-HIR well-formedness checking is an early collection of checks on mostly surface
-Rust syntax (such as parameters, local variables and return types) which are run
-before further type-checking and inference, for two purposes:
-
-1. For better error-reporting: a program which is not WF is more likely to give
-   hard-to-understand or spurious errors.
-2. To enable making simplifying assumptions in later HIR typeck: such as not
-   having to check if a tuple's fields are `Sized` when type checking a
-   `tuple.0` expression.
-
-Note that HIR WF checking are not the only place where WF checks take place:
-there are further WF checks in THIR/MIR to complement HIR WF checks.
-
-#### The Trait System
-
-> 🚧 **TODO** 🚧 I don't know how to describe the Trait System at all here.
-
-#### HIR Type Lowering
-
-HIR Type Lowering converts the more surface-syntax-like HIR type system entities
-(types, lifetimes/regions, constants in type positions) into
-[`rustc_middle::ty`](https://rustc-dev-guide.rust-lang.org/ty.html)
-representations to express the semantics of the type.
-
-See the [The `ty` module: representing
-types](https://rustc-dev-guide.rust-lang.org/ty.html) for more information.
-
-#### HIR Building
-
-HIR building is the lowering from Abstract Syntax Tree (AST) into HIR. HIR is
-further desugared from AST to simplify analysis. There are sanity checks on the
-lowered HIR to catch obvious lowering mistakes.
-
-See [AST Lowering](https://rustc-dev-guide.rust-lang.org/ast-lowering.html) for
-more details.
-
-### Non-Querified Areas
-
-We now flip our direction of traversal, and start from Source Code.
+#### Metadata Encoding
 
-#### Tokenization
+Rust libraries are compiled to archives which consists of object code and
+_metadata_. Metadata is used by downstream crates to understand the interface of
+upstream crates: including (but are not limited to) exported items, function
+signatures, type definitions and MIR for generic functions[^proc-macro]. In this
+sense, metadata can be compared to precompiled C headers. Metadata Encoding is
+the area responsible for serializing this information into a common binary
+format that can be understood by both upstream and downstream crates.
 
-The compiler takes the input, a stream of Unicode characters, and transforms it
-into a sequence of
-[`Token`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/token/index.html)s
-called a
-[`TokenStream`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/tokenstream/struct.TokenStream.html).
-This has multiple benefits:
+Metadata is serialized via types which implement [`Encodable`], some of which
+are derived while others are hand-written implementations. Symmetrically,
+metadata can be read back by [`Decodable`] derives and manual deserialization
+implementations.
 
-- Separation of concerns: the lexer can be concerned with lower-level details
-  such as interning identifiers, collecting numeric literals, identifying
-  keywords and operators, associating source locations with the token, and
-  generate useful error reports for these cases. This simplifies the job of the
-  parser as it can then work with tokens, which is a higher level construct than
-  Unicode characters.
-- Simplifying the grammar: with a separate lexer, the parser can focus on
-  accepting a valid program according to a grammar defined in terms of _tokens_
-  instead of individual Unicode characters.
+[^proc-macro]: proc macro metadata has a trimmed down version which _only_
+    contains the exported macros without anything else defined inside the proc
+    macro.
 
-See [Lexing and Parsing](https://rustc-dev-guide.rust-lang.org/the-parser.html)
+See [Libraries and
+Metadata](https://rustc-dev-guide.rust-lang.org/backend/libs-and-metadata.html)
 for more details.
 
-#### Parsing
+#### Monomorphization Collection
 
-Given a token stream, the compiler builds a Abstract Syntax Tree (AST) that has
-a tree structure to enable tree-based reasoning and effectively represent the
-syntactical structure of the program. Rust has a macro system, which means that
-macros will need to be expanded in order to construct the full AST. Initially, a
-pre-expansion AST is constructed with placeholders for macros that are pending
-expansion.
+Monomorphization collection is the area responsible for collecting _Mono Items_
+which contribute to code generation: functions, methods, closures, statics, drop
+glue, constants, VTables and object shims. Functions need to be _monomorphized_
+-- they might have generic type parameters, in which case the compiler has to
+instantiate the functions with the provided type arguments.
 
-See [Lexing and Parsing](https://rustc-dev-guide.rust-lang.org/the-parser.html)
+See
+[Monomorphization](https://rustc-dev-guide.rust-lang.org/backend/monomorph.html)
 for more details.
 
-#### Macro Expansion, Metadata Loading, Early Name Resolution and Late Name Resolution
+#### Static-Single Assignment (SSA) Code Generation
 
-After the pre-expansion AST is constructed, the compiler tries to build the full
-AST for a crate which has all macros expanded and all modules inlined.
-Unresolved macros are iteratively expanded, which requires resolving imports and
-macro names early (i.e. Early Name Resolution), but not other names yet.
+Static Single Assignment (SSA) code generation is responsible for lowering
+Mid-Level Intermediate Representation (MIR) into SSA form (another kind of IR)
+which has the property that each variable is assigned to exactly once and is
+defined before use. Lowering into SSA form enables more optimizations since it
+simplifies the properties of variables. It also makes it easier for code
+generation backends to handle. This area abstracts the common code generation
+logic and interfaces which code generation backends will need to implement.
 
-For import suggestions, the compiler may try to perform speculative crate
-loading via reading crate metadata that does not produce diagnostics for the
-speculatively loaded crate for import suggestion candidates.
+In order to lower MIR to SSA, we depend on Monomohprization Collection to
+collect _Mono Items_ such as functions, methods and closures which contribute to
+code generation.
 
-See [Macro
-Expansion](https://rustc-dev-guide.rust-lang.org/macro-expansion.html) and [Name
-Resolution](https://rustc-dev-guide.rust-lang.org/name-resolution.html) for more
+See [Code
+Generation](https://rustc-dev-guide.rust-lang.org/backend/codegen.html) for more
 details.
 
-#### Abstract Syntax Tree (AST) Validation
-
-Some basic sanity checks are performed on the AST, such as not having more than
-`u16::MAX` parameters, to catch some obvious user errors as well as errors in
-AST construction / macro expansion.
+#### The Trait System
 
-See [AST Validation](https://rustc-dev-guide.rust-lang.org/ast-validation.html)
-for more details.
+> 🚧 **TODO** 🚧 I don't know how to describe the Trait System at all here.
 
 ## Additional References and Resources
 
@@ -635,9 +604,9 @@ for more details.
       and
       [`rustc_codegen_ssa::base::codegen_instance`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/base/fn.codegen_instance.html)
 
-[`decodable`]:
+[`Decodable`]:
     https://doc.rust-lang.org/nightly/nightly-rustc/rustc_serialize/trait.Decodable.html
-[`encodable`]:
+[`Encodable`]:
     https://doc.rust-lang.org/nightly/nightly-rustc/rustc_serialize/trait.Encodable.html
-[`switchint`]:
+[`SwitchInt`]:
     https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/enum.TerminatorKind.html#variant.SwitchInt

From 28a153b4b98d53ab8873550fe2fe82d951071025 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=AE=B8=E6=9D=B0=E5=8F=8B=20Jieyou=20Xu=20=28Joe=29?=
 
Date: Mon, 8 Apr 2024 15:05:28 +0100
Subject: [PATCH 4/6] overview(R2): revise HIR wfcheck, stub out
 driver/interface and codegen backends

- Extend HIR wfcheck to cover not only type wfcheck, but other HIR
  wfchecks like object safety.
- Stub out rustc driver/interface as the high-level entry point and
  orchestrator of the compilation process.
- Stub out codegen backends.
---
 src/overview/overview.md | 51 +++++++++++++++++++++++++---------------
 1 file changed, 32 insertions(+), 19 deletions(-)

diff --git a/src/overview/overview.md b/src/overview/overview.md
index 42b406978..deed9a4de 100644
--- a/src/overview/overview.md
+++ b/src/overview/overview.md
@@ -35,8 +35,7 @@ information.
 Ideally, the entire compiler would be organized as queries. However, as of the
 time of writing (March 2024), `rustc` still has several areas which are not yet
 querified and work like conventional passes. The following diagram illustrates
-this distinction as well as the information dependency between areas. We will
-explain each area in more detail in the next section.
+this distinction as well as the information dependency between areas.
 
 > **FIXME** What do we want the arrows to **actually** mean?
 
@@ -132,14 +131,7 @@ digraph rustc_areas {
 ```
 -->
 
-## Brief Summaries of the Areas
-
-> **UNDER CONSTRUCTION** This section lacks exhaustive list of areas and their
-> summaries. This should ideally be ordered based on a BFS traversal related to
-> the information dependency presented in the previous section.
-
-We now summarize areas following the order of their information dependency. To
-produce the final executable, we take one of the several code generation
+To produce the final executable, we take one of the several code generation
 pathways. For example, to produce an executable following the LLVM pathway, we
 rely on the synthesis of LLVM IR from SSA code generation. Code generation in
 turn relies on information produced by Monomorphization Collection, and so on.
@@ -147,8 +139,7 @@ We keep following the dependencies for the querified areas until we reach HIR
 Lowering, which depends on information from non-querified areas of the compiler.
 At that boundary, we make a distinction between the pull-based information
 dependency of querified areas versus push-based information dependency of the
-non-querified areas. We flip our direction, and trace from the source code until
-Late Name Resolution.
+non-querified areas.
 
 To pass information between areas, the compiler uses various _Intermediate
 Representations_ (IRs), which provide common interfaces to allow areas to
@@ -163,9 +154,15 @@ These various IRs gradually transform surface Rust syntax by simplications of
 language constructs and enriches the information available to lower-level areas
 by many analyses.
 
-### Non-Querified Areas
+We will explain each area in more detail in the next section.
 
-We now flip our direction of traversal, and start from Source Code.
+## Brief Summaries of the Areas
+
+### The Compiler Driver and the Interface
+
+> **TODO** write about this
+
+### Non-Querified Areas
 
 #### Tokenization
 
@@ -265,7 +262,7 @@ example:
 - For an algebraic data type (struct/enum/union) to be WF, its generics need to
   satisfy the `where` clauses on the ADT.
 
-The notion of well-formedness can be inductively extended for entities that
+The notion of type well-formedness can be inductively extended for entities that
 contain types, such as trait predicates. A trait predicate `T0: Trait`
 is well-formed if `T0` and `P1, ...` are well-formed in addition to `Trait`'s
 `where` clauses being satisfied.
@@ -280,8 +277,18 @@ before further type-checking and inference, for two purposes:
    having to check if a tuple's fields are `Sized` when type checking a
    `tuple.0` expression.
 
-Note that HIR WF checking are not the only place where WF checks take place:
-there are further WF checks in THIR/MIR to complement HIR WF checks.
+The HIR is _well-formed_ (WF) when it satisfies a set of requirements that
+include but are not limited to:
+
+- well-formedness of types in type signatures
+- object safety is respected
+- function call ABI requirements (e.g. for "rust-call") are satisfied
+- receiver type can be used as a self type
+- variances are compatible
+- and many more
+
+Note that HIR WF checking are also not the only place where WF checks take
+place: there are further WF checks in THIR/MIR to complement HIR WF checks.
 
 #### HIR Body Type-checking
 
@@ -465,6 +472,10 @@ See
 [Monomorphization](https://rustc-dev-guide.rust-lang.org/backend/monomorph.html)
 for more details.
 
+#### The Trait System
+
+> 🚧 **TODO** 🚧 I don't know how to describe the Trait System at all here.
+
 #### Static-Single Assignment (SSA) Code Generation
 
 Static Single Assignment (SSA) code generation is responsible for lowering
@@ -483,9 +494,9 @@ See [Code
 Generation](https://rustc-dev-guide.rust-lang.org/backend/codegen.html) for more
 details.
 
-#### The Trait System
+#### Codegen backends: LLVM, GCC and Cranelift
 
-> 🚧 **TODO** 🚧 I don't know how to describe the Trait System at all here.
+> 🚧 **TODO** 🚧 need more information.
 
 ## Additional References and Resources
 
@@ -503,6 +514,8 @@ details.
 > **UNDER CONSTRUCTION** This should retain _key entry points_ from the previous
 > overview version. Can be very useful. We should expand it a bit. This section
 > lacks additional references.
+>
+> **FIXME**: audit these references and links, they are likely very outdated
 
 - Command line parsing
 

From b074ec320f55ca761ef79479732adcfecdebc140 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=AE=B8=E6=9D=B0=E5=8F=8B=20Jieyou=20Xu=20=28Joe=29?=
 
Date: Mon, 8 Apr 2024 15:38:52 +0100
Subject: [PATCH 5/6] overview(R3): fix a bunch of links

---
 src/overview/overview.md    | 28 ++++++++++++++--------------
 src/overview/walkthrough.md | 20 ++++++++++----------
 2 files changed, 24 insertions(+), 24 deletions(-)

diff --git a/src/overview/overview.md b/src/overview/overview.md
index deed9a4de..2c602ee9b 100644
--- a/src/overview/overview.md
+++ b/src/overview/overview.md
@@ -519,7 +519,7 @@ details.
 
 - Command line parsing
 
-  - Guide: [The Rustc Driver and Interface](rustc-driver.md)
+  - Guide: [The Rustc Driver and Interface](../rustc-driver.md)
   - Driver definition:
     [`rustc_driver`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/)
   - Main entry point:
@@ -527,7 +527,7 @@ details.
 
 - Lexical Analysis: Lex the user program to a stream of tokens
 
-  - Guide: [Lexing and Parsing](the-parser.md)
+  - Guide: [Lexing and Parsing](../the-parser.md)
   - Lexer definition:
     [`rustc_lexer`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lexer/index.html)
   - Main entry point:
@@ -535,9 +535,9 @@ details.
 
 - Parsing: Parse the stream of tokens to an Abstract Syntax Tree (AST)
 
-  - Guide: [Lexing and Parsing](the-parser.md)
-  - Guide: [Macro Expansion](macro-expansion.md)
-  - Guide: [Name Resolution](name-resolution.md)
+  - Guide: [Lexing and Parsing](../the-parser.md)
+  - Guide: [Macro Expansion](../macro-expansion.md)
+  - Guide: [Name Resolution](../name-resolution.md)
   - Parser definition:
     [`rustc_parse`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/index.html)
   - Main entry points:
@@ -555,10 +555,10 @@ details.
 
 - The High Level Intermediate Representation (HIR)
 
-  - Guide: [The HIR](hir.md)
-  - Guide: [Identifiers in the HIR](hir.md#identifiers-in-the-hir)
-  - Guide: [The `HIR` Map](hir.md#the-hir-map)
-  - Guide: [Lowering `AST` to `HIR`](ast-lowering.md)
+  - Guide: [The HIR](../hir.md)
+  - Guide: [Identifiers in the HIR](../hir.md#identifiers-in-the-hir)
+  - Guide: [The `HIR` Map](../hir.md#the-hir-map)
+  - Guide: [Lowering `AST` to `HIR`](../ast-lowering.md)
   - How to view `HIR` representation for your code `cargo rustc -- -Z
     unpretty=hir-tree`
   - Rustc `HIR` definition:
@@ -568,8 +568,8 @@ details.
 
 - Type Inference
 
-  - Guide: [Type Inference](type-inference.md)
-  - Guide: [The ty Module: Representing Types](ty.md) (semantics)
+  - Guide: [Type Inference](../type-inference.md)
+  - Guide: [The ty Module: Representing Types](../ty.md) (semantics)
   - Main entry point (type inference):
     [`InferCtxtBuilder::enter`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/infer/struct.InferCtxtBuilder.html#method.enter)
   - Main entry point (type checking bodies): [the `typeck`
@@ -579,7 +579,7 @@ details.
 
 - The Mid Level Intermediate Representation (MIR)
 
-  - Guide: [The `MIR` (Mid level IR)](mir/index.md)
+  - Guide: [The `MIR` (Mid level IR)](../mir/index.md)
   - Definition:
     [`rustc_middle/src/mir`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/index.html)
   - Definition of sources that manipulates the MIR:
@@ -589,7 +589,7 @@ details.
 
 - The Borrow Checker
 
-  - Guide: [MIR Borrow Check](borrow_check.md)
+  - Guide: [MIR Borrow Check](../borrow_check.md)
   - Definition:
     [`rustc_borrowck`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_borrowck/index.html)
   - Main entry point: [`mir_borrowck`
@@ -597,7 +597,7 @@ details.
 
 - `MIR` Optimizations
 
-  - Guide: [MIR Optimizations](mir/optimizations.md)
+  - Guide: [MIR Optimizations](../mir/optimizations.md)
   - Definition:
     [`rustc_mir_transform`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/index.html)
   - Main entry point: [`optimized_mir`
diff --git a/src/overview/walkthrough.md b/src/overview/walkthrough.md
index 757c1668c..132a61520 100644
--- a/src/overview/walkthrough.md
+++ b/src/overview/walkthrough.md
@@ -129,9 +129,9 @@ with additional low-level types and annotations added (e.g. an ELF object or
 `WASM`). The different libraries/binaries are then linked together to produce
 the final binary.
 
-[*trait solving*]: traits/resolution.md
-[*type checking*]: type-checking.md
-[*type inference*]: type-inference.md
+[*trait solving*]: ../traits/resolution.md
+[*type checking*]: ../type-checking.md
+[*type inference*]: ../type-inference.md
 [`bump`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/parser/struct.Parser.html#method.bump
 [`check`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/parser/struct.Parser.html#method.check
 [`Crate`]: https://doc.rust-lang.org/beta/nightly-rustc/rustc_ast/ast/struct.Crate.html
@@ -144,7 +144,7 @@ the final binary.
 [`Parser`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/parser/struct.Parser.html
 [`Pat`]: https://doc.rust-lang.org/beta/nightly-rustc/rustc_ast/ast/struct.Pat.html
 [`rustc_ast::ast`]: https://doc.rust-lang.org/beta/nightly-rustc/rustc_ast/index.html
-[`rustc_driver`]: rustc-driver.md
+[`rustc_driver`]: ../rustc-driver.md
 [`rustc_interface::Config`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/interface/struct.Config.html
 [`rustc_lexer`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lexer/index.html
 [`rustc_parse::lexer`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/lexer/index.html
@@ -153,12 +153,12 @@ the final binary.
 [`simplify_try`]: https://github.com/rust-lang/rust/pull/66282
 [`StringReader`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/lexer/struct.StringReader.html
 [`Ty<'tcx>`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.Ty.html
-[borrow checking]: borrow_check.md
-[codegen]: backend/codegen.md
+[borrow checking]: ../borrow_check.md
+[codegen]: ../backend/codegen.md
 [hir]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/index.html
-[lex]: the-parser.md
-[mir-opt]: mir/optimizations.md
-[mir]: mir/index.md
+[lex]: ../the-parser.md
+[mir-opt]: ../mir/optimizations.md
+[mir]: ../mir/index.md
 [parse_crate_mod]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/parser/struct.Parser.html#method.parse_crate_mod
 [parse_external_mod]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_expand/module/fn.parse_external_mod.html
 [parse_mod]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/parser/struct.Parser.html#method.parse_mod
@@ -368,7 +368,7 @@ For more details on bootstrapping, see
 [the bootstrapping section of the guide][rustc-bootstrap].
 
 [_bootstrapping_]: https://en.wikipedia.org/wiki/Bootstrapping_(compilers)
-[rustc-bootstrap]: building/bootstrapping/intro.md
+[rustc-bootstrap]: ../building/bootstrapping/intro.md