Rust 编译器快速上手从克隆仓库到构建、测试 rustc 的完整实战指南【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust本指南面向想要参与 rustc 开发或自建编译器的开发者以rustc-dev-guide中的 Quickstart 为主线完整演示从克隆rust-lang/rust仓库、生成bootstrap.toml配置、调用x构建工具链到链接 rustup 工具链、运行 UI 测试套件的全流程。读完本文你将掌握./x setup、./x build、./x check、./x test等核心命令的用法与加速技巧并理解 stage0/stage1/stage2 分级构建背后的原理可以立即上手对编译器进行修改与验证。一、准备工作获取 rustc 源码构建 Rust 编译器的第一步是获取源码。主仓库同时包含编译器rustc、标准库core、alloc、test、proc_macro等以及一系列工具rustdoc、bootstrap 基础设施等因此一次克隆即可获得完整的开发环境git clone https://github.com/rust-lang/rust.git cd rust注意在 Windows 上杀毒软件的全盘扫描会明显拖慢大仓库的 Git 与构建命令。如果遇到这种情况可考虑仅将 Rust 检出目录加入 Windows 安全中心的排除列表避免过宽的排除范围。克隆方式的选择由于仓库体积庞大、历史记录完整在较慢的网络下完整克隆耗时长、占磁盘大。rustc-dev-guide提供了两种替代方案Partial clone推荐只拉取当前文件内容历史内容在需要时按需自动获取。所有 Git 命令照常可用代价是访问未加载的历史节点时需要联网git clone --filterblob:none https://github.com/rust-lang/rust.git cd rustShallow clone浅克隆使用--depth N只保留最近 N 次提交--depth 1即只取main分支的最新一次提交适合浏览源码或快速构建git clone --depth 1 https://github.com/rust-lang/rust.git cd rust但浅克隆会限制部分 Git 命令git bisect和git blame依赖完整提交历史因此如果打算参与编译器开发并贡献代码建议使用完整克隆或 partial clone。另外请预留足够的磁盘空间构建编译器需要相对较大的存储文档建议至少预留 10~15 GB而完整的多阶段构建尤其超过 stage 1 时可能占用接近 100 GB 的空间。二、认识 x构建 rust 仓库的统一入口构建 rustc 时不直接使用cargo而是使用一个名为 x 的包装器通过./x调用。x 的底层是仓库中的 bootstrap 构建系统位于 src/bootstrap它负责构建文档、运行测试、构建编译器和标准库。./x是 bootstrap 的推荐入口但根据操作系统与 Shell 的不同还有多种等价形式参见 how-to-build-and-run.md./x subcommand [flags] # Unix shell 或配置好的 Windows PowerShell ./x.ps1 subcommand [flags] # Windows NuShell x.py subcommand [flags] # Windows 命令提示符需 .py 关联 Python python x.py subcommand [flags] # 手动调用 Python ./x.py subcommand [flags] # 仅有 python3 且 sh 不支持 local 的环境如 Solaris仓库根目录下实际存在 x、x.ps1、x.py 三个入口文件对应上述调用方式。在 Windows PowerShell 中直接运行./x可能报错File ... x.ps1 cannot be loaded because running scripts is disabled on this system可执行以下命令允许运行本地脚本Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser如果想要更方便地在仓库任意子目录中运行x还可以安装系统级的x二进制源码位于 src/tools/x它会自动查找合适的 Python 版本不依赖当前 Shellcargo install --locked --path src/tools/x三、生成构建配置./x setup 与 bootstrap.toml克隆完成后需要为构建创建配置文件。运行./x setup会执行初始化并生成一份带合理默认值的bootstrap.toml./x setup交互式设置会询问你选择哪种默认配置profile常见选项对应 src/bootstrap/defaults 下的模板文件compilerbootstrap.compiler.toml面向编译器贡献者启用debug-logging、debug-assertions、incremental、backtrace-on-ice等开发友好选项并从 CI 下载预编译 LLVMdownload-ci-llvm truelibrarybootstrap.library.toml面向标准库与文档贡献者test-stage 1、bench-stage 1避免构建编译器本身toolsbootstrap.tools.toml面向 rustdoc、cargo、clippy 等工具贡献者download-rustc if-unchanged且默认test-stage 2distbootstrap.dist.toml面向从源码安装的用户与发行版维护者默认完整的 stage 2 构建build-stage 2、extended true。例如 compiler profile 会设置[rust]下的incremental true显著加快增量重建、lto off以约 20% 运行时性能为代价换取更快的构建、frame-pointers true便于性能分析等这些配置共同定义了面向开发、而非面向发布的构建形态。也可以手写bootstrap.toml仓库根目录的 bootstrap.example.toml 列出了全部可用配置项及其说明src/bootstrap/defaults 则给出了常见的组合。如果你已经构建过 rustc 后修改了与 LLVM 相关的配置可能需要执行./x clean --all才能让后续配置变更生效注意./x clean不会触发 LLVM 重建。多配置管理config extensions不同任务可能需要切换不同的 bootstrap 配置。与其手工复制粘贴配置值bootstrap.toml支持通过include引入配置扩展且扩展可以递归嵌套# cross.toml [build] build x86_64-unknown-linux-gnu host [i686-unknown-linux-gnu] target [i686-unknown-linux-gnu] [llvm] download-ci-llvm false [target.x86_64-unknown-linux-gnu] llvm-config /path/to/llvm-19/bin/llvm-config# bootstrap.toml include [cross.toml]注意include的覆盖逻辑为从右到左——include [a.toml, b.toml]中b.toml覆盖a.toml且父级扩展总是覆盖内层扩展。四、构建编译器./x build 与 ./x check配置就绪后即可开始构建。最常用的黄金命令是构建标准库同时也会用 stage0 编译器构建 rustc再用新构建的 stage1 编译器构建标准库并组装出可用的 stage1 sysroot./x build library该命令的完整执行链条为用 stage0 编译器下载的预发布编译器和 stage0 标准库构建 rustc用刚构建出的 stage1 编译器构建library标准库组装出包含 stage1 编译器与 stage1 标准库的 stage1 sysroot。最终产物stage1 编译器 用它构建的库就是编译普通 Rust 程序所需的一切除非程序使用#![no_std]或#![no_core]。快速入门文档 quickstart.md 中推荐的做法是./x setup ./x build./x build会构建编译器、标准库以及少量工具如果只想快速验证代码能否编译可以改用./x check。两类命令都支持指定组件或路径作为参数例如./x check compiler只检查编译器部分。常用 x 命令速查命令适用场景./x check快速检查大部分代码能否编译重构类型更改时首选rust-analyzer 可自动执行./x build构建rustc、std和rustdoc./x test运行全部测试./x fmt格式化所有代码x还支持compiler、library与src/tools目录的各种路径后缀简写例如x test tidy等价于x test src/tools/tidyx build std等价于x build library/std。构建特定组件如果只改标准库无需构建全部默认组件./x build --stage 1 library选择 library profile 时--stage 1是默认值可省略。构建某个工具则直接给出其路径./x build src/tools/cargo交叉编译需要构建支持其他目标的编译器时向x build传入任意数量的--target标志./x build --target x86_64-unknown-linux-gnu,wasm32-wasip1若要让编译器能构建包含 proc macro 或 build script 的 crate必须显式包含宿主平台目标。也可以在bootstrap.toml的[build]段中固化目标列表[build] target [x86_64-unknown-linux-gnu, wasm32-wasip1]避免 std 重复构建--keep-stage-std 1构建 stage1 标准库往往是整个流程的瓶颈。当修改不改变标准库的编译方式例如仅修改错误信息文案时可以跳过 std 的重编./x build library --keep-stage-std1该标志会假设旧的标准库可以复用——因为编译器代码没有被改动时这通常是成立的。但要注意如果修改的是影响元数据编码的部分例如 rlib 中类型编码、MIR 的定义等复用的 std 可能与新编译器不兼容导致奇怪的 ICE 或 panic。遇到此类异常时去掉--keep-stage-std1重新构建即可。测试同样可以使用该技巧./x test tests/ui --keep-stage-std1清理构建目录需要完全重新开始时运行./x clean虽然rm -rf build也能达到目的但会丢失已编译的 LLVM 缓存重建 LLVM 即使在较快的机器上也非常耗时因此通常建议使用./x clean。五、链接 rustup 工具链并使用自建编译器构建完成后build目录下会生成一系列产物。推荐用 rustup 将产物链接为自定义工具链以便随时调用rustup toolchain link stage1 build/host/stage1特别注意如果使用./x setup tools默认 stage 会是 2 而非 1链接命令需相应调整rustup toolchain link stage2 build/host/stage2之后即可通过stage1选择器使用自建编译器rustc stage1 testfile.rs运行rustc stage1 -vV可以验证版本号以-dev结尾表明来自本地构建$ rustc stage1 -vV rustc 1.48.0-dev binary: rustc commit-hash: unknown commit-date: unknown host: x86_64-unknown-linux-gnu release: 1.48.0-dev LLVM version: 11.0rustup 工具链指向的是build目录中的产物因此每次运行x build或x test后工具链会自动指向最新构建结果。需要注意的是自建工具链不包含 cargorustup 会按 nightly → beta → stable 的顺序回退使用已安装工具链的 cargo如果需要不稳定的 cargo 标志请先rustup install nightlyrust-analyzer 与 IntelliJ Rust 插件依赖rust-analyzer-proc-macro-srv组件处理 proc macro若要通过rustup override set stage1在项目中使用自定义工具链可额外构建./x build proc-macro-srv-cli六、运行测试./x test 与 UI 测试套件完成修改后用./x test运行测试套件。但完整测试套件很慢通常并非所需对编译器修改而言./x test tests/ui才是最常用的命令——它运行所有 UI 测试对每个特定测试文件调用编译器并核对编译器输出。./x test tests/uiUI 测试位于 tests/ui本质上是一个编译器输出快照测试体系compiletest 用rustc编译测试文件将输出与同目录下的.stderr/.stdout文件比对。测试文件内还会用//~ ERROR之类的注释标注预期的诊断信息。当你修改了编译器导致输出变化后需要更新.stderr快照./x test tests/ui --bless--bless会用新输出自动重写.stderr/.stdout文件之后务必人工检查快照内容是否符合预期——这正是 UI 测试保证诊断输出稳定性的核心机制。其他常用的测试命令还包括./x test library/std # 运行 std 的单元与集成测试 ./x test tests/ui/const-generics # 运行 ui 套件下某子目录的测试 ./x test tests/ui/const-generics/const-types.rs # 运行单个测试文件加快测试循环增量编译./x test tests/ui --incremental --test-args issue-1234可加快后续重建也可以在bootstrap.toml中固化[rust] incremental true注意增量编译会占用更多磁盘空间磁盘紧张时应定期检查build目录体积。精细优化将optimize false会让编译器慢到无法测试若想缩短重建周期可只对高频重建的 crate 关闭优化在根目录 Cargo.toml 中[profile.release.package.rustc_mir_build] opt-level 0 [profile.release.package.rustc_driver] opt-level 0rust-analyzer 自动检查配置完成后rust-analyzer 可在每次保存文件时自动运行./x check详见下一节。七、提升开发效率的常用工作流重构期多用 ./x check进行类型化重构如重命名方法、修改函数签名时./x check比./x build快得多足够验证编译器能否构建。可以持续执行./x check积累重构提交稍后再集中运行测试并借助git bisect精确定位出问题的提交。这样留下的细粒度提交既全部可构建、又便于审查。安装 pre-push 钩子CI 会要求代码通过tidy仓库内置的代码质量检查工具。可以安装 Git 钩子让每次 push 自动运行./x test tidy若钩子失败运行./x test tidy --bless并提交修复。仓库已提供现成钩子脚本 src/etc/pre-push.sh复制到.git/hooks并去掉.sh后缀即可./x setup交互流程中也提供安装钩子的选项。配置 rust-analyzer./x setup会询问是否为 VSCode、Vim、Emacs、Helix 或 Zed 设置编辑器配置也可通过./x setup editor单独触发VSCode生成 .vscode/settings.json 风格的推荐配置若希望保存时手动触发检查可改用 Build Task如 .vscode/tasks.json 同目录的配置思路将./x check注册为构建任务Emacs选择emacs生成.dir-locals.el推荐配置见 src/etc/rust_analyzer_eglot.elHelix选择helix生成languages.toml推荐配置见 src/etc/rust_analyzer_helix.tomlZed选择zed生成.zed/settings.json推荐配置见 src/etc/rust_analyzer_zed.json。rust-analyzer 默认运行cargo check与rustfmt对 rustc 仓库应覆盖为./x check与 stage0 rustfmt。若只关注编译器部分可将检查命令限制为x check compiler --json-output以节省时间可用x check --help --verbose查看可选部分。另外rust-analyzer 默认使用独立构建目录如需共享build目录以节省磁盘可以覆盖生成配置但这会导致命令行构建与后台检查互相锁定构建目录官方并不推荐。使用 nightly 工具链bootstrap 的部分环节如 rustfmt使用固定的 nightly 版本。要让仓库内的cargo fmt正常工作cd rustc 仓库路径 rustup override set nightly注意这并不会让你能用 cargo 直接构建 rustc编译器与标准库的开发仍须通过x此操作只是让cargo fmt等工具可用。如需固定版本可参考 src/stage0 中的 pinned nightly 版本。并行开发多个分支git worktree在不同分支并行开发时构建产物与增量缓存会互相覆盖。与其维护多个克隆重复存储 Git 元数据不如使用 Git worktree——多个工作树共享同一 Git 数据库git worktree add ../rust2 # 新建工作树 git worktree add -b my-feature ../rust2 main # 基于 main 创建新分支的工作树唯一需要注意的是子模块不会共享仍会被多次克隆。Shell 补全./x的自动补全脚本位于 src/etc/completions覆盖 Bash、Zsh、Fish、PowerShell。例如 Bash/Zsh/Fish 可执行source ./src/etc/completions/x.extensionPowerShell 执行 .\src\etc\completions\x.ps1将其加入 Shell 启动脚本即可自动加载。八、常见问题速查问题解决办法Windows PowerShell 报脚本执行被禁用Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser修改 LLVM 相关配置后构建不生效执行./x clean --all不会触发 LLVM 重建--keep-stage-std1构建出奇怪的 ICE去掉该标志重新构建磁盘空间不足清理build/目录、独立的build-rust-analyzer/目录或用rustup toolchain list卸载不用的工具链使用download-rustc true时./x test library/std失败临时以./x test library/std --set rust.download-rustcfalse关闭download-rustc或在bootstrap.toml中设置rust.download-rustc false代价是需要构建 stage1 编译器相关修复正在推进中结语从git clone、./x setup生成配置到./x build产出可用的 stage1 工具链、rustup toolchain link接入系统、./x test tests/ui --bless维护诊断快照这一套流程就是 rustc 贡献者最核心的日常工作闭环。深入阅读 how-to-build-and-run.md 与 suggested.md 可以获得更多细节如果仍有疑问可以在 Zulip 的t-compiler/help频道向社区求助。现在你可以放心地对编译器做出第一处修改了。【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考