rustc_driver_impl：Rust 编译器 rustc 的“main 函数”与编译流水线编排

2026-09-06 21:03:06作者：秋阔奎Evelyn

本文基于 Rust 编译器仓库中的 rustc_driver_impl 文档展开，系统讲解 rustc 驱动层的定位、启动流程与编译流水线编排机制。读完本文，你将能够理解 rustc 命令从进程启动到产出可执行文件的关键调用链，掌握 run_compiler、Callbacks、--print、ICE（Internal Compiler Error）处理等核心机制在源码中的落点，并可据此将 rustc 作为库驱动自己的工具链（如 rustdoc、自定义 Lint 工具）。

定位：driver 就是 rustc 的“main”函数

rustc_driver_impl/README.md 对驱动 crate 的官方描述非常凝练：

The driver crate is effectively the "main" function for the rust compiler. It orchestrates the compilation process and "knits together" the code from the other crates within rustc. This crate itself does not contain any of the "main logic" of the compiler (though it does have some code related to pretty printing or other minor compiler options).

这句话点明了 driver 的三重身份：

入口：rustc 二进制的 main 函数就位于本 crate；
编排者：按正确顺序调用其余各 crate（rustc_parse、rustc_resolve、rustc_hir_analysis、rustc_codegen_ssa 等）的能力，把编译各阶段“编织”成一条流水线；
薄壳：不含编译器的主体逻辑（类型检查、借用检查、代码生成都不在这里），只有少数周边功能，如 pretty printing（结构体美化打印）和次要的编译器选项处理。

仓库中还有一个配套的薄 crate compiler/rustc_driver/src/lib.rs，其全部源码只有一行重导出：

// This crate is intentionally empty and a re-export of `rustc_driver_impl` to allow the code in
// // `rustc_driver_impl` to be compiled in parallel with other crates.

#[doc(no_inline)]
pub use rustc_driver_impl::*;

也就是说，rustc_driver 只是 rustc_driver_impl 的 re-export 壳，目的是让 rustc_driver_impl 能在 rustc 自举（bootstrap）时与其他 crate 并行编译。日常阅读源码时应直接进入 compiler/rustc_driver_impl/src 目录。

crate 组织：入口与周边功能模块

compiler/rustc_driver_impl/src 下的模块划分清晰地对应了 README 中“main 函数 + 少量周边功能”的说法：

模块	职责
lib.rs	`main`、`run_compiler`、选项解析、`--print`、ICE 钩子等核心编排逻辑
args.rs	原始命令行参数读取与 `@argfile` 展开
pretty.rs	`-Zunpretty` 各模式（source/AST/HIR/MIR/THIR 等）的美化打印
print.rs	`safe_print!/safe_println!` 宏，避免打印失败导致 panic
diagnostics.rs	驱动层专用的诊断定义（ICE、`--explain`、`-Zls` 相关等）
highlighter.rs	诊断输出中的 Markdown 高亮着色
signal_handler.rs	SIGSEGV/SIGBUS/SIGILL 下的裸栈回溯（处理栈溢出等致命信号）
allocator.rs	可选的 jemalloc 全局分配器覆盖

依赖声明集中在 compiler/rustc_driver_impl/Cargo.toml，可以看到它几乎引用了 rustc 的每一个核心 crate（rustc_ast、rustc_hir、rustc_middle、rustc_mir_build、rustc_metadata、rustc_session、rustc_target、rustc_interface 等），这正是“编排者”角色的直接证据：它本身不实现算法，但必须能看到所有阶段的接口。Cargo.toml 还定义了若干 feature：check_only、llvm、llvm_offload、max_level_info、rustc_randomized_layouts 等，它们大多只是向 rustc_interface、rustc_log 等下游 crate 透传同名 feature，进一步印证 driver 的“透传编排”定位。

进程入口：`main()` 的启动序列

rustc 二进制的真正 main 在 compiler/rustc_driver_impl/src/lib.rs：

