rustc-dev-guide

这是一项合作努力，旨在构建一个解释 rustc 工作原理的指南。该指南的目的是帮助新贡献者了解 rustc，同时也帮助更有经验的开发者了解编译器中他们以前没有接触过的新部分。

你可以在这里阅读指南的最新版本。

你可能也会发现编译器本身的 rustdocs 很有用。请注意，这些文档并非intended 作为指南；建议你搜索你需要的文档，而不是从头到尾阅读。

关于开发标准库的文档，请参见 std-dev-guide。

为指南做贡献

这个指南现在已经很有用了，但还有很多工作要做。

如果你想帮助改进这个指南，我们非常欢迎你的参与！你可以在问题跟踪器上找到大量的问题。只需在你想处理的问题上发表评论，以确保我们不会意外地重复工作。如果你认为有什么遗漏的内容，请为此开启一个新的问题！

**总的来说，如果你不了解编译器是如何工作的，这不是问题！**在这种情况下，我们会安排一些时间让你与了解代码的人交流，或者与你一起研究。然后你可以开始写下你所学到的内容。

通常，在写关于编译器代码特定部分的内容时，我们建议你链接到 rustc rustdocs 的相关部分。

构建说明

要构建本地静态 HTML 网站，请使用以下命令安装 mdbook：

> cargo install mdbook mdbook-linkcheck mdbook-toc mdbook-mermaid

然后在仓库根目录执行以下命令：

> mdbook build --open

构建文件位于 book/html 目录中。

链接验证

我们使用 mdbook-linkcheck 来验证文档中包含的 URL。当你按照上面的说明进行构建时，linkcheck 会自动运行。

目录

我们使用 mdbook-toc 为长章节自动生成目录。你可以通过在想要插入目录的位置包含 <!-- toc --> 标记来调用预处理器。

如何修复工具状态失败

注意：目前，由于偶发性失败，我们不再跟踪 rustc-dev-guide 的工具状态，但我们保留这些说明以备将来再次使用。

1. 你会收到工具状态提交的通知。例如：https://github.com/rust-lang-nursery/rust-toolstate/commit/8ffa0e4c30ac9ba8546b7046e5c4ccc2b96ebdd4

2. 提交包含导致破坏的 PR 链接。例如：https://github.com/rust-lang/rust/pull/64321

3. 如果你进入该 PR 的线程，会有一个来自 bors 的帖子，其中包含 CI 状态的链接：https://github.com/rust-lang/rust/pull/64321#issuecomment-529763807

4. 点击 check-actions 链接进入该构建的 Actions 页面

5. 该构建会有大约 10 亿个不同的作业。它们是针对不同的配置和平台的。rustc-dev-guide 构建仅在 Linux x86_64-gnu-tools 作业上运行。所以在列表中点击该作业，它大约在列表的 60% 处。

6. 点击作业中的 Run build 步骤以获取该步骤的控制台日志。

7. 点击日志并使用 Ctrl-F 在日志中打开搜索框

8. 搜索 rustc-dev-guide。这会带你到检查链接的位置。通常在日志的第 11000 行左右。

9. 查看日志中该点附近的链接

10. 修复 rustc-dev-guide 中的这些链接（通过在 rustc-dev-guide 仓库中提交 PR）

11. 在 rust-lang/rust 仓库中提交 PR 以更新 src/docs/rustc-dev-guide 中的 rustc-dev-guide git 子模块。 要提交 PR，以下步骤很有用：

# 假设你已经克隆了 rust-lang/rust 仓库并且在正确的目录中
git submodule update --remote src/doc/rustc-dev-guide
git add -u
git commit -m "Update rustc-dev-guide"
# 注意，你可以使用 -i，它是 --incremental 的简写，在以下命令中
./x test --incremental src/doc/rustc-dev-guide # 这是可选的，应该会成功
# 在 rust-lang/rust 中打开一个 PR

12. 等待 PR 合并

大功告成！