├── README.md ├── events ├── 2021-11-14.md └── 2021-11-7.md └── logs ├── .keep └── name-resolve.md /README.md: -------------------------------------------------------------------------------- 1 | # Rust 源码阅读俱乐部 (Rust Code Reading Club) 2 | 3 | 4 | ## 介绍 5 | 6 | 最近 Rust 官方发起了 Rust 源码阅读俱乐部 活动，参见 [Rust Code Reading Club](https://mojosd.medium.com/rust-code-reading-club-8fe356287049) 。 7 | 8 | 此活动目的就是为了让更多人为 Rust 编译器做贡献。由 语言工作组 Leader Niko 亲自来讲解 Rust 编译器中的源码。 9 | 10 | 11 | 为了响应官方的活动，我在飞书 Rust 中文社群发起每周源码阅读在线沙龙。 12 | 13 | 每周五/六/日 不定时活动： 14 | 15 | - 跟随 Rust 官方的 源码阅读俱乐部活动 16 | - 自发组织的 Rust 生态库源码阅读活动 17 | 18 | 本仓库用于记录每次活动的日志和内容沉淀 19 | 20 | ## 活动 21 | 22 | - [2021-11-7: Rust 编译器源码阅读｜名称解析](./events/2021-11-7.md) 23 | 24 | ## 如何加入飞书群 25 | 26 | [如何加入飞书群？](https://github.com/ZhangHanDong/rust-code-reading-club/issues/1) 27 | -------------------------------------------------------------------------------- /events/2021-11-14.md: -------------------------------------------------------------------------------- 1 | # Rust 源码阅读活动 ｜ 第二期 2 | 3 | ## 活动安排 4 | 5 | - Rust 源码阅读活动 16:00 ～ 17:30 6 | - Tokio 源码阅读活动 14: 00 ～ 15:30 -------------------------------------------------------------------------------- /events/2021-11-7.md: -------------------------------------------------------------------------------- 1 | # Rust 源码阅读活动 ｜ 第一期 2 | 3 | ## 前情提要 4 | 5 | 因为官方原定于 11.4 号的活动因为线上zoom 房间人太多，Niko 无法进入房间，被迫取消。官方在重新确定会议工具后再作通知。 6 | 7 | 但是我们中文社区的活动会正常启动。本来打算的回顾活动，现在变成了预习。 8 | 9 | ## 活动安排 10 | 11 | 2021.11.07 14:00 ～ 15:30 于 Rust 中文社群飞书群内举行。欢迎大家参与。 12 | 13 | ### 主题： Rust 编译器源码阅读｜名称解析 14 | 15 | 相关代码：[compiler/rustc_resolve/src](https://github.com/rust-lang/rust/tree/master/compiler/rustc_resolve/src) 16 | 17 | ### 参与前准备： 18 | 19 | 1. 阅读 《the-programmers-brain》 这本书 20 | 2. 阅读 Rustc dev guide ，了解下 Rust 编译过程 21 | 3. 阅读 [compiler/rustc_resolve/src](https://github.com/rust-lang/rust/tree/master/compiler/rustc_resolve/src) 文档相关，了解该库 22 | 23 | 24 | ### 工具 25 | 26 | - [代码阅读着色工具（代码要使用永久链接）](https://annotate.code-reading.org/#/) -------------------------------------------------------------------------------- /logs/.keep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ZhangHanDong/rust-code-reading-club/3d846bd02a75e6ea0c08d6a16124454129967bf9/logs/.keep -------------------------------------------------------------------------------- /logs/name-resolve.md: -------------------------------------------------------------------------------- 1 | # Rust 源码阅读俱乐部 | 第一期 2 | 3 | 说明： 这不是线上沙龙的文字记录，而是我本人会后的学习记录。 4 | 5 | ## 引子 6 | 7 | 最近 Rust 官方发起了 Rust 源码阅读俱乐部 活动，参见 [Rust Code Reading Club](https://mojosd.medium.com/rust-code-reading-club-8fe356287049) 。 8 | 9 | 此活动目的就是为了让更多人为 Rust 编译器做贡献。由 语言工作组 Leader Niko 亲自来讲解 Rust 编译器中的源码。 10 | 11 | 这次活动不会有任何回放，只能实时参与。 12 | 13 | 参与人员条件： 14 | 15 | 1. 听得懂英文 16 | 2. 对 Rust 有一定了解，不必要了解 Rust 的所有角落 17 | 3. 不一定需要编译器背景知识，但是需要阅读 [Rustc Dev guide ](https://rustc-dev-guide.rust-lang.org/) (中文版也需要你的贡献： [https://github.com/RustcRustc/rustc-dev-guide-zh](https://github.com/RustcRustc/rustc-dev-guide-zh)) 18 | 19 | 第一期活动： 20 | 21 | - 时间： 2021-11-04 12:00 - 13:30 US Eastern time ([see in your time zone](https://everytimezone.com/s/a287d2e5)) 22 | - 方式 zoom 23 | - 内容： [compiler/rustc_resolve/src](https://github.com/rust-lang/rust/tree/master/compiler/rustc_resolve/src) 24 | - Slides： [https://hackmd.io/@rustc-reading-club/S1xsDveDK#/1](https://hackmd.io/@rustc-reading-club/S1xsDveDK#/1) 25 | 26 | 参与前准备： 27 | 28 | 1. 阅读 《the-programmers-brain》 这本书 29 | 2. 阅读 Rustc dev guide ，了解下 Rust 编译过程 30 | 3. 阅读 [compiler/rustc_resolve/src](https://github.com/rust-lang/rust/tree/master/compiler/rustc_resolve/src) 文档相关，了解该库 31 | 32 | 33 | 34 | ### Rust 飞书群 Rust 源码阅读俱乐部 35 | 36 | 为了响应官方的活动，我在飞书 Rust 中文社群也准备每周六或日，也组织一次源码阅读在线沙龙。 37 | 38 | 内容就是跟随官方内容，共同学习。 39 | 40 | 并且会把每周源码学习记录下来，行为文字输出，分享给大家。 41 | 42 | [如何加入飞书的Rust 中文社群?](https://github.com/ZhangHanDong/rust-code-reading-club/issues/1) 43 | 44 | 45 | 46 | ### 准备工作 47 | 48 | #### 书籍推荐《 The Programmer's Brain》 49 | 50 | Rust 官方推荐了《The Programmer's Brain》 这本书，在[ Manning 的官网](https://www.manning.com/books/the-programmers-brain)可以免费看这本书的在线版本。如果要翻译书名的话，我觉得《编程大脑》这个名字还行？ 听说这本书已经被国内出版社引进。 51 | 52 | 这本书分为四部分： 53 | 54 | 1. 如何更好地阅读代码 55 | 2. 关于代码的思考 56 | 3. 编写更好的代码 57 | 4. 关于代码协作 58 | 59 | 这本书的特点在于，它会介绍不同类型代码和大脑认知思维之间的联系，而不是纯技巧罗列。 60 | 61 | 既然 Rust 官方推荐这本书，那说明它的内容还是有一定价值，感兴趣可以去看看。 62 | 63 | ##### 关于编程过程中的三类困扰 64 | 65 | 这一期分享这本书第一章中提到的编程过程中的三类困扰开发者的问题： 66 | 67 | 1. 缺乏知识（Lack of knowledge，对应长期记忆 long-term memory ， LTM）。指开发者缺乏基本的编程语言的知识，无法使用或理解基本的语法，而造成的困扰。 68 | 2. 缺乏信息（Lack of information，对应短期记忆， short-term memory， STM）。指开发者缺乏程序要处理的问题领域信息的了解，而造成的困扰。 69 | 3. 缺乏处理能力（Lack of processing power ，对应工作记忆，working memory，WM）。指开发者缺乏对整个编程执行过程的处理能力，而造成的困扰。 70 | 71 | 这三类问题，不仅仅困扰开发者编写新的程序，还对开发者阅读既有代码造成困扰。 72 | 73 | 所以，当我们在阅读别人写的源码时，要确保对这三类问题中缺乏的知识有一个预备补充。 74 | 75 | #### 我的源码阅读习惯 76 | 77 | 我阅读源码和读书的方式一致，都是从整体结构到细节。 78 | 79 | 首先要确保自己对 `rustc_resolve` 这个库的上下文信息有所了解，也就是上面提到的 编程过程中的三类困扰中的第二类问题要做信息补充。第一类和第三类问题，相信对于 非 Rust 新手应该是可以避开了。一般阅读 Rust 源码最常见的问题就是第二类问题，缺乏对程序要处理问题领域的信息的了解。 80 | 81 | #### 官方建议的阅读方法 82 | 83 | 在 [官方给出的 Rustc 源码阅读第一期 Slides](https://hackmd.io/@rustc-reading-club/S1xsDveDK#/1) 中，建议采用一种 广-深-广( `Broad - deep - broad`) 的三段阅读方法。 84 | 85 | 具体来说： 86 | 87 | 1. 广（`Broad`）： 整体了解模块。 88 | 2. 深（`Deep`）： 聚焦于某个函数或小片区域（你感兴趣的，或有疑问的）。 89 | 3. 广（`Broad`）： 回到整个模块中。 90 | 91 | 按上述三段阅读方法来执行几轮，整个代码就读完了。 92 | 93 | 94 | 95 | ## Rustc 编译器架构 96 | 97 | 在 [Rustc Dev Guide](https://rustc-dev-guide.rust-lang.org/overview.html) 中介绍了 Rust 编译器（Rustc） 的 整体架构。 98 | 99 | Rustc 编译器架构不同于传统的编译器架构。传统编译器架构是 **基于 遍历** (`pass-based`) 而设计，Rust 编译器架构则是 **基于 按需驱动**（`demand-driven`）而设计。 100 | 101 | ### 基于遍历 的编译器架构 102 | 103 | 所谓 遍历（`Pass`） ，就是对 代码 / `AST ` 扫描并进行处理。 104 | 105 | 早期的编译器一般都是 `Single Pass` 的，后来又出现 `Multi Pass` ，并且分为编译前端和后端。前端负责生成 `AST` ，而后端用于生成机器码。编译流程的每一步都被抽象为 `Pass`，这个称呼最早由 `LLVM` 采用，进而扩展到整个编译原理领域。 106 | 107 | 遍历 分为两类： 108 | 109 | - 分析（analysis）遍历，负责收集信息供其他 Pass 使用，辅助调试或使程序可视化 110 | - 变换 （transform）遍历，用于改变程序的数据流或控制流，比如优化等 111 | 112 | 这两类遍历流程，也对应着编译器的两大阶段：分析阶段和综合阶段。前者从给定的源码文本创建出一个中间表示，后者从中间表示创建等效的目标程序。 113 | 114 | 编译器前端一般对应于 分析阶段，编译器后端对应于综合阶段。 115 | 116 | 编译器前端又包括以下几部分： 117 | 118 | 1. 词法分析器 119 | 2. 语法分析器 120 | 3. 语义分析器 121 | 4. 中间代码生成器 122 | 5. 代码优化器 123 | 124 | 而目标代码生成则由后端完成。 125 | 126 | 在 词法分析、语法分析和语义分析阶段，编译器会创建和维护一个重要的数据结构，用于跟踪变量的语义，即它会存储有关的信息和名称的绑定信息等，叫做 符号表（`Symbol Table`）。在中间代码生成和目标代码生成过程中会使用它。 127 | 128 | 传统的基于遍历的编译器架构大概就是这样。 129 | 130 | ### 按需驱动的编译器架构 131 | 132 | Rust 编译器执行过程： 133 | 134 | - `rustc` 命令执行编译 135 | - `rustc_driver` 来解析命令行参数，相关编译配置被记录于 `rustc_interface::Config` 136 | - `rustc_lexer` 用于词法解析，将源代码文本输出为 词条流 (`Token Stream `) 137 | - `rustc_parse` 为编译过程下一阶段做准备。包含了词法分析的一部分，通过 内置的 [` StringBuffer`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/lexer/struct.StringReader.html) 结构体对文本字符串进行验证，以及将字符串进行符号（Symbol）化。 符号化是一种叫做 [`String interning`](https://en.wikipedia.org/wiki/String_interning) 的技术，将字符串的值存储一份不可变的副本。 138 | - `rustc_parse` 另一部分就是语法解析，使用递归下降（自顶向下）方法进行语法分析，将 词条流转换为 抽象语法树（`AST`）。入口点是 [`rustc_parse::parser::Parser`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/parser/struct.Parser.html) 结构体的 [`Parser::parse_crate_mod()`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/parser/struct.Parser.html#method.parse_crate_mod)和[`Parser::parse_mod()`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/parser/struct.Parser.html#method.parse_mod) 关联方法。外部模块解析入口点是[`rustc_expand::module::parse_external_mod`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_expand/module/fn.parse_external_mod.html)。宏解析器入口点是[`Parser::parse_nonterminal()`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/parser/struct.Parser.html#method.parse_nonterminal)。 139 | - 宏展开、`AST`验证、名称解析，以及 early lint 发生在编译过程的词法分析和语法分析阶段。 140 | - 此后，将 [`AST `转为` HIR`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/index.html)， 使用` HIR` 进行 类型推断](https://rustc-dev-guide.rust-lang.org/type-inference.html)（自动检测表达式类型的过程）、[特质求解](https://rustc-dev-guide.rust-lang.org/traits/resolution.html)（将` impl `与对特质的每个引用配对的过程）和[类型检查](https://rustc-dev-guide.rust-lang.org/type-checking.html)（转换类型的过程）。 141 | - 随后，[将](https://rustc-dev-guide.rust-lang.org/mir/index.html)`HIR`[降级到中级中级代表 (`MIR`)](https://rustc-dev-guide.rust-lang.org/mir/index.html)。在此过程中，也构建了 `THIR`，这是一个更加脱糖的` HIR`。`THIR (Typed HIR)` 用于模式和穷举检查。转换成` MIR` 也比` HIR` 更方便。 142 | - `MIR` 用于[借用检查](https://rustc-dev-guide.rust-lang.org/borrow_check.html)，它基本上是一个控制流图 (`CFG`)。此外 ， `MIR` 还用于 优化、增量编译、Unsafe Rust UB 检查等。 143 | - 最后，进行 代码生成 （`Codegen`）。 将 `MIR` 转换为 `LLVM IR`，然后将` LLVM IR `传递给` LLVM` 生成目标机器代码。 144 | 145 | 另一件需要注意的事情是编译器中的许多值都是`intern` 的。这是一种性能和内存优化，我们在称为`Arena`的特殊分配器中分配值。 146 | 147 | 在 Rust 编译器中，上面说的过程主要步骤都被组织成一堆相互调用的查询。 148 | 149 | Rust 编译器使用的是 查询系统（`Query System`），而非大多数编译原理教科书那种遍历式编译器（基于遍历 的编译器架构 ）。 Rust 使用查询系统是为了实现 增量编译功能，即按需编译。 150 | 151 | Rust 编译器最初并不是基于查询系统实现的，所以现在整个编译器还在改造为查询系统过程中，上面的整个编译过程都将被改造为基于查询系统。但是截至到 2021年 11月，目前仅是在` HIR` 到` LLVM IR` 这个过程是基于查询的。 152 | 153 | ### 编译器源码结构 154 | 155 | Rust 语言项目本身由三个主要目录组成： 156 | 157 | - `compiler/`，包含源代码`rustc`。它由许多 `crate` 组成，这些 `crate` 共同构成了编译器。 158 | - `library/`，包含标准库 ( `core`, `alloc`, `std`, `proc_macro`, `test`) 以及 Rust 运行时 ( `backtrace`, `rtstartup`, `lang_start`)。 159 | - `src/` ，包含 `rustdoc`、`clippy`、`cargo`、构建系统、语言文档等的源代码。 160 | 161 | 该`compiler/`包装箱所有名称以`rustc_*`。这些是大约 50 个相互依存的`crate`的集合，大小不等。还有`rustc` `crate` 是实际的二进制文件（即 `main`函数）；除了调用`rustc_driver` `crate`之外，它实际上并没有做任何事情。 162 | 163 | Rust 编译器之所以区分这么多 `crate` ，主要是以下两个因素考虑： 164 | 165 | 1. 便于组织代码。编译器是一个巨大的代码库，拆分为多个 `crate`，更利于组织。 166 | 2. 加速编译时间。多个 `crate` 有利于增量和并行编译。 167 | 168 | 但是因为 查询系统是在 `rustc_middle` 中定义的，而其他很多 `crate` 都依赖于它，而它又很大，导致编译时间很长。但是将其拆分的工作又没那么简单。 169 | 170 | 整个编译器 依赖树的顶部是[`rustc_interface`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/index.html)和 [`rustc_driver`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/index.html) crate。[`rustc_interface`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/index.html)是围绕查询系统的未稳定包装器，有助于驱动编译的各个阶段。 171 | 172 | ### 查询： 按需驱动编译 173 | 174 | 什么叫查询？ 比如有一个查询叫 `type_of(def_id)`，只要给定某个`Item` 的 `def-id` （标识符定义的索引值 `rustc_middle/src/hir/def_id.rs` ），就可以得到该` Item `的类型。查询执行是被缓存的，这也是增量编译的机制。 175 | 176 | ```rust 177 | let ty = tcx.type_of(some_def_id); 178 | ``` 179 | 180 | 但是，如果查询 不在缓存中，则编译器将尝试找到合适的**提供程序(provider)**。提供程序是一个已定义并链接到编译器某处的函数，该函数包含用于计算查询结果的代码。 181 | 182 | 由 Rust 编译器的查询系统还衍生出一个通用的按需增量计算框架 [Salsa](https://github.com/salsa-rs/salsa)。你可以通过 [`Salsa BOOK`](https://salsa-rs.github.io/salsa/about_salsa.html) 进一步了解查询系统工作机制。 183 | 184 | ## 源码阅读：名称解析组件 `rustc_resolve` 185 | 186 | 第一期 源码阅读 的内容聚焦在 `rustc_resolve` 库，它和 名称解析 相关。 187 | 188 | 经过前面关于 Rust 编译器架构背景相关了解，我们知道， `rustc_resolve` 名称解析是发生在 语法分析阶段，为生成最终 抽象语法树而服务，所以，这个库并没有使用到 查询系统。 189 | 190 | 这也是源码阅读第一期指定这个库的原因吧，不会上来就涉及相对比较复杂的查询系统。 191 | 192 | `crate` 的模块在这里构建，宏的路径、模块导入、表达式、类型、模式、标签（`label`）和生命周期 都是在这里解析的 193 | 194 | 类型相关的名称解析（方法、字段、关联项）发生在`rustc_typeck` 上。 195 | 196 | ### Rust 中的名称解析 197 | 198 | 经过查阅名称解析相关的资料，了解到 Rust 编译器在 2016 年引入 [RFC 1560](https://github.com/rust-lang/rfcs/blob/master/text/1560-name-resolution.md) 来改进名称解析的处理过程。 199 | 200 | 在这之前，名称解析在编译器的早期被处理，在 AST 降级到 HIR 之后。AST 会被遍历三遍，第一遍用于构建 `简化图（reduce_graph）`，第二遍用于解析名称，第三遍来检查未使用的名称。简化图是程序中所有定义和导入的记录。 201 | 202 | RFC 1560 将名称解析分成两个阶段：第一个阶段是与宏展开同时发生，并且会解析导入，来定义一个作用域范围内名称到定义的映射。第二阶段是从整个映射中根据一个名称来查找定义。这样做的目的是解耦。 203 | 204 | 当前 RFC 1560 已经被实现，在宏扩展期间不会做 全名解析，只解析导入和宏。当整个 AST 被构建以后，才会做全名解析，以便解析整个 crate 中所有的名称。 205 | 206 | 来看一个示例： 207 | 208 | ```rust 209 | 210 | #![allow(unused)] 211 | fn main() { 212 | type x = u32; 213 | let x: x = 1; 214 | let y: x = 2; 215 | } 216 | 217 | ``` 218 | 219 | 上面代码是可以合法编译的。其中 `x` 即是类型的命名，也是一个变量的命名。 Rust 如何进行名称解析来让两个同名的标识符共存呢？ 220 | 221 | 因为 Rust 有不同的命名空间。不同类型的符号存在于不同的命名空间中，比如类型和变量不会发生冲突。每个命名空间都会有自己的独立的 `rib` (编译器内部引入的抽象作用域概念，比如 let绑定、花括号定义范围、宏定义范围等都是一个 rib )栈。 222 | 223 | 接下来，我们现在来采用官方建议的三段阅读方法来阅读这个库的源码。 224 | 225 | ### rustc_resolve 的整体模块结构 226 | 227 | 包括在阅读 `rustc_resolve` 这个库的时候，我先从其文档着手。一个`crate` 的文档可以非常清晰的展现出这个 `crate` 的整体结构。 228 | 229 | [https://doc.rust-lang.org/stable/nightly-rustc/rustc_resolve/index.html](https://doc.rust-lang.org/stable/nightly-rustc/rustc_resolve/index.html) 230 | 231 | #### 模块 232 | 233 | - [`build_reduced_graph`](https://doc.rust-lang.org/stable/nightly-rustc/rustc_resolve/build_reduced_graph/index.html) 从宏中获取 AST 片段后，此模块中的代码有助于将该片段集成到已经部分构建的模块结构中。 234 | - [`check_unused`](https://doc.rust-lang.org/stable/nightly-rustc/rustc_resolve/check_unused/index.html)，顾名思义，检测 unused 结构体、枚举和函数 235 | - [`def_collector`](https://doc.rust-lang.org/stable/nightly-rustc/rustc_resolve/def_collector/index.html)， 给 AST 的节点创建 DefId（定义标识ID） 236 | - [`diagnostics`](https://doc.rust-lang.org/stable/nightly-rustc/rustc_resolve/diagnostics/index.html)，失败时候的诊断信息 237 | - [`imports`](https://doc.rust-lang.org/stable/nightly-rustc/rustc_resolve/imports/index.html)，一揽子和解析 导入 相关的方法和结构 238 | - [`late`](https://doc.rust-lang.org/stable/nightly-rustc/rustc_resolve/late/index.html)，“后期求解（late resolution）” 是除 导入 和 宏之前大多数名称求解的过程。它在 crate 完全展开并且模块结构完全构建时运行。所以，它只是遍历crate 并解析所有表达式、类型等。为什么没有对应的 `early`，因为它被分散到 `build_reduced_graph.rs`，`macros.rs`和`imports.rs` 中。 239 | - [`macros`](https://doc.rust-lang.org/stable/nightly-rustc/rustc_resolve/macros/index.html)， 一揽子和 解析 宏 相关的方法和结构 240 | 241 | #### 结构体 242 | 243 | 错误类型 244 | 245 | - `AmbiguityError`，歧义错误 246 | - `BindingError`， 绑定错误 247 | - `PrivacyError`，可见性错误 248 | - `UseError`， use 错误 249 | 250 | 数据类型 251 | 252 | - `DeriveData`， Derive 相关数据 253 | - `ExpandHasher` ，展开 Hasher 254 | - `ModuleData`，模块树某个节点的数据 255 | - `ExternPreludeEnty` ，处理 Extern、Prelude 相关 256 | - `NameBinding`， 记录可能是私有的值、类型或模块定义 257 | - `UsePlacementFinder`，use 相关 258 | 259 | 命名空间和作用域 260 | 261 | - `PerNS`，每个命名空间的单独结构，辅助类型 262 | - `ParentScope`， 记录scope 访问者的起点 263 | - `Segment`，path 段最小呈现 264 | 265 | 解析器相关 266 | 267 | - `Resolver` 主要的解析器类型 268 | - `ResolverArenas`，为 crate其他部分提供内存，Arena 模型 269 | 270 | #### 枚举 271 | 272 | 这里就不罗列了，和结构体分类类似的一些枚举类型。 273 | 274 | #### Traits 275 | 276 | - [`ToNameBinding`](https://doc.rust-lang.org/stable/nightly-rustc/rustc_resolve/trait.ToNameBinding.html)，用来转换areans 引用为 NameBinding 引用 277 | 278 | #### 函数 279 | 280 | 一些辅助函数 281 | 282 | #### 类型别名 283 | 284 | 记录了一些类型别名 285 | 286 | #### 依赖crate 287 | 288 | 在 `rustc_resolve` 的 `Cargo.toml` 中可以看到一些依赖 `crate`: 289 | 290 | - `rustc_ast `， 该库中定义了 Rust 内部用的 AST 数据结构 291 | - `rustc_arean`，编译器内部全局内存池，使用它来分配内存，被分配的内存生命周期为 `'tcx` 292 | - `rustc_middle`，Rust 编译器的 main 库，包含了其他 库中使用的通用类型定义 293 | - `rustc_attr`，和编译器内建属性相关 294 | - `rustc_data_structures`，定义了很多 编译器内部使用的数据结构，包括一些并行编译需要的线程安全的数据结构 295 | - `rustc_errors`，定义了 编译器常用的报告错误的实用工具 296 | - `rustc_expand`，用于宏展开。 297 | - `rustc_feature`，定义了编译器中的 features gate 298 | - `rustc_hir`，定义了 HIR 相关数据类型 299 | - `rustc_index`， 对 `usize`的一个 NewType 包装，用于编译器内部索引 300 | - `rustc_metadata`，关于 Rust 静态库、动态库相关的一些链接元信息 301 | - `rustc_query_system`，Rust 查询系统 302 | - `rustc_session`，编译器编译过程中错误处理和内建lint相关 303 | - `rustc_span`，定义源代码位置相关的数据类型，也包括宏卫生相关信息。 304 | 305 | 以上只是列出一些主要的依赖。截止今天（2021.11.13），看到 名称解析库也加入了 查询系统。 306 | 307 | 接下来我们看一下 [`lib.rs`](https://github.com/rust-lang/rust/blob/master/compiler/rustc_resolve/src/lib.rs) 中定义了什么内容。 308 | 309 | 看得出来，在 `lib.rs` 中定义的基本都是 上面文档中展示的那些 用于在名称解析过程中使用的结构体或枚举类型。 310 | 311 | 这里罗列有几个比较容易懂的类型： 312 | 313 | **`Scope` 枚举类型:** 314 | 315 | ```rust 316 | // 用于查找名称的特定作用域，只能用于 early 解析过程，比如 导入 和 宏，而不能用于 late 解析。 317 | /// A specific scope in which a name can be looked up. 318 | /// This enum is currently used only for early resolution (imports and macros), 319 | /// but not for late resolution yet. 320 | #[derive(Clone, Copy)] 321 | enum Scope<'a> { 322 | DeriveHelpers(LocalExpnId), 323 | DeriveHelpersCompat, 324 | MacroRules(MacroRulesScopeRef<'a>), 325 | CrateRoot, 326 | // The node ID is for reporting the `PROC_MACRO_DERIVE_RESOLUTION_FALLBACK` 327 | // lint if it should be reported. 328 | Module(Module<'a>, Option), 329 | RegisteredAttrs, 330 | MacroUsePrelude, 331 | BuiltinAttrs, 332 | ExternPrelude, 333 | ToolPrelude, 334 | StdLibPrelude, 335 | BuiltinTypes, 336 | } 337 | ``` 338 | 339 | **`Segment` 结构体：** 340 | 341 | ```rust 342 | // path 的最小化呈现 ： 段 343 | // 比如 std::sync::Arc 这就是一个 path，其中 `::` 分开的就是段 344 | /// A minimal representation of a path segment. We use this in resolve because we synthesize 'path 345 | /// segments' which don't have the rest of an AST or HIR `PathSegment`. 346 | #[derive(Clone, Copy, Debug)] 347 | pub struct Segment { 348 | ident: Ident, 349 | id: Option, 350 | /// Signals whether this `PathSegment` has generic arguments. Used to avoid providing 351 | /// nonsensical suggestions. 352 | has_generic_args: bool, 353 | } 354 | ``` 355 | 356 | `**LexicalScopeBinding` 枚举：** 357 | 358 | ```rust 359 | // Item，整个块中可见 360 | // Res，只在定义的地方可见 361 | /// An intermediate resolution result. 362 | /// 363 | /// This refers to the thing referred by a name. The difference between `Res` and `Item` is that 364 | /// items are visible in their whole block, while `Res`es only from the place they are defined 365 | /// forward. 366 | #[derive(Debug)] 367 | enum LexicalScopeBinding<'a> { 368 | Item(&'a NameBinding<'a>), 369 | Res(Res), 370 | } 371 | ``` 372 | 373 | **`ModuleKind` 枚举** 374 | 375 | ```rust 376 | #[derive(Debug)] 377 | enum ModuleKind { 378 | // 比较有意思的是，我们发现内部模块的分类，还有一种是 匿名模块，一个 block 就是一个匿名模块 379 | /// An anonymous module; e.g., just a block. 380 | /// 381 | /// ``` 382 | /// fn main() { 383 | /// fn f() {} // (1) 384 | /// { // This is an anonymous module 385 | /// f(); // This resolves to (2) as we are inside the block. 386 | /// fn f() {} // (2) 387 | /// } 388 | /// f(); // Resolves to (1) 389 | /// } 390 | /// ``` 391 | Block(NodeId), 392 | /// Any module with a name. 393 | /// 394 | /// This could be: 395 | /// 396 | /// * A normal module – either `mod from_file;` or `mod from_block { }` – 397 | /// or the crate root (which is conceptually a top-level module). 398 | /// Note that the crate root's [name][Self::name] will be [`kw::Empty`]. 399 | /// * A trait or an enum (it implicitly contains associated types, methods and variant 400 | /// constructors). 401 | Def(DefKind, DefId, Symbol), 402 | } 403 | ``` 404 | 405 | `AmbiguityKind` 枚举 406 | 407 | ```rust 408 | // 歧义类型 409 | #[derive(Clone, Copy, PartialEq, Debug)] 410 | enum AmbiguityKind { 411 | Import, // 多个导入源 412 | BuiltinAttr, // 内建属性命名冲突 413 | DeriveHelper, // derive 内命名冲突 414 | MacroRulesVsModularized, // 宏名和非宏名冲突 415 | GlobVsOuter, 416 | GlobVsGlob, 417 | GlobVsExpanded, 418 | MoreExpandedVsOuter, 419 | } 420 | ``` 421 | 422 | **`Resolver<'a'>` 结构体** 423 | 424 | ```rust 425 | // 这是主要用于解析的结构体，这是一个很大的结构体，包含了名称解析过程需要的数据信息 426 | /// The main resolver class. 427 | /// 428 | /// This is the visitor that walks the whole crate. 429 | pub struct Resolver<'a> { 430 | session: &'a Session, 431 | 432 | definitions: Definitions, 433 | 434 | graph_root: Module<'a>, 435 | 436 | prelude: Option>, 437 | extern_prelude: FxHashMap>, 438 | // ... 439 | } 440 | 441 | // 用于 Resolver 库里的内存分配 442 | pub struct ResolverArenas<'a> { 443 | modules: TypedArena>, 444 | local_modules: RefCell>>, 445 | imports: TypedArena>, 446 | name_resolutions: TypedArena>>, 447 | ast_paths: TypedArena, 448 | dropless: DroplessArena, 449 | } 450 | 451 | ``` 452 | 453 | 接下来就是一些函数，包括 `report_errors` / `report_conflict` / `add_suggestion_for_rename_of_use` 等一些用于编译器诊断信息等函数。 454 | 455 | ### 聚焦于问题 456 | 457 | 我们现在对 名称解析 功能相关背景有了足够且系统的认识。让我们来看一些代码细节。 458 | 459 | 根据官方阅读源码的建议，现在这一步，应该是 `Deep` ，聚焦于某些感兴趣或有疑问的函数。 460 | 461 | 我对 Rustc 如何检查未使用变量比较感兴趣，就让我们聚焦 `check_unused.rs` 模块中的相关功能。 462 | 463 | 该模块注释中写道，检查未使用的导入主要分为三步： 464 | 465 | 第一步： `UnusedImportCheckVisitor` 来遍历 AST 以查找`UseTree`内所有未使用的导入，并且记录它们的 `use`分组和 `NodeId` 信息。 466 | 467 | 对于 unused trait 方法，则在 `rustc_typeck/check_unused.rs` 中检查。 468 | 469 | 我们从前面背景资料已经知道，`check_unused` 发生在第三遍 AST 遍历，经过前面两遍遍历，已经构建出了 `UseTree`，只需要走查 `Unused NodeId` 即可： 470 | 471 | ```rust 472 | struct UnusedImport<'a> { 473 | use_tree: &'a ast::UseTree, 474 | use_tree_id: ast::NodeId, 475 | item_span: Span, 476 | unused: FxHashSet, // 内部的 快速 HashSet 存储 NodeId 信息 477 | } 478 | 479 | impl<'a> UnusedImport<'a> { 480 | fn add(&mut self, id: ast::NodeId) { 481 | self.unused.insert(id); 482 | } 483 | } 484 | 485 | struct UnusedImportCheckVisitor<'a, 'b> { 486 | r: &'a mut Resolver<'b>, 487 | /// All the (so far) unused imports, grouped path list 488 | unused_imports: NodeMap>, 489 | base_use_tree: Option<&'a ast::UseTree>, 490 | base_id: ast::NodeId, 491 | item_span: Span, 492 | } 493 | 494 | impl<'a, 'b> UnusedImportCheckVisitor<'a, 'b> { 495 | // We have information about whether `use` (import) items are actually 496 | // used now. If an import is not used at all, we signal a lint error. 497 | fn check_import(&mut self, id: ast::NodeId) { 498 | /* do something */ 499 | } 500 | 501 | } 502 | 503 | // 实现 rustc_ast 中 定义 的 Visitor trait， 这是访问者模式在 Rust 编译器中的应用 504 | // Visitor trait 中定义了 AST Node的访问钩子方法，这样具体的访问者就可以实现 Visitor 的特定方法来进行具体的访问 505 | // 这里具体的访问者就是 UnusedImportCheckVisitor 506 | impl<'a, 'b> Visitor<'a> for UnusedImportCheckVisitor<'a, 'b> { 507 | fn visit_item(&mut self, item: &'a ast::Item) { /* do something */ } 508 | fn visit_use_tree(&mut self, use_tree: &'a ast::UseTree, id: ast::NodeId, nested: bool) { /* do something */ } 509 | } 510 | ``` 511 | 512 | 513 | 514 | 第二步： `calc_unused_spans` ，遍历上一步收集的 `NodeId` 关联的 `Span ` 515 | 516 | ```rust 517 | fn calc_unused_spans( 518 | unused_import: &UnusedImport<'_>, 519 | use_tree: &ast::UseTree, 520 | use_tree_id: ast::NodeId, 521 | ) -> UnusedSpanResult { 522 | /* do something */ 523 | match use_tree.kind { 524 | ast::UseTreeKind::Simple(..) | ast::UseTreeKind::Glob => { /* do something */ } 525 | ast::UseTreeKind::Nested(ref nested) => {/* do something */} 526 | } 527 | /* do something */ 528 | } 529 | ``` 530 | 531 | 第三步： `check_crate`，根据生成的数据发出诊断信息 532 | 533 | ```rust 534 | impl Resolver<'_> { 535 | // 为 Resolver 实现 check_unused 方法 536 | crate fn check_unused(&mut self, krate: &ast::Crate) { 537 | /* do something */ 538 | // 检查导入源 539 | for import in self.potentially_unused_imports.iter() { 540 | match import.kind { 541 | ImportKind::MacroUse => { /* do something */ } 542 | ImportKind::ExternCrate { .. } => { /* do something */ } 543 | } 544 | } 545 | let mut visitor = UnusedImportCheckVisitor { 546 | r: self, 547 | unused_imports: Default::default(), 548 | base_use_tree: None, 549 | base_id: ast::DUMMY_NODE_ID, 550 | item_span: DUMMY_SP, 551 | }; 552 | visit::walk_crate(&mut visitor, krate); 553 | for unused in visitor.unused_imports.values() { 554 | let mut fixes = Vec::new(); // 为 cargo fix 记录 555 | /* do something */ 556 | // 计算 unused 位置信息 557 | let mut spans = match calc_unused_spans(unused, unused.use_tree, unused.use_tree_id) { 558 | /* do something */ 559 | } 560 | /* do something */ 561 | // 发出诊断消息 562 | visitor.r.lint_buffer.buffer_lint_with_diagnostic( 563 | UNUSED_IMPORTS, 564 | unused.use_tree_id, 565 | ms, 566 | &msg, 567 | BuiltinLintDiagnostics::UnusedImports(fix_msg.into(), fixes), 568 | ); 569 | } 570 | } 571 | } 572 | ``` 573 | 574 | 通过阅读这部分代码，我们大概了解了 `rustc_resolve` 库的组织结构： 575 | 576 | - `lib.rs` 中定义主要的 `Resolver`相关类型和方法 577 | - 在不同的 `Resolver` 功能模块中实现具体的 解析方法，比如 `check_unused` 578 | 579 | ### 回到整体模块 580 | 581 | 然后，我们再回到整体模块中来了解其他部分的代码。 582 | 583 | 我们知道第一遍 AST 遍历会构建 简化图 （ `reduced graph`），那么这个过程肯定是对应于[ `build_reduced_graph.rs` ](https://github.com/rust-lang/rust/blob/master/compiler/rustc_resolve/src/build_reduced_graph.rs) 模块。 584 | 585 | 我们可以看到该模块引入了 `rustc_ast` / `rustc_expand`/ `rustc_data_structures::sync::Lrc (等价于 Arc)/ rustc_hir::def_id` 等相关组件，可想而知，它是和宏展开相关，并且也支持并行编译。 586 | 587 | ```rust 588 | impl<'a> Resolver<'a> { 589 | crate fn define(&mut self, parent: Module<'a>, ident: Ident, ns: Namespace, def: T) where 590 | T: ToNameBinding<'a>, 591 | { 592 | let binding = def.to_name_binding(self.arenas); 593 | let key = self.new_key(ident, ns); 594 | // https://github.com/rust-lang/rust/blob/master/compiler/rustc_resolve/src/imports.rs#L490 595 | // try_define 定义于 imports 模块，解析导入的时候用于检查绑定的名称 596 | if let Err(old_binding) = self.try_define(parent, key, binding) { 597 | // 如果命名有冲突，这里会调用 report_conflict 来发出错误报告 598 | self.report_conflict(parent, ident, ns, old_binding, &binding); 599 | } 600 | } 601 | fn get_nearest_non_block_module(&mut self, mut def_id: DefId) -> Module<'a> {/* do something */} 602 | crate fn get_module(&mut self, def_id: DefId) -> Option> {/* do something */} 603 | crate fn expn_def_scope(&mut self, expn_id: ExpnId) -> Module<'a> {/* do something */} 604 | crate fn build_reduced_graph( 605 | &mut self, 606 | fragment: &AstFragment, 607 | parent_scope: ParentScope<'a>, 608 | ) -> MacroRulesScopeRef<'a> {/* do something */} 609 | 610 | } 611 | ``` 612 | 613 | 实现了构建 简化图需要的 `Resolver` 相关方法。 具体细节我们就不再看了，了解整体流程即可。 614 | 615 | ## 总结 616 | 617 | 官方的源码阅读俱乐部活动，旨在带动 Rust 编译器贡献者踊跃去对 Rust 编译器做贡献。但是具体的源码阅读过程，猜测不会太详细，还有很多东西是需要私下去了解的。 618 | 619 | 本文作为一次源码阅读学习的记录分享，旨在抛砖引玉，如果文中有发现错误，欢迎反馈。 620 | 621 | 622 | ## 参考链接 623 | 624 | - [https://github.com/rust-lang/rustc-reading-club](https://github.com/rust-lang/rustc-reading-club) 625 | - [https://www.manning.com/books/the-programmers-brain](https://www.manning.com/books/the-programmers-brain) 626 | - [代码阅读着色工具（代码要使用永久链接）](https://annotate.code-reading.org/#/) 627 | - [https://courses.cs.washington.edu/courses/cse401/07au/CSE401-07sem.pdf](https://courses.cs.washington.edu/courses/cse401/07au/CSE401-07sem.pdf) 628 | - [https://github.com/rust-lang/rfcs/blob/master/text/1560-name-resolution.md](https://github.com/rust-lang/rfcs/blob/master/text/1560-name-resolution.md) --------------------------------------------------------------------------------