Rust 编译器引导构建Bootstrapping全解析从 Stage 0 到 Stage 3 的分阶段编译机制【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust导读本文基于 rustc-dev-guide 的《What Bootstrapping does》章节系统讲解 rust-lang/rust 仓库如何通过用旧编译器编译新编译器的分阶段Stage 0/1/2/3引导流程完成rustc与标准库的自举构建。你将掌握各阶段的职责与产物、./x默认 stage 与--stage N覆写规则、--cfg bootstrap与RUSTC_BOOTSTRAP1的稳定性破解机制、sysroot 与rustc_private的装载原理以及为 bootstrap 传递 rustc/cargo 标志的完整环境变量体系从而在日常开发中选对构建与测试命令、看懂构建日志。什么是引导构建Bootstrapping[Bootstrapping]自举指使用一个编译器去编译它自身更准确地说是用一个较旧的编译器去编译同一编译器的新版本。这引出一个先有鸡还是先有蛋的悖论最初的编译器从何而来它必然是用另一种语言写成的——Rust 的早期编译器用 OCaml 编写但早已废弃。如今构建现代rustc的唯一方式就是用一个稍微不那么新的版本去编译它。Rust 的 bootstrap 构建系统正是这样运作的它下载当前 beta 版本的rustc然后用它去编译仓库里的新编译器源码。相关背景可参阅 引导构建引言 与 bootstrap 的 Step 机制。Stages of bootstrapping引导构建的阶段总体概览编译rustc是分阶段进行的共四个阶段Stage 0预编译的编译器与标准库默认是近期 beta 版rustc及其动态库由 bootstrap 自动下载Stage 1用更早的编译器stage0编译当前源码得到的编译器Stage 2真正当前的编译器用 stage1 编译器 树内 std 重新编译得到Stage 3同结果测试可选用于 sanity check。下图为引导阶段顺序示意改编自 Jynn Nelson 在 RustConf 2022 的 bootstrapping 演讲图中A、B、C、D表示引导顺序蓝色节点为下载所得黄色节点由stage0编译器构建绿色节点由stage1编译器构建图中版本号为示例1.86.0-beta.1是当前下载的 stage0 版本1.87.0-dev表示从当前源码构建的-dev版本。实际版本以仓库 src/version 与bootstrap.toml中配置的 stage0 为准。Stage 0预编译的编译器stage0 编译器默认是最近的 beta 版rustc及其关联动态库bootstrap 会替你下载也可在bootstrap.toml中配置改变 stage0 的来源。预编译的 stage0 编译器 stage0 std 只被用来编译 src/bootstrap 和 compiler/rustc 这两部分。这里涉及两个概念编译器及其依赖集与target/object 库std与rustc。两者都被分阶段但节奏错开——这正是后续stage N std与stage N-1 std区分的根源。Stage 1用较早的编译器编译当前源码rustc 源码随后用 stage0 编译器编译产出stage1 编译器。Stage 2真正当前的编译器再用stage1 编译器 树内 std重新构建编译器产出stage2 编译器。stage2 正是rustup与所有其他安装方式分发的编译器。为什么必须这样绕一圈因为 stage1 编译器本身是由预编译的 stage0 编译器与 std 构建的并非由你工作目录中的源码直接产出。stage0 编译器生成的 ABI 可能与 stage1 编译器生成的 ABI 不一致这对动态库、测试以及使用rustc_private的工具会带来问题。注意proc_macrocrate 通过一层 C FFIproc_macro::bridge规避了这个问题因此它可以与 stage1 一起使用。stage2 的代价是构建时间非常长你必须先用旧编译器构建新编译器再用它构建一遍自身。因此日常开发通常只需要--stage 1参见 构建编译器。Stage 3同结果测试可选为 sanity check 新编译器可以用 stage2 编译器再构建一遍库结果应当与之前完全相同——除非有什么东西坏了。构建各阶段./x的默认 stage脚本 ./x 会贴心地为每个子命令挑选你最可能想要的 stage。以下是常用x命令及其默认 stage命令默认 stagecheck--stage 1clippy--stage 1doc--stage 1build--stage 1test--stage 1dist--stage 2install--stage 2bench--stage 2你随时可以通过显式传入--stage N覆盖默认值。stage 的约定--stage N表示运行 stage N 编译器stageN/rustcstage N artifact 是由 stage N 编译器产出的构建产物stage N1 编译器由 stage N artifacts组装而成这一过程称为uplifting提升。引导构建的复杂性nightly 特性与稳定性构建系统使用当前 beta 编译器构建 stage1 引导编译器因此编译器源码在特性进入 beta 之前不能使用某些新特性否则 beta 编译器不支持它们。但另一方面编译器内建函数intrinsics 和内部特性又必须使用此外编译器还大量使用nightly特性#![feature(...)]。如何解决这个矛盾两种方法--cfg bootstrap构建系统在用 stage0 构建时设置--cfg bootstrap于是源码可以写cfg(not(bootstrap))让某些特性只在 stage1 及之后构建时启用。这适用于刚刚稳定的特性——它们用 stage0 构建时还需要#![feature(...)]而 stage1 之后不再需要。该配置在 src/bootstrap/src/core/builder/cargo.rs 中随 cargo 调用注入。RUSTC_BOOTSTRAP1这个特殊环境变量意味着打破 Rust 的稳定性保证允许在非 nightly 编译器上使用#![feature(...)]。在 src/bootstrap/src/core/builder/cargo.rs 与 src/bootstrap/src/core/builder/mod.rs 中均可看到 bootstrap 为编译命令设置RUSTC_BOOTSTRAP1。除非是在引导编译器否则永远不应该设置RUSTC_BOOTSTRAP1。深入理解各 stage 的细节构建产物Build artifacts任何能用./x构建的东西都是构建产物包括但不限于二进制如stage0-rustc/rustc-main共享对象如stage0-sysroot/rustlib/libstd-6fae108520cf72fe.sorlib 文件如stage0-sysroot/rustlib/libstd-6fae108520cf72fe.rlibrustdoc 生成的 HTML 文件如doc/std。正确的用法示例./x test tests/ui构建 stage1 编译器并对其运行compiletest。如果你在开发编译器这通常就是你想要的测试命令。./x test --stage 0 library/std不构建rustc源码直接用 stage0 构建 std 再测试其产物。如果你在开发标准库这通常是你想要的命令。./x build --stage 0用 stage0rustc构建。./x doc --stage 1用 stage0rustdoc生成文档。常见错误用法不要这样做./x test --stage 0 tests/ui这是在beta 编译器上跑测试并未构建rustc源码没有意义。应该用test tests/ui它从源码构建 stage1。./x test --stage 0 compiler/rustc只构建编译器但不运行任何测试——它实际执行的是cargo test -p rustc而 cargo 并不理解 Rust 的测试协议。直接用test不带参数即可。./x build --stage 0 compiler/rustc构建编译器但不构建libstd甚至libcore。大多数时候你应该用./x build library它允许编译程序而无需定义 lang items。构建 vs 运行简言之stage 0 用 stage0 编译器创建 stage0 artifacts这些 artifacts 之后会被 uplift 为 stage1 编译器。除 stage 0 外每个阶段执行两大步骤std由 stage N 编译器编译该std链接到 stage N 编译器构建的所有程序包括 stage N artifacts即 stage N1 编译器。这其实很直观把 stage N artifacts 看作用 stage N 编译器构建的另一个程序——build --stage N compiler/rustc就是把 stage N artifacts 链接到 stage N 编译器构建出的std。阶段与std的关系注意存在两份std链接到stageN/rustc的库由 stage N-1 构建stage N-1std用stageN/rustc编译程序时使用的库由 stage N 构建stage Nstd。stage Nstd对 stage N 编译器而言几乎是必不可少的没有它你只能用#![no_core]编译程序——这没什么用两者必须不同是因为它们不一定 ABI 兼容nightly 上可能有新的布局优化、MIR变更或其他 Rust 元数据变化而这些在 beta 中还不存在。这正是--keep-stage 1 library/std存在的意义由于大多数编译器改动并不会改变 ABI一旦你在 stage1 产出了一份std就可以放心复用它。标志--keep-stage指示构建脚本假定之前的编译结果仍然有效直接把旧 artifacts 复制到合适位置跳过cargo调用参见 src/bootstrap/src/core/build_steps/compile.rs 中keep-stage的处理逻辑。如果 ABI 变了例如你改了编码进rlib的元数据、或MIR的定义请移除该标志重新构建否则可能出现诡异的 ICE 或 panic。交叉编译 rustc交叉编译指编译将在另一种架构上运行的代码例如在 x86 机器上构建 ARM 版 rustc。交叉编译时构建 stage2std的方式有所不同若HOST与TARGET相同./x会直接复用 stage1std作为 stage2std——这成立是因为 stage1std由 stage1 编译器编译而该编译器使用的正是你当前检出的源码因此它应当与 stage2rustc会编译出的std完全一致从而 ABI 兼容但交叉编译时stage1std只能在 host 上运行因此stage2 编译器必须为目标架构重新编译std这解释了为何构建表中 stage2 只构建非 host 的stdtargets。什么是 sysroot用cargo构建项目时依赖产物通常放在target/debug/deps但那里只有 cargo 知道的依赖没有标准库。std、proc_macro从哪来它们来自sysroot——编译器在运行时加载构建产物的若干目录的根。sysroot 不只存放标准库还包括一切需要在运行时加载的东西libstd/libtest/libproc_macro等库使用rustc_private时的编译器 crates 本身树内in-tree总是存在树外则需用rustup安装rustc-devLLVM 项目的共享对象libLLVM.so树内由源码构建或从 CI 下载树外需用rustup安装llvm-tools-preview。以上都是编译器的运行时依赖可以用rustc --print sysroot查看$ ls $(rustc --print sysroot)/lib libchalk_derive-0685d79833dc9b2b.so libstd-25c6acf8063a3802.so libLLVM-11-rust-1.50.0-nightly.so libtest-57470d2aa8f7aa83.so librustc_driver-4f0cc9f50e53f0ba.so libtracing_attributes-e4be92c35ab2a33b.so librustc_macros-5f0ec4a119c6ac86.so rustlib标准库还有自己的运行时依赖位于lib/rustlib/而非直接的lib/$ ls $(rustc --print sysroot)/lib/rustlib/x86_64-unknown-linux-gnu/lib | head -n 5 libaddr2line-6c8e02b8fedc1e5f.rlib libadler-9ef2480568df55af.rlib liballoc-9c4002b5f79ba0e1.rlib libcfg_if-512eb53291f6de7e.rlib libcompiler_builtins-ef2408da76957905.rliblib/rustlib/包含hashbrown、cfg_if这类并非标准库公共 API、但用于实现它的库。注意lib/rustlib/属于链接器的搜索路径而lib永远不会被加入搜索路径。-Z force-unstable-if-unmarked既然lib/rustlib/在搜索路径中就必须小心哪些 crates 被放进去。除标准库外所有 crates 都以-Z force-unstable-if-unmarked构建意味着必须使用#![feature(rustc_private)]才能加载它们标准库始终可用不受此限。该标志有多种用途核心是强制正确的 crates 被标记为unstable。它最初引入是为了让 rustc 与标准库能链接 crates.io 上没有使用staged_api的任意 cratesrustc 也依赖它把所有 crates 统一标记为带rustc_private的unstable免去逐 crate 手工标记。bootstrap 脚本会自动对所有 rustc 与标准库 crate 应用该标志——因为编译器及其全部依赖会随 sysroot 分发到所有用户。该标志的效果将未自行标记stable/unstable的 crate 标记为带rustc_private的 unstable允许这些 crates无需任何属性即可访问其他 forced-unstable crates。正常情况下 crate 需要#![feature(rustc_private)]才能使用其他unstablecrates但那样 crates.io 上的 crate 就无法访问自己的依赖它没有feature(rustc_private)而所有东西都用-Z force-unstable-if-unmarked编译。不使用该标志的代码例如链接 rustc 本身的Miri、clippy应包含#![feature(rustc_private)]crate 属性来访问这些 forced-unstable crates。向 bootstrap 调用的命令传递标志./x允许你向 bootstrap 过程中的rustc和cargo传递分阶段的标志RUSTFLAGS_BOOTSTRAP作为RUSTFLAGS传给 bootstrap 阶段stage0RUSTFLAGS_NOT_BOOTSTRAP传给构建后续阶段 artifacts 时RUSTFLAGS也可以但会影响bootstrap自身的构建因此很少想用它MAGIC_EXTRA_RUSTFLAGS绕过cargo缓存把标志传给 rustc 而不重新编译所有依赖。RUSTDOCFLAGS/RUSTDOCFLAGS_BOOTSTRAP/RUSTDOCFLAGS_NOT_BOOTSTRAP与RUSTFLAGS系列类似但作用于rustdoc在 src/bootstrap/src/core/builder/cargo.rs 中通过cargo.rustdocflags.env(...)注入CARGOFLAGS向 cargo 本身传参CARGOFLAGS_BOOTSTRAP与CARGOFLAGS_NOT_BOOTSTRAP与RUSTFLAGS_BOOTSTRAP机制类似--test-args把参数透传给测试运行器。对tests/ui是compiletest对单元测试与文档测试是libtest运行器。大多数测试运行器支持--help可以用来查看其接受的选项。引导过程中的环境变量引导过程中使用了一批编译器内部环境变量。如果你想运行一个中间版本的rustc有时需要手工设置其中一些否则会得到如下报错thread main panicked at RUSTC_STAGE was not set: NotPresent, library/core/src/result.rs:1165:5如果./stageN/bin/rustc报环境变量相关的错误通常意味着出了大问题——比如你在尝试编译rustc、std或其他依赖环境变量的东西。在极少见的情况下你确实需要这样调用rustc可以给x命令加-vvv让 bootstrap shim 打印全部env变量。另外bootstrap 使用 cc-rs crate其文档说明如何通过环境变量配置 C 编译器与 C 标志。解读构建命令的 stdout以x build --dry-run为例构建输出大致如下下述小节将逐行解读Building stage0 library artifacts (x86_64-unknown-linux-gnu - x86_64-unknown-linux-gnu) Copying stage0 library from stage0 (x86_64-unknown-linux-gnu - x86_64-unknown-linux-gnu / x86_64-unknown-linux-gnu) Building stage0 compiler artifacts (x86_64-unknown-linux-gnu - x86_64-unknown-linux-gnu) Copying stage0 rustc from stage0 (x86_64-unknown-linux-gnu - x86_64-unknown-linux-gnu / x86_64-unknown-linux-gnu) Assembling stage1 compiler (x86_64-unknown-linux-gnu) Building stage1 library artifacts (x86_64-unknown-linux-gnu - x86_64-unknown-linux-gnu) Copying stage1 library from stage1 (x86_64-unknown-linux-gnu - x86_64-unknown-linux-gnu / x86_64-unknown-linux-gnu) Building stage1 tool rust-analyzer-proc-macro-srv (x86_64-unknown-linux-gnu) Building rustdoc for stage1 (x86_64-unknown-linux-gnu)Building stage0 {std,compiler} artifacts这些步骤用提供的通常已下载的编译器把本地 Rust 源码编译成可用的库Copying stage0 {std,rustc}把库与编译器产物从cargo复制到stage0-sysroot/lib/rustlib/{target-triple}/libAssembling stage1 compiler把 buildingstage0... artifacts 中构建的库复制到 stage1 编译器的lib/目录。这些是编译器自身运行所需的 host 库并非新编译器生成的 artifacts 所用该步骤同时把生成的rustc与rustdoc二进制复制到build/$HOST/stage/bin。关键结论stage1/bin/rustc是一个由 stage0预编译编译器与 std 构建的、功能完整的编译器要使用完全由源码 树内编译器与 std 构建的编译器你需要构建stage2 编译器它由 stage1 树内编译器与 std 编译。与 bootstrap 实现细节的衔接本文聚焦用户可见的引导构建语义若要深入 bootstrap 的内部实现——例如核心抽象Steptrait、Builder::ensure的步骤编排、./x→x.py→bootstrap.py→src/bootstrap/src/bin/main.rs的入口链——请继续阅读 bootstrap 如何运作 与 bootstrap 内部文档另有 调试 bootstrap 介绍--verbose日志与BOOTSTRAP_TRACING结构化追踪。结合 如何构建与运行编译器典型的日常工作流是./x setup生成 bootstrap.toml →./x build librarystage1 编译器 stage1 std 组装出可用 sysroot→ 用./x test tests/ui跑编译器测试需要完整编译器时再以./x build --stage 2 rustc构建 stage2并用rustup toolchain link stage1 build/host/stage1注册本地 toolchain 后以rustc stage1调用。【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考