pub fn main() -> ExitCode {
    let start_time = Instant::now();
    let start_rss = get_resident_set_size();

    let early_dcx = EarlyDiagCtxt::new(ErrorOutputType::default());

    init_rustc_env_logger(&early_dcx);   // 1. 初始化 RUSTC_LOG 日志
    signal_handler::install();           // 2. 安装致命信号处理器
    let mut callbacks = TimePassesCallbacks::default();
    install_ice_hook(DEFAULT_BUG_REPORT_URL, |_| ());  // 3. 安装 ICE 钩子
    install_ctrlc_handler();             // 4. 安装 Ctrl+C 处理器

    let exit_code =
        catch_with_exit_code(|| run_compiler(&args::raw_args(&early_dcx), &mut callbacks));

    if let Some(format) = callbacks.time_passes {
        let end_rss = get_resident_set_size();
        print_time_passes_entry("total", start_time.elapsed(), start_rss, end_rss, format);
    }

    exit_code
}

这个启动序列有几个值得注意的设计点：

日志：init_rustc_env_logger 读取 RUSTC_LOG 环境变量初始化 tracing 日志（见 lib.rs 中 init_rustc_env_logger）。它存在的意义是让外部工具（如 rustdoc）无需“碰巧匹配”rustc 的 tracing 版本即可启用日志——注释中明确说明了这一点。
信号处理器：signal_handler.rs 只对 SIGILL、SIGBUS、SIGSEGV 三个“致命信号”安装 handler，用 sigaltstack 建立备用信号栈、SA_ONSTACK 标志，在信号上下文中通过裸 libc::write 直接往 stderr 写回溯（此时编译器可能已经栈溢出，不能用任何带分配、带同步的 API）。handler 还会检测回溯中的周期模式来识别递归导致的栈溢出，并给出 RUST_MIN_STACK=... 的调大建议。在不满足条件的平台（如 wasm），install() 是空实现，回退到 std 的默认信号处理。
Ctrl+C：install_ctrlc_handler 使用 ctrlc crate，收到信号后置位 rustc_const_eval::CTRL_C_RECEIVED 原子标志，给编译器 100ms 机会执行自定义清理逻辑，随后强制退出。
ICE 钩子：install_ice_hook（lib.rs）在用户未显式设置 RUST_BACKTRACE 时默认开启完整回溯；panic 发生时先调用默认钩子打印 panic 信息和栈回溯，再把完整记录追加写入 rustc-ice-<时间戳>-<pid>.txt 文件（路径由环境变量 RUSTC_ICE 或 -Zmetrics-dir 决定），最后调用 report_ice 输出带 bug 报告链接、版本、主机三元组、query 栈的标准 ICE 报告。

main 最后调用的 catch_with_exit_code 是一个对 rustc_errors::catch_fatal_errors 的包装（lib.rs），它把 Termination 状态转换为进程 ExitCode，保证“用户代码编译错误”和“编译器自身崩溃”都能映射到正确的退出码。

核心编排：`run_compiler` 的完整流程

驱动层最重要的函数是 run_compiler，它是 README 所说的“orchestrates the compilation process”的具体实现。按源码顺序，其流程可分为六段：

1. 参数展开与早期解析

