rustc_codegen_llvm debuginfo 模块：Rust 编译器 DWARF 调试符号生成的原理与实现剖析

在构建带 -g 选项的 Rust 可执行文件时，rustc_codegen_llvm 中的 debuginfo 模块负责把类型布局、函数签名、变量作用域与源码位置等信息转化为 LLVM 元数据，再由 LLVM 生成最终的可被 GDB/LLDB 读取的 DWARF（或 Windows 下的 CodeView）调试信息。本文基于仓库内 debuginfo 模块设计文档 逐节展开，结合 模块入口、类型元数据缓存 与 会话配置 中的实际实现，讲清该模块的设计原则、递归类型的 stub 打断机制，以及源码位置（prologue 处理）的完整链路，帮助读者理解从 rustc -g 到调试器可定位源码行号这一整条路径的底层机制。

模块定位：文档如何被加载，模块做什么

仓库中该模块的文档文件 doc.md 并不是独立存放的说明文件，而是被直接编织进了 rustdoc 文档系统。mod.rs 的第一行即为：

#![doc = include_str!("doc.md")]

这意味着对 debuginfo 模块做文档查询时看到的内容就是这份设计文档。文档开篇阐明了模块的核心职责：

该模块用于生成调试符号。我们使用 LLVM 的 source level debugging 特性来生成调试信息。基本原则是：只要 LLVM IR 中具备正确的元数据（metadata），LLVM 代码生成器就能为给定代码创建 DWARF 调试符号。元数据的组织方式非常接近 DWARF 的 debugging information entries（DIE），表示数据类型布局、函数签名、块布局、变量位置与作用域等信息。本模块的目的就是生成正确的元数据并插入 LLVM IR。

可以将其概括为三层职责：

1. 类型/符号描述：为每种参与调试的类型（struct、enum、vtable 等）生成对应的 DIType 节点；
2. 函数与变量描述：为函数（subprogram）、参数、局部变量、全局变量生成 DIScope/DIVariable 节点；
3. 源码位置绑定：为 IR 指令打上线号信息，使机器码可以映射回源码。

文档还指出一个重要工程决策：由于元数据树的确切格式在不同 LLVM 版本之间可能变化，模块尽量使用 LLVM 的 DIBuilder 来创建元数据，而不是手工拼装 !DICompositeType(...) 这类字符串化元数据。当前仓库的实现也印证了这一点——di_builder.rs 中封装了 DIBuilderBox，而 metadata.rs 中的各类 LLVMDIBuilder* 调用都通过 DIB(cx) 辅助函数取得 builder。

公开 API、缓存与私有状态的组织方式

文档对该模块的对外形态给出了明确描述：模块的公开 API 是一组函数，用正确的参数调用它们时，就会把正确的元数据插入 LLVM IR。因此模块是被外部客户端驱动的。文档中给出的示意性调用是 debuginfo::create_local_var_metadata(bx: block, local: &ast::local)。

从当前源码结构看，这套"被外部驱动"的 API 已经演进为 trait 方法的形式：mod.rs 中实现了 DebugInfoBuilderMethods<'tcx> for Builder，其中的 dbg_scope_fn 等方法对应文档所说的"为函数创建 scope 节点"这类公开操作；例如 dbg_scope_fn 内部依次完成：通过 file_metadata 获取文件节点、create_subroutine_type 构造子例程类型、计算 DISubprogram 的 flags（SPFlagDefinition、SPFlagLocalToUnit、SPFlagOptimized、SPFlagMainSubprogram），最后调用 LLVMRustDIBuilderCreateFunction 生成函数 DIE。对方法，还会额外先创建 LLVMRustDIBuilderCreateMethod 的声明节点，源码注释解释了原因：LLVM LTO 在类型 DIE 的子 DIE 是完整 subprogram 定义时无法统一类型定义，因此方法在类型 DIE 中只放 DW_AT_declaration，完整定义放在编译单元（CU）层级并用 DW_AT_specification 指回声明。

文档中强调的另一原则是缓存复用：模块内部通过缓存尽量复用已创建的元数据，调用方只需调用对应函数（文档示例为 file_metadata(cx, file)），函数会自行探测是否已存在该文件路径对应的节点。当前实现中的对应函数是 metadata.rs 中的 file_metadata，而缓存本体挂在编译单元级上下文上——CodegenUnitDebugContext 结构体中的 created_files 字段：

