rustc-dev-guide：给编译器贡献者的活地图，但别指望它替你读代码
该项目围绕「A guide to how rustc works and how to contribute to it. This is a collaborative effort to build a guide that explains how rustc works.」构建，适用于实际场景的开源实践，提供可复用的工具链与集成方式。
秒懂
- 它是什么？
- rustc-dev-guide 是 rust-lang 官方维护的 rustc 贡献者指南，面向想深入编译器内部的人。它用 mdBook 组织，内容覆盖从词法分析到代码生成的各个阶段，但它的价值取决于你是否愿意主动对照源码。
- 适合谁用？
- rustc-dev-guide 适合两类人：一是刚接触 rustc 并想参与贡献的开发者，它能把庞大的编译器拆成可消化的章节，告诉你从哪里开始读代码；二是需要快速了解某个具体阶段（如借用检查或 MIR）的资深用户，它能帮你定位到对应源码文件。不适合的人包括：想学 Rust 语言本身的人，这本指南默认你已经有 Rust 编程经验；以及想找一份完整、实时更新的编译器文档的人，它明确承认自己还有很多工作没完成。
- 能商用吗？
- 可以。Apache-2.0 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 2 天前。
- 用什么语言写的？
- 主要是 HTML（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决的是「看不懂 rustc」这个具体问题
rustc 是 Rust 编译器的实现，代码量巨大，新贡献者往往不知道从哪个文件开始读。rustc-dev-guide 的目标就是解决这个定位问题。它由 rust-lang 组织维护，面向两类人：刚入门的贡献者，以及想在某个陌生模块里找方向的资深开发者。指南不教 Rust 语法，也不讲编译器理论，它只讲 rustc 本身：各个阶段如何衔接、关键数据结构在哪、调试工具怎么用。它和 std-dev-guide 是分开的，后者专门讲标准库的开发，两者互不重叠。
内容组织：按编译流程走，而不是按代码目录走
指南的结构是一本标准的 mdBook，目录在 src/SUMMARY.md 里，每个页面对应 src/ 下的一个 Markdown 文件。它不按 rustc 的源码目录来组织，而是按编译流程来组织：从词法分析、语法分析、类型检查、借用检查，到 MIR 生成、优化、代码生成。每一章会解释该阶段做什么，并指向 rustc 源码中的具体文件。这种组织方式对新手友好，因为你可以顺着数据流读下去，而不是在几十个 crate 之间乱撞。但这也意味着它不会覆盖所有源码细节，README 里明白写着「guide is useful today, but it has a lot of work still to go」，所以别把它当成完整文档。
构建与本地预览：mdbook 三件套
想本地看这份指南，需要安装 mdbook 以及两个配套插件：mdbook-linkcheck2 和 mdbook-mermaid。安装命令是 cargo install --locked mdbook mdbook-linkcheck2 mdbook-mermaid。然后在仓库根目录运行 mdbook serve --open 就能在浏览器里打开本地站点，改动 Markdown 文件会自动重新编译。如果想做一次性构建，用 mdbook build。链接检查默认不跑，需要设置环境变量 ENABLE_LINKCHECK=1 再执行 mdbook serve，CI 里是默认开启的。整个流程很轻，只要你有 Rust 工具链，十分钟内就能跑起来。
编辑指南的门槛比改编译器低得多
这份指南的贡献策略很有意思。它明确说，如果你不懂编译器怎么工作，那也没关系，社区会安排你和一个懂代码的人结对，你负责把学到的东西写下来。这意味着写文档的门槛被刻意降低了，目的是鼓励更多人参与。仓库里还提供了几个辅助工具，放在 ci/ 目录下。检查语义换行用 cargo run --manifest-path ci/sembr/Cargo.toml src，检查日期标注用 cargo run --manifest-path ci/date-check/Cargo.toml .，链接检查用 mdbook-linkcheck2 --standalone。这些工具都有对应的 cargo test 可以跑。所以如果你发现某章写得不清楚，可以直接提 PR，审查政策也相对宽松，具体政策链接指向 forge.rust-lang.org。
一个真实的坑：忘记加进 SUMMARY.md 的页面不会显示
mdBook 的机制是只渲染 SUMMARY.md 里列出的页面。指南里专门用 NOTE 强调：如果你新增了一个 Markdown 文件但没把它加进 SUMMARY.md，它就不会出现在最终站点上。这对贡献者是个常见的失误点，但也反映了整个项目对构建流程的依赖。另一个限制是链接检查默认关闭，本地预览时不会报错，只有 CI 里才会跑。所以本地看起来一切正常，push 上去后 CI 可能因为一个失效链接而失败。这不算 bug，但确实是个容易踩的坑，尤其是第一次贡献的人。
维护成本与同步机制：和 rustc 主仓库绑定
这份指南不是独立存在的，它和 rust-lang/rust 主仓库通过 josh 子树同步。同步工具是 rustc-josh-sync，具体操作步骤写在 src/external-repos.md 里。这意味着指南的内容更新是跟着 rustc 的变更走的，而不是完全独立的。维护成本因此分成两部分：一是常规的文档编辑，二是与主仓库的同步。对普通读者来说，这个机制意味着指南可能滞后于编译器的最新变化，尤其是那些快速演进的模块。如果你在指南里看到某个 API 已经不存在了，那很可能就是同步还没跟上。
许可证与适用边界：Apache-2.0，但别指望它替代源码
项目采用 Apache-2.0 许可证，这是 rust-lang 仓库的常见选择，允许自由使用和修改，但如果你要分发修改版本，需要注意保留版权声明。从适用性角度看，这份指南最适合那些已经决定要读 rustc 源码的人。它不能替代阅读源码本身，也不能替代调试实践。它更像一张地图，告诉你哪里有路，但路况如何还得自己走。对于只想了解 Rust 语言设计的人，这份指南的性价比很低，因为它的每一章都预设了你要去改编译器。如果你需要的是标准库开发指南，应该去看 std-dev-guide，两者定位完全不同。
编辑结论
rustc-dev-guide 适合两类人：一是刚接触 rustc 并想参与贡献的开发者，它能把庞大的编译器拆成可消化的章节，告诉你从哪里开始读代码；二是需要快速了解某个具体阶段（如借用检查或 MIR）的资深用户，它能帮你定位到对应源码文件。不适合的人包括：想学 Rust 语言本身的人，这本指南默认你已经有 Rust 编程经验；以及想找一份完整、实时更新的编译器文档的人，它明确承认自己还有很多工作没完成。采用前先验证两件事：一是你读的章节是否与当前 rustc 版本匹配，因为编译器变动频繁，指南可能滞后；二是你是否有能力对照源码阅读，指南是路线图，不是替代品。最终判断：这是一份由社区协作、以贡献者为导向的活文档，它的价值不取决于内容量，而取决于你愿不愿意在阅读时打开 rustc 的源码。
社区笔记