pub fn run_compiler(at_args: &[String], callbacks: &mut (dyn Callbacks + Send)) {
    let mut default_early_dcx = EarlyDiagCtxt::new(ErrorOutputType::default());
    // Throw away the first argument, the name of the binary.
    let at_args = at_args.get(1..).unwrap_or_default();
    let args = args::arg_expand_all(&default_early_dcx, at_args);
    let (matches, help_only) = match handle_options(&default_early_dcx, &args) { ... };

先丢弃 argv[0]（注释特别提到：早期版本曾因先展开后去首参，允许用 @empty_file 作为 argv[0] 触发崩溃，现在的顺序规避了这一点）。
args.rs 中的 arg_expand_all 负责 @file 参数文件展开：@path 把文件内容按行拆分为独立参数；若启用 -Zshell-argfiles，则 @shell:path 使用 shlex 按 shell 语法解析（支持引号与转义）。由于 -Zshell-argfiles 本身会影响展开行为，Expander 内部还做了一次保守的“预解析”来提前发现该不稳定选项。
raw_args（args.rs）则负责把 env::args_os() 转成 Vec<String>，遇到非 Unicode 参数时通过早期诊断报错而不是 panic。
handle_options 用 getopts 按“编译器定义的全部选项”解析（此处不区分稳定性，先尽量解析成功），再由 nightly_options::check_nightly_options 做稳定性检查。函数注释详细解释了 rustc 选项的稳定性模型：稳定选项随处可用；不稳定选项要么位于 -Z 之后，要么需要 -Z unstable-options 解锁，且只有 nightly 通道才放行。解析阶段还会处理：-Wall（rustc 没有该标志，打印引导性帮助并退出）、-C passes=list、--version 等早退分支，以及一个易错项——-o 与值之间缺少空格且值疑似标志名（如把 -o3 写成 -o 3 的反面：-o3）时的友好警告。
帮助输出由 handle_help 按命令行中出现的位置排序处理：-h/--help（或空参数）、-Z help（打印全部 Z_OPTIONS）、-C help（打印全部 CG_OPTIONS）。注意 -W help 不在此处处理，因为它要等 Lint 工具（如 Clippy）注册完额外 lint 之后才能完整输出。

2. 输入、输出与 `--explain`

let sopts = config::build_session_options(&mut default_early_dcx, &matches);
let ice_file = ice_path_with_config(Some(&sopts.unstable_opts)).clone();

if let Some(ref code) = matches.opt_str("explain") {
    handle_explain(&default_early_dcx, code, sopts.color);
    return;
}

let input = make_input(&default_early_dcx, &matches.free);
let has_input = input.is_some();
let (odir, ofile) = make_output(&matches);

make_input 处理输入文件：无参数为 None（随后报“no input filename given”）；- 表示从 stdin 读取（非 UTF-8 输入直接早期致命退出）；同时出现多个文件则报错。它还在读取 stdin 时支持 UNSTABLE_RUSTDOC_TEST_PATH/UNSTABLE_RUSTDOC_TEST_LINE 环境变量，为 rustdoc 的 doctest 提供精确的源文件命名。
make_output 处理 -o（-o - 表示输出到 stdout）与 --out-dir。
--explain E0XXX 在创建 Session 之前就被短路处理：handle_explain 从 rustc_errors::codes 中查找错误码说明文档，终端环境用 pager（PAGER 环境变量，默认 less/Windows 下 more.com）分页显示，并尝试用 highlighter.rs 做 Markdown 彩色渲染，失败则逐级回退到纯文本。

3. 组装 `interface::Config` 并回调

let mut config = interface::Config {
    opts: sopts,
    crate_cfg: matches.opt_strs("cfg"),
    crate_check_cfg: matches.opt_strs("check-cfg"),
    input: input.unwrap_or(Input::File(PathBuf::new())),
    output_file: ofile,
    output_dir: odir,
    ice_file,
    ...
    make_codegen_backend: None,
    using_internal_features: &USING_INTERNAL_FEATURES,
};

callbacks.config(&mut config);

这里是外部工具接入的第一道钩子：Callbacks::config 允许在 Session 建立前修改配置（例如本 crate 自带的 TimePassesCallbacks 就在 config 回调里根据 -Ztime-passes 与 --print 的组合决定是否统计各 pass 耗时）。随后调用 rustc_interface::run_compiler，把真正“创建 Compiler、建立 Session、驱动查询”的职责移交给 rustc_interface crate。

4. 编译阶段流水线

interface::run_compiler 内部的闭包就是编译流水线的骨架，各阶段的顺序与早退条件如下（行号对应 lib.rs 中闭包体）：

-Whelp：必须等 lint 注册完成后才能打印完整 lint 列表，所以放在 Session 创建之后、其他处理之前（describe_lints 会分别列出内建与外部加载的 lint 和 lint 组）。
帮助/--print 早退：help_only 直接返回；print_crate_info 处理 --print=... 请求，返回 Compilation::Stop 时结束。
输入检查：!has_input 时 sess.dcx().fatal("no input filename given")。
-Zls：列出 .rmeta 文件元数据（对传入 .rs 源文件会给出针对 Cargo 用户的专门提示）。
-Zlink-only：process_rlink 直接反序列化 codegen 产物（rlink）并调用后端链接，跳过整个前端。
解析 crate 根：passes::parse(sess) 只解析 crate 根，子模块在后续展开阶段解析。
pretty printing：若给了 -Zunpretty，按模式打印后退出；需要 AST map 的模式（如 expanded 系列）会先进入 create_and_enter_global_ctxt 跑早期 lint 检查。
after_crate_root_parsing 回调：Callbacks 的第二道钩子，可决定是否停止编译。
命名解析 + 宏展开：create_and_enter_global_ctxt(compiler, krate, ...) 内先 tcx.resolver_for_lowering()，触发解析与展开，随后是 after_expansion 回调；接着写 dep-info、写 crate 接口文件（write_interface），若只要 --emit=dep-info 或开了 -Zno-analysis 则提前结束。
类型分析：tcx.ensure_ok().analysis(()) 触发全量分析查询（名字检查、类型推断、借用检查等）；-Zmetrics-dir 在此处 dump 不稳定特性使用指标；随后是 after_analysis 回调（三道 Callbacks 钩子齐备）。
MIR 输出：--emit=mir 时调用 pretty::emit_mir。
codegen：Linker::codegen_and_build_linker(tcx, codegen_backend) 生成目标代码并构建 linker。
链接：链接被刻意放在 compiler.enter() 作用域之外——源码注释解释：这样可以在链接前尽早释放 GlobalCtxt 中的 Queries 内存。

这条流水线同时解释了 Callbacks 这个 trait 的完整面貌（lib.rs）：

pub trait Callbacks {
    /// Called before creating the compiler instance
    fn config(&mut self, _config: &mut interface::Config) {}
    /// Called after parsing the crate root. ...
    fn after_crate_root_parsing(&mut self, _compiler: &interface::Compiler,
                                 _krate: &mut ast::Crate) -> Compilation { Compilation::Continue }
    /// Called after expansion. ...
    fn after_expansion<'tcx>(&mut self, _compiler: &interface::Compiler,
                              _tcx: TyCtxt<'tcx>) -> Compilation { Compilation::Continue }
    /// Called after analysis. ...
    fn after_analysis<'tcx>(&mut self, _compiler: &interface::Compiler,
                            _tcx: TyCtxt<'tcx>) -> Compilation { Compilation::Continue }
}

四个回调覆盖“配置期 / 解析后 / 展开后 / 分析后”四个插入点，返回值 Compilation::Stop | Continue 允许嵌入方在任意阶段截断编译——这正是 rustc_interface 文档所称“把 rustc 内部当库驱动”的典型用例。

5. `--print`：不编译也能输出的信息

print_crate_info 实现了 --print 的全部分支，每个分支对应一类“查编译器自身信息”的能力，这也是 driver 层“次要编译器选项”的代表：

目标信息：TargetList（全部内置 target 三元组）、HostTuple、Sysroot、TargetLibdir、TargetSpecJson（目标 spec 的 JSON）、AllTargetSpecsJson、TargetSpecJsonSchema；
crate 信息：FileNames（按 crate 类型推算产物文件名）、CrateName、CrateRootLintLevels（crate 根 lint 等级）、SupportedCrateTypes；
配置信息：Cfg（stable 通道自动过滤被 gate 的不稳定 cfg）、CheckCfg；
后端信息：RelocationModels、CodeModels、TlsModels、TargetCPUs、TargetFeatures、StackProtectorStrategies（经 codegen_backend.print 委托给后端）、CallingConventions（来自 rustc_abi）、BackendHasMnemonic、BackendHasZstd；
特殊分支：NativeStaticLibs 与 LinkArgs 在链接阶段打印，--print 只含它们时直接 Continue；DeploymentTarget 仅对 Apple 目标有效。

值得留意的是 print_crate_info 内部用一个局部 import 把 safe_print/safe_println 宏“替换”成 compile_error! 的假宏，强制该函数只能通过 println_info! 写往输出文件而不是 stdout——这是驱动层防止输出串台的一处精巧手法，与开头 lib.rs 用 do_not_use_print 假宏封禁裸 println! 的设计一脉相承：所有输出都必须走 print.rs 的 safe_print，写 stdout 失败时抛 FatalError 而不是 panic（避免在 ICE 路径上二次崩溃）。

6. pretty printing：driver 自带的前端打印器

README 提到 driver “有 pretty printing 相关代码”，对应 pretty.rs。print 函数按 PpMode 分派：

Source(Normal/Expanded/ExpandedIdentified/ExpandedHygiene)：从 source map 取出源码，按注解（AST 节点 id、hygiene 上下文）打印展开前后的源码；
AstTree / AstTreeExpanded：直接 {:?} 格式化 AST；
Hir(Normal/Identified/Typed)：打印 HIR，Typed 模式会把类型检查得到的表达式类型以 as <ty> 注释注入；
Mir / MirCFG / StableMir / ThirTree / ThirFlat：打印 MIR、Graphviz 控制流图、稳定 MIR 与 THIR。

其中需要类型信息的模式（needs_analysis()）会先触发 tcx.ensure_ok().analysis(())，这解释了为什么 -Zunpretty=hir=typed 这类选项实际上跑完了整个前端分析。

将 rustc 当库：`rustc_driver` 与 `rustc_interface` 的分层

仓库内自带的开发者指南 src/doc/rustc-dev-guide/src/rustc-driver/intro.md（即 README 所指 “rustc dev guide” 的对应文档）把分层总结得很清楚：

rustc_driver 是 rustc 的 main 函数，是“胶水”，负责按正确顺序运行各编译阶段，基于 rustc_interface 定义的接口工作；能用 rustc_driver（即本文的 rustc_driver_impl::run_compiler + Callbacks）时，优先于直接使用更底层的 rustc_interface；
rustc_interface 提供低层 API 供第三方手动驱动编译过程，把 rustc 内部当作库来分析 crate 或临时模拟编译器（如 rustdoc 编译代码并输出文档的场景），其入口 rustc_interface::run_compiler 接收 Config 和一个接收未解析 Compiler 的闭包；rustc_driver_impl::run_compiler 本身就是这个接口的一个完整实现范例。

指南同时警告：编译器内部 API 天然不稳定，接口可能变化。对本仓库读者而言，这句话的适用前提是当前 nightly 源码树（Cargo.toml 中各 crate 版本均为 0.0.0，edition 2024），不应把这里的内部 API 用于长期维护的外部工具。

小结：driver 层给编译器工程留下的三个模式

从 compiler/rustc_driver_impl 的源码可以提炼出驱动层刻意保持的三个工程模式：

入口薄、编排显式：main 只做日志/信号/ICE/Ctrl+C 四类基础设施初始化，然后立即委托 run_compiler；后者再以清晰的线性顺序串起“解析 → 展开 → 分析 → codegen → 链接”，每一阶段的早退条件（-Zls、-Zlink-only、--print、-Zunpretty、-Zno-analysis）都以显式分支呈现，读源码即可画出完整流程图。
钩子而非插件：Callbacks 提供四个固定回调点（config / 解析后 / 展开后 / 分析后），配合 Compilation::Stop/Continue，让 rustdoc、Clippy 等工具在不复制编译器逻辑的前提下截断或介入流水线；更底层的定制则改用 rustc_interface::run_compiler。
失败路径同样是一等公民：驱动层对“编译器自己崩溃”的处理比多数工具更讲究——safe_print 宏保证 I/O 失败不引发二次 panic，install_ice_hook 保证 ICE 附带版本、主机三元组、query 栈与落盘文件，signal_handler 甚至能在栈溢出的 SIGSEGV 中安全地打印并折叠周期性回溯。理解这些机制，是读懂 rustc 崩溃报告与调试 rustc 本身的第一步。