pub(crate) struct CodegenUnitDebugContext<'ll, 'tcx> {
    builder: DIBuilderBox<'ll>,
    created_files: RefCell<UnordMap<Option<(StableSourceFileId, SourceFileHash)>, &'ll DIFile>>,
    type_map: metadata::TypeMap<'ll, 'tcx>,
    adt_stack: RefCell<Vec<(DefId, GenericArgsRef<'tcx>)>>,
    namespace_map: RefCell<DefIdMap<&'ll DIScope>>,
    recursion_marker_type: OnceCell<&'ll DIType>,
}

见 mod.rs。这与文档所述"模块使用的全部私有状态存放在 CodegenUnitDebugContext（由 CodegenCx 持有）或 FunctionDebugContext（由 FunctionCx 持有）之中"完全一致。类型维度的缓存则由 TypeMap 承担（下文递归类型一节详述）。

此外，CodegenUnitDebugContext::new 在初始化时会根据目标平台的 DebuginfoKind 设置 LLVM 模块级标志，见 mod.rs：

• 目标为 Dwarf 或 DwarfDsym（macOS 的 dSYM）时，写入 "Dwarf Version" 模块标志，合并行为为 Max（多 CGU 交叉 LTO 合并时取最高版本，与 Clang 行为一致）；源码注释指出 macOS 与 Android 存在对高版本 DWARF 的兼容性问题，可用 --llvm-opts -dwarf-version,N 覆盖；
• 目标为 Pdb 时，写入 "CodeView" 标志，指示 LLVM 生成 CodeView 调试信息；
• 所有情况都写入 "Debug Info Version" 标志（LLVMRustDebugMetadataVersion()），防止位码读取器丢弃调试信息。

文档最后还给出了该模块源码文件的组织结构——三个概念性区域：1）模块公开接口；2）模块内部元数据创建函数；3）小工具函数。这一划分在目录中依然清晰可见：mod.rs 承担接口区（DebugInfoBuilderMethods 实现），metadata/ 子模块（含 type_map.rs、enums/）承担元数据创建，utils.rs、dwarf_const.rs、namespace.rs、gdb.rs 则是工具与辅助区。

递归类型问题：stub 机制如何打断类型引用环

文档中最具技术含量的一节是 Recursive Types。struct 和 enum 这类类型可能是递归的：某个类型 X 的定义（经由其他类型）传递性地指回 X 自身，这在类型引用图中引入了环。文档用一个单链表示例说明问题：

struct List {
    value: i32,
    tail: Option<Box<List>>,
}

对这种类型做朴素的需求驱动深度优先遍历（DFS）描述时，会产生如下无限调用栈：

describe(t = List)
  describe(t = i32)
  describe(t = Option<Box<List>>)
    describe(t = Box<List>)
      describe(t = List) // at the beginning again...
      ...

文档给出的解决方案是 stub（桩节点）：当算法遇到可能递归的类型（任何 struct 或 enum）时，立即创建一个类型描述节点并先于描述其成员之前插入缓存。这个节点此刻只是一个 stub（尚未描述和挂接成员），但已经可以让算法引用该类型；之后若成员描述中遇到递归引用，就会命中缓存，而不再重新描述该类型。文档指出这一行为封装在 type_map::build_type_with_children() 函数中。

当前仓库的 type_map.rs 中确实可以找到这套机制的完整实现，且比文档描述更为精细：

1）类型标识与缓存。缓存的键不是类型名，而是 UniqueTypeId 枚举，区分普通类型、枚举变体 part（DWARF 中 DW_TAG_variant_part）、单个变体对应的合成 struct 类型、CPP-like 模式下的变体 wrapper 以及 vtable 合成类型：

pub(super) enum UniqueTypeId<'tcx> {
    Ty(Ty<'tcx>, private::HiddenZst),
    VariantPart(Ty<'tcx>, private::HiddenZst),
    VariantStructType(Ty<'tcx>, VariantIdx, private::HiddenZst),
    VariantStructTypeCppLikeWrapper(Ty<'tcx>, VariantIdx, private::HiddenZst),
    VTableTy(Ty<'tcx>, Option<ExistentialTraitRef<'tcx>>, private::HiddenZst),
}

UniqueTypeId 通过稳定哈希（StableHash）生成十六进制字符串，作为 LLVM DIBuilderCreate*Type 系列接口的 UniqueId 参数，见 type_map.rs。TypeMap 本体则是 FxHashMap<UniqueTypeId, &'ll DIType>，insert 时若键已存在会直接 bug! 报错，保证"一个类型标识至多对应一个 DIE"的不变式。

2）stub 的创建。stub() 函数（type_map.rs）针对 Stub::Struct/Stub::VTableTy 调用 LLVMDIBuilderCreateStructType，针对 Stub::Union 调用 LLVMDIBuilderCreateUnionType，关键在于元素数组为空（no_elements）——即节点先占位，字段后补。

3）先插缓存、再描述成员。build_type_with_children 的核心流程是：断言该 stub 尚未入缓存 → 将 stub 插入 TypeMap → 执行 members 闭包描述成员（成员描述中若递归指回本类型，type_di_node 查缓存即命中 stub）→ 用 LLVMRustDICompositeTypeReplaceArrays 把成员数组与泛型参数数组回填到 stub 上。其源码注释与文档描述一一对应：

This function enables creating debuginfo nodes that can recursively refer to themselves. It will first insert the given stub into the type map and only then execute the members and generics closures passed in. ... If the type of a field transitively refers back to the type currently being built, the stub will already be found in the type map, which effectively breaks the recursion cycle.

4）对"膨胀式递归"的额外防护。文档未展开、但当前实现中存在的一个细节值得注意：对于像 enum Recursive<T> { Recurse(*const Recursive<Wrap<T>>), Item(T) } 这样参数严格包含祖先参数的膨胀型递归，类型展开理论上可以无限进行。build_type_with_children 借助 CodegenUnitDebugContext 中的 adt_stack（一个 (DefId, GenericArgsRef) 栈）检测这种情况：当前类型与栈上某祖先 def_id 相同，且某参数严格包含（arg != ancestor_arg && arg.contains(ancestor_arg)）祖先的对应参数、且中间各层类型都使用该祖先参数时，判定为 is_expanding_recursive，直接返回 stub 而不再展开成员（源码标注了 FIXME: indicate that this is an expanding recursive type in stub metadata?）。对普通的 Box<Box<Recursive>> 这类正常递归则不触发该短路，注释中专门解释了原因。栈的压入/弹出由 RAII 守卫 AdtStackPopGuard 保证。

从源码结构看，这套 stub + 栈检测的组合正是文档所述"stub 打断环"策略在长期演进后的完整形态：基础环靠 stub 缓存打断，膨胀环靠 adt_stack 检测后以未展开 stub 兜底。

源码位置与行号信息：prologue 的特别处理

文档第二节 Source Locations and Line Information 指出：除类型描述外，调试信息还必须能把机器码位置映射回源码位置，这一功能同样由本模块处理，并列出三个控制函数：

• set_source_location()
• clear_source_location()
• start_emitting_source_locations()

其语义是一个有状态 API（刻意模仿 LLVM 的行为）：调用 set_source_location() 后，之后创建的所有 IR 指令都会关联到该源码位置，直到再次设置或清除；清除之后创建的指令不关联任何源码位置。文档特别提醒：不要依赖调用点处存在某个特定状态，因为先前调用可能已经改变了它。

当前实现中该状态读取封装在 Builder::get_dbg_loc（mod.rs），底层即 LLVM 的 LLVMGetCurrentDebugLocation2，指令创建时的位置注入由 CodegenBuilderMethods 各路径调用该模块的设置接口完成——与文档描述的状态机模型一致。

文档随后花较大篇幅讨论一个容易踩坑的话题——函数 prologue。函数机器码开头通常有若干指令用于把参数装入 alloca、检查栈空间是否足够，这段 prologue 在源码中是不可见的。LLVM 会在行表（line table）中第一个非 prologue 指令处放置特殊的 PROLOGUE END 标记；而 LLVM 判断 prologue 结束位置的方法是：找到函数体中第一条关联了源码位置的指令。因此生成 prologue 指令时必须保证在"真正"的函数体开始之前不发出源码位置信息——这正是文档中第三个函数 start_emitting_source_locations() 的作用：新 codegen 的函数默认禁用源码位置发出，只有在即将开始 codegen 该函数顶层基本块之前调用该函数后才激活。

文档还给出了一个例外：llvm.dbg.declare 指令必须关联到被声明变量的源码位置。对函数参数而言，这些 dbg.declare 通常出现在 prologue 中段，但 LLVM 的 prologue 检测会忽略它们；因此 create_argument_metadata() 等函数负责在源码位置发出仍被禁用时，为 llvm.dbg.declare 正确关联位置，调用方无需做任何特殊处理。

理解这一节的实际意义在于：它解释了为什么调试器停在函数第一行时，栈回溯与行号表能正确区分"编译器生成的序言"与"用户代码"——PROLOGUE END 标记的位置完全由模块"何时开始发射源位置"这一策略决定，而该策略被刻意推迟到函数体真正开始之处。

与编译选项的衔接：从 -g 到 DebugInfo 枚举

上述元数据生成并非无条件进行，它与 rustc 的调试信息级别直接挂钩。从 rustc_session/src/config.rs 可以看到：

• -g 被定义为等价于 -C debuginfo=2（select_debuginfo 中取 -g 次数与 -C debuginfo 数值的最大值，max_g > max_c 时得到 DebugInfo::Full）；
• DebugInfo 枚举区分 None / Limited / Full 等档位，-g0 对应 DebugInfo::None，此时不生成调试元数据，debuginfo 模块基本空转；
• 若使用 -C remark 而未开启任何 debuginfo，会话配置会给出"需要 -C debuginfo=n 才能显示源码位置"的早期告警，印证了行号信息与调试信息级别的绑定关系。

在模块内部，这个档位直接决定元数据的"厚度"：mod.rs 中，get_function_signature 与 get_template_parameters 均在 cx.sess().opts.debuginfo != DebugInfo::Full 时返回空签名/空模板参数——即较低档位下仍生成函数 DIE（变量与行号信息可用），但不生成完整的参数类型与泛型模板信息。这为"为什么 -g1 比 -g2 在调试器里看到的类型细节更少"提供了源码级解释。

验证路径：如何在仓库中观察其行为

该模块产出的元数据最终体现为二进制中的 DWARF/CodeView 段，仓库提供了相应的测试面供进一步观察：

• tests/debuginfo/：针对 GDB 调试体验（natvis 文件、-gdwarf-* 变体）的集成测试；
• tests/run-make/ 中与 dwarf/split-debuginfo 相关的 run-make 用例：覆盖模块标志（如 "Dwarf Version"）、-C split-debuginfo 等路径；
• 模块自身的行为约定（如 TypeMap::insert 的重复键 bug!、build_type_with_children 的先插后建顺序）可从 type_map.rs 直接阅读核对。

需要注意的适用前提：本文涉及的实现细节均以当前仓库状态为准；文档中出现的 create_local_var_metadata、start_emitting_source_locations 等函数名为设计文档中的示意性/历史命名，当前代码中对应的实际入口是 DebugInfoBuilderMethods trait 方法（由 MIR 构建与 codegen 路径调用）与 Builder::get_dbg_loc 的读侧接口，二者语义与文档描述的状态机模型一致。

小结

debuginfo 模块的设计可以浓缩为三点：以 LLVM 元数据为中间表示（借助 DIBuilder 而非手写元数据字符串，以平滑跨 LLVM 版本演进）；以缓存为核心（CodegenUnitDebugContext 持有文件、类型、命名空间三级缓存，调用方通过"查缓存或创建"的统一入口取值）；以 stub 机制解决类型引用环（先占位入缓存，后回填成员，另以 adt_stack 检测膨胀式递归），并以"默认禁用、函数体开始时启用"的源码位置发射策略正确切出 prologue。理解这套机制后，再去看 -g 级别差异、Dwarf Version 模块标志或调试器中看到的类型/行号行为，都能追溯到本模块中对应的具体实现。