Rust 符号名称修改(Symbol Mangling)方案 v0 深度解析:RFC 2603 从设计动机到完整文法

原创2026-10-15 18:17:041,383 阅读
文章标签:文档

Rust 符号名称修改(Symbol Mangling)方案 v0 深度解析:RFC 2603 从设计动机到完整文法

本指南以 Rust RFC 仓库中的 text/2603-rust-symbol-name-mangling-v0.md 为骨架,系统讲解 Rust 编译器符号名称修改(name mangling)方案 v0(即今天 Rust 二进制中常见的 _R 前缀符号)。你将理解旧版哈希后缀方案的缺陷、新方案的编码文法与压缩机制、闭包与方法等复杂实体的命名规则,并掌握 demangler 的解析思路——无论是排查符号表、编写外部工具,还是为 #[no_std] 环境实现轻量级 demangler,本指南都能提供可直接落地的知识。

背景:为什么 Rust 需要一套新的符号修改方案

符号名称修改(name mangling)是把源代码中的实体(函数、静态变量等)编码成链接器与符号表可见的唯一字符串的过程。Rust 编译器自诞生以来使用了一套临时拼凑的旧方案:它以一个哈希后缀来保证符号唯一性,其余部分则零散地借鉴了 Itanium C++ ABI 的风格。随着 Rust 的发展,这套方案的缺陷日益明显。

RFC 2603 提出的新方案(mangling scheme v0)用来定义编译器生成的符号名称应该是什么样。它的核心优势在于:一致、不依赖编译器内部实现细节、符号中编码的信息可以被再次解码,从而显著改善外部工具(demangler、调试器、剖析器)处理 Rust 二进制文件的体验。

需要特别注意的是:在 RFC 提出之时,该方案不属于语言规范,也不属于稳定 Rust ABI 的一部分。它被设计为稳定且可扩展,未来有可能进入语言规范和稳定 ABI,但在当时仍然是 Rust 编译器的实现细节。

旧方案的四大痛点

旧方案由于其临时性(ad-hoc)积累了一系列问题:

  1. 泛型信息丢失:修改过程中泛型参数等信息被丢弃,无法从单态化(monomorphized)函数的符号名中提取出其类型实参。例如你无法从 _ZN4core3mem8align_of17h...E 这类名字里读回 align_of::<usize> 中的 usize。
  2. 方案不一致:大多数路径使用 Itanium ABI 风格编码,但有一部分并不符合,导致解析规则支离破碎。
  3. 符号包含 . 字符:部分平台不支持符号名中的 .(如某些汇编器的符号命名规则、Windows LLD 的 issue 54190、ThinLTO 的 issue 53912 等场景都曾因此踩坑)。
  4. 依赖编译器内部实现:旧方案的结果无法被另一个编译器实现或外部工具复现,因为其中的哈希来自各种编译器内部数据结构。

作为旁证,仓库中的 text/0109-remove-crate-id.md 在 "Symbol mangling" 一节也记录了旧方案的背景:当时的 mangled 符号在末尾携带版本号,最终被视为过度设计而被移除;符号末尾的哈希只包含 crate 名称与命令行元数据(通过 -C metadata=foo 传入哈希字符串)。这印证了旧方案"哈希掩盖一切"的形态。

新方案如何解决

新方案对症下药:

  • 可逆地编码泛型参数信息:可以从符号名中反推出具体的类型实参。
  • 定义一致、不依赖 pretty-printing:编码规则由正式文法定义,不再依赖对语言构造的格式化输出。
  • 字符集受限:生成的符号只包含 A-Z、a-z、0-9 和 _ 这些字符,规避了 . 等特殊字符带来的平台兼容性问题。
  • 面向未来:虽然仍包含部分实现定义的内容,但相比旧方案,它更接近"完全可预测"的目标。

这些性质使得第三方工具能够更容易地与 Rust 二进制协作。

符号修改方案的设计需求与非目标

在设计任何 mangling 方案之前,先要明确它要满足什么。RFC 区分了一个必需目标和若干可取目标。

必需目标:无歧义

方案必须为最终可能出现在二进制符号表中的一切内容提供无歧义的字符串编码。

"无歧义"意味着:任意两个不同的编译器生成实体(主要是函数的机器码)绝不能映射到相同的符号名。这正是旧方案中哈希后缀的主要职责——用不可读的哈希来消解冲突。而新方案换了一种思路:在编码结构上就直接保证唯一性,同时让符号具备可读、可解码的能力。

可取目标

  • 可解码性(decodable):应能从符号中识别出它标识的是某个多态函数的具体实例。这对外部工具、backtrace、以及只有二进制表示的人都很重要。旧方案中这类信息全部沉没在"魔法哈希后缀"里。
  • 平台无关性:主要通过把字符集限制为 A-Z、a-z、0-9、_ 实现。其他字符要么在某些上下文中有特殊含义(如 MSVC DEF 文件中的 .),要么根本不被支持(如 Unicode)。
  • 高效性:符号不能无谓地长(否则占用目标文件空间,增加编译器和链接器的工作量),生成/解码符号名的计算开销也要可控。
  • 可预测性:当用于稳定 ABI 时,应能根据源码层面的构造手工推导出符号名。例如给定 fn foo<T>() { ... },应能手工构造出 foo<u32> 或 foo<extern fn(i32, &mut SomeStruct<(char, &str), ...) -> !>() 的符号名。旧方案由于哈希来自编译器内部数据结构,另一个编译器实现连简单情况都无法预测。注意:新方案当时也没有完全满足这一要求,因为仍有部分内容留给编译器实现决定。

非目标

RFC 明确声明了两个非目标:

  1. 不与现有(如 C++)mangling 方案兼容。虽然用现有方案编码 Rust 符号听起来诱人,但作者认为实际收益很小(C++ 工具不会把符号 demangle 成 Rust 语法,demangle 结果也难以阅读),而让现有工具支持 Rust 专用方案反而相当可行——GDB、LLDB、binutils、valgrind 等许多工具已经有处理 Rust 符号的专门代码路径。
  2. 不定义标准化的 demangled 形式。RFC 只定义 mangled 形式并保证它能被高效 demangle,但不同的 demangler 在"如何把符号呈现给用户"上仍保留一定的自由。

通过示例理解方案:从最简单的函数说起

RFC 用一系列由浅入深的例子来展开方案。我们从最简单的情况开始——它已经涉及一些可能令人惊讶的设计。

自由函数与静态项

一个自由函数由其绝对路径唯一标识。例如:

mod foo {
  fn bar() {}
}

路径是 foo::bar,而 NN3foo3bar 是对该路径的一种合法编码。为什么采用这种数字内嵌的格式?因为这是一种游程编码(run-length encoding),与 Itanium C++ ABI 对标识符的处理方式类似。方案沿用这一格式是因为:在我们受限的字符集下,很难找到合适的标识符终止符,而长度前缀天然自终止。

注意路径中的每个组件(如 foo、bar)前面都有一个起始标签(start-tag)——这里是 N。这个标签是必要的,因为后续的复杂嵌套结构(泛型参数、方法、impl 等)都依赖它来表达语法归属。

然而 NN3foo3bar 并不能在所有上下文中无歧义地标识该函数——另一个 crate 完全可以在自己的 mod foo 里也定义一个 fn bar。为避免冲突,绝对路径必须总是包含 crate-id,于是符号变成 NNC7mycrate3foo3bar。crate-id 的起始标签是 C。

还存在另一种歧义:Rust 有两个命名空间——类型命名空间和值命名空间。下面这段代码是合法的:

fn foo() {
    fn bar() {}
}

mod foo {
    fn bar() {}
}

函数 foo 在值命名空间,模块 foo 在类型命名空间,二者互不干扰。为了让两个不同的 bar 函数的符号唯一,需要在组件的起始标签处按需加上命名空间标识符:NvNvC7mycrate3foo3bar(第一个 bar,位于函数 foo 内)和 NvNtC7mycrate3foo3bar(第二个 bar,位于模块 foo 内)。注意差异:NvNv... 与 NvNt...,其中 v 表示值命名空间,t 表示类型命名空间。

最后一种歧义来自宏卫生(macro hygiene):多个同名项可以出现在同一上下文中。编译器内部通过附加数字索引来消歧义——某个父级内第一次出现的 foo 实际被视为 foo'0,第二次是 foo'1,依此类推。方案照搬这一做法:对索引非零的标识符,在前面加上消歧义前缀。例如宏展开产生如下代码:

mod foo {
    fn bar'0() {}
    // The second `bar` function was introduced by macro expansion.
    fn bar'1() {}
}

两个函数的符号分别编码为 NvNtC7mycrate3foo3bar 和 NvNtC7mycrate3foos_3bar(注意第二个符号里的 s_ 前缀)。类似的消歧义还用于处理同名不同版本的 crate:同样使用该语法前缀来编码 crate 消歧义符,如 NtNvCs1234_7mycrate3foo3bar。前缀的具体形态在参考级说明中给出。

与 C++ 等支持函数重载的语言不同,Rust 的符号不需要包含函数参数类型——Rust 不允许同名不同参数的两个函数。

最终,函数符号还要加上所有本方案符号共有的 _R 前缀:

  _RNvNtCs1234_7mycrate3foo3bar
  <>^^^^^<----><------><--><-->
   ||||||   |      |     |   |
   ||||||   |      |     |   +--- "bar" identifier
   ||||||   |      |     +------- "foo" identifier
   ||||||   |      +------------- "mycrate" identifier
   ||||||   +-------------------- disambiguator for "mycrate"
   |||||+------------------------ start-tag for "mycrate"
   ||||+------------------------- namespace tag for "foo"
   |||+-------------------------- start-tag for "foo"
   ||+--------------------------- namespace tag for "bar"
   |+---------------------------- start-tag for "bar"
   +----------------------------- common Rust symbol prefix

泛型函数

泛型函数的每个单态化实例(monomorphization)都有自己的符号名,由具体泛型实参列表来消歧义。实参通过一对结构加入符号:开头的 I 起始标签 + 结尾的实参列表。例如实例:

std::mem::align_of::<f64>

被编码为:

_RINvNtC3std3mem8align_ofdE
  ^                      ^^
  |                      ||
  |                      |+--- end of argument list
  |                      +--- f64
  +--- start-tag

其中 I 位于实参所属对象之前,d 表示 f64,E 结束实参列表。显然,方案需要能够表示可以出现在实参列表中的所有类型(未来加入 const generics 后,还需要表示值):

  • 基本类型(char、()、str、!、i8、i16 ...)
  • 引用和指针类型(共享、mut、const)
  • 元组
  • 数组,带或不带固定长度(如 [u8]、[u8; 17])
  • 结构体、枚举、闭包及其他具名类型,可能带各自的类型实参
  • 函数类型,如 fn(&i32) -> u16
  • dyn trait

基本类型都用单个小写字母编码(与 Itanium 方案一致)。具名类型编码为其绝对路径(含实参),与函数符号的做法相同。引用、元组、函数类型等复合类型遵循参考级说明中的简单文法。一些示例编码:

  • std::mem::align_of::<usize>:_RINvNtC3std3mem8align_ofjE
  • std::mem::align_of::<&char>:_RINvNtC3std3mem8align_ofRcE
  • std::mem::align_of::<std::mem::Discriminant>:_RINvNtC3std3mem8align_ofNtNtC3std3mem12DiscriminantE
  • std::mem::align_of::<&mut (&str,())>:_RINvNtC3std3mem8align_ofQTReuEE

还有一个针对泛型函数的特殊情形:编译器可能生成单态化的 crate-local 副本。如果一个函数 foo<T> 在两个不同 crate 中都被以 foo<u32> 使用,编译器(取决于优化级别)可能在 LLVM IR 层面生成两个不同函数、各带各的符号。为避免冲突,单态化符号名必须包含其实例化所属 crate 的 id——方案通过在符号末尾追加 <crate-id> 后缀实现:

_RINvNtC3std3mem8align_ofjEC3foo (for crate "foo")
_RINvNtC3std3mem8align_ofjEC3bar (for crate "bar")

闭包与闭包环境

方案需要能为闭包的函数代码生成符号名,也需要能在闭包作为类型实参时引用闭包类型。闭包没有名字,因此需要生成一个名字。方案复用了前面介绍的命名空间和消歧义机制:闭包拥有自己的"命名空间"(既不在类型命名空间也不在值命名空间),每个闭包有一个空名字,配一个在其父级内标识它的消歧义索引(类似宏卫生)。

mod foo {
  fn bar(x: u32) {
    let a = |x| { x + 1 }; // local name: NC<...>0
    let b = |x| { x + 2 }; // local name: NC<...>s_0

    a(b(x))
  }
}

上述代码中有两个闭包:赋给 a 的和赋给 b 的。第一个的局部名是 NC<...>0,第二个是 NC<...>s_0。这里的 0 表示其(空)名字的长度;<...> 是父级路径;C 是命名空间标签,类似于值命名空间的 v 标签;第二个闭包的 s_ 是消歧义索引(索引 0 依然用不加前缀的方式编码)。它们的完整名分别是 NCNvNtC7mycrate3foo3bar0 和 NCNvNtC7mycrate3foo3bars_0。

方法

方法嵌套在 impl 或 trait 项内。理论上可以把方法符号构造成 my_crate::foo::{{impl}}::some_method 这样的路径,其中 {{impl}} 用某种方式标识具体的 impl。由于 impl 没有名字,只能使用类似闭包的索引方案(编译器内部也正是这么做的)。加上泛型实参后,符号看起来会像 my_crate::foo::impl'17::<u32, char>::some_method。

但作者认为这类符号很难映射回它所代表的方法:试想一个模块里有几十个类型,每个类型都有多个由 #[derive(...)] 生成的 impl 块。要弄清某个符号对应哪个方法,你得数清楚模块里手写和宏生成的 impl 块数量,还得猜对某个 derive 宏引入了多少个 impl 块(每次宏调用可能引入 0..n 个)。方法名或许能给出线索,但名为 clone、hash、eq 的方法可能有几十个。

因此 RFC 提议让符号名贴近方法在错误消息中的表示方式:

  • 固有方法(inherent method):<Foo<u32, char>>::some_method
  • trait 方法:<Foo<u32, char> as SomeTrait<Quux>>::some_method

实现方式是扩展此前使用的路径定义:路径的根不再总是 crate-id,也可以是一个包含 self 类型(以及 trait 方法中的 trait 名)的 impl 产生式。扩展后的路径语法如下:

<path> = C <identifier>                      // crate-id root
       | M <type>                            // inherent impl root
       | X <type> <path>                     // trait impl root
       | N <namespace> <path> <identifier>   // nested path
       | I <path> {<generic-arg>} E          // generic arguments

完整符号示例:

<mycrate::Foo<u32>>::foo => _RNvMINtC7mycrate3FoomE3foo
<u32 as mycrate::Foo>::foo => _RNvXmNtC7mycrate3Foo3foo
<mycrate::Foo<u32> as mycrate::Bar<u64>>::foo => _RNvXINtC7mycrate3FoomEINtC7mycrate3BaryE3foo

泛型 impl 内的项

Rust 允许在泛型项(如函数或 impl)内定义项。例如:

struct Foo<T>(T);

impl<T> From<T> for Foo<T> {
  fn from(x: T) -> Self {
    static MSG: &str = "...";
    panic!("{}", MSG)
  }
}

这里的 MSG(或其他嵌套定义)不继承 impl 的泛型上下文——MSG 是非泛型的,定义在它位置的函数也一样。按照前面的例子,MSG 的完全限定名是 <mycrate::Foo<_> as std::convert::From<_>>::from::MSG,其符号名为:

_RNvNvXINtC7mycrate3FoopEINtNtC3std7convert4FrompE4from3MSG

然而引入 trait 特化(specialization)后,这个符号会产生歧义。看下面的代码:

struct Foo<T>(T);

impl<T> From<T> for Foo<T> {
  default fn from(x: T) -> Self {
    static MSG: &str = "...";
    panic!("{}", MSG)
  }
}

impl<T: Default> From<T> for Foo<T> {
  fn from(x: T) -> Self {
    static MSG: &str = "123";
    panic!("{}", MSG)
  }
}

注意两个 MSG 静态项具有相同的路径 <Foo<_> as From<_>>::foo::MSG。必须对 impl 进行消歧义:方案把 impl 的路径加入符号名。语法随之扩展为:

<path> = C <identifier>                      // crate-id root
       | M <impl-path> <type>                // inherent impl root
       | X <impl-path> <type> <path>         // trait impl root
       | N <namespace> <path> <identifier>   // nested path
       | I <path> {<generic-arg>} E          // generic arguments

<impl-path> = [<disambiguator>] <path>

两个符号名分别变成:

_RNvNvXs2_C7mycrateINtC7mycrate3FoopEINtNtC3std7convert4FrompE4from3MSG
_RNvNvXs3_C7mycrateINtC7mycrate3FoopEINtNtC3std7convert4FrompE4from3MSG
       <----------><----------------><----------------------->
        impl-path      self-type            trait-name

与其他消歧义信息一样,这段 impl-path 在 demangle 时通常不会展示给用户。

Unicode 标识符

Rust 允许 Unicode 标识符,但方案的字符集限制为 ASCII 字母数字和 _。为了在这两者之间转换,RFC 采用了与 Swift 相同的做法:用 Punycode 编码所有非 ASCII 标识符。Punycode 是一种标准化且高效的编码,能让编码结果保持相当的可读性。例如字符串:

"Gödel, Escher, Bach"

编码为:

"Gdel, Escher, Bach-d3b"

与 Base64 之类的方案相比,它仍能让人大致看出原始字符串长什么样。

名字中的每个组件(即上面示例中以字节数开头的内容)被单独编码。以这种方式编码的组件会加上 u 前缀,让 demangler 知道该标识符需要进一步解码。例如函数:

mod gödel {
  mod escher {
    fn bach() {}
  }
}

会被编码为:

_RNvNtNtC7mycrateu8gdel_5qa6escher4bach
                 <-------->
              Unicode component

压缩与替换(Compression/Substitution)

符号名长度直接影响编译器、链接器和加载器的工作量,名字越短越好。但 Rust 的泛型会产生相当长的名字(由于类型推断和 impl Trait,这些长名字在代码中往往不可见)。例如下面函数的返回类型:

fn quux(s: Vec<u32>) -> impl Iterator<Item = (u32, usize)> {
    s.into_iter()
     .map(|x| x + 1)
     .filter(|&x| x > 10)
     .zip(0..)
     .chain(iter::once((0, 0)))
}

其返回类型是:

std::iter::Chain<
  std::iter::Zip<
    std::iter::Filter<
      std::iter::Map<
        std::vec::IntoIter<u32>,
        [closure@src/main.rs:16:11: 16:18]>,
      [closure@src/main.rs:17:14: 17:25]>,
    std::ops::RangeFrom<usize>>,
  std::iter::Once<(u32, usize)>>

如果这个类型作为泛型实参出现(甚至反复出现),符号名会非常长。C++ 的模板也有同样的问题,这正是 Itanium mangling 引入压缩(compression)概念的原因:某个定义中的组件若出现多次,就不再重复写出,而是替换为替换标记(substitution marker,即 backref 反向引用),解码时据此重建所引用的组件。本方案采用同样的思路(但定义更简单)。

具体机制是:在构建 mangled 符号名时,记住输出字符串中每个可替换项的位置;当同一项再次出现时,用指向首次出现位置的 backref 代替它。可替换的对象有三类:(1) 路径的所有前缀(含完整路径本身);(2) 除基本类型外的所有类型;(3) 类型级常量(数组长度、传给 const 泛型参数的值)。

举例说明。名字:

std::iter::Chain<std::iter::Zip<std::vec::IntoIter<u32>, std::vec::IntoIter<u32>>>

先编码为如下未压缩字符串。下方标注的是各段首次出现的 0 基字节位置,这些段之后都可以被 backref 替换:

  0         10        20        30        40        50        60        70        80        90
_RINtNtC3std4iter5ChainINtNtC3std4iter3ZipINtNtC3std3vec8IntoItermEINtNtC3std3vec8IntoItermEEE
                            5----              5----                    5----
                          3-----------                                43---------
                                                                    41--------------------
                                                                   40-----------------------

编译器应总是使用最长的可行替换以获得最佳压缩。压缩后的符号为:

_RINtNtC3std4iter5ChainINtB2_3ZipINtNtB4_3vec8IntoItermEBt_EE
                          ^^^         ^^^               ^^^     back references

backref 的形式为 B<base-62-number>_。

参考级说明:符号名的正式文法

参考级说明由三部分组成:

  1. 符号名应遵循的语法规范。
  2. 压缩方案规范。
  3. Rust 实体到符号名语法的映射。

对 demangler 的实现者而言,只有前两部分值得关注——demangler 只需理解符号的语法和压缩,无需关心编译器如何生成符号名。

完整 EBNF 文法

符号名的语法以扩展巴科斯-瑙尔形式(EBNF)给出:

  • 非终结符写在尖括号内(如 <path>)
  • 终结符写在引号内(如 "_R")
  • 可选部分写在方括号内(如 [<disambiguator>])
  • 重复(零次或多次)用花括号表示(如 {<type>})
  • 注释以 // 标记
// The <decimal-number> specifies the encoding version.
<symbol-name> =
    "_R" [<decimal-number>] <path> [<instantiating-crate>] [<vendor-specific-suffix>]

<path> = "C" <identifier>                    // crate root
       | "M" <impl-path> <type>              // <T> (inherent impl)
       | "X" <impl-path> <type> <path>       // <T as Trait> (trait impl)
       | "Y" <type> <path>                   // <T as Trait> (trait definition)
       | "N" <namespace> <path> <identifier> // ...::ident (nested path)
       | "I" <path> {<generic-arg>} "E"      // ...<T, U> (generic args)
       | <backref>

// Path to an impl (without the Self type or the trait).
// The <path> is the parent, while the <disambiguator> distinguishes
// between impls in that same parent (e.g. multiple impls in a mod).
// This exists as a simple way of ensure uniqueness, and demanglers
// don't need to show it (unless the location of the impl is desired).
<impl-path> = [<disambiguator>] <path>

// The <decimal-number> is the length of the identifier in bytes.
// <bytes> is the identifier itself, and it's optionally preceded by "_",
// to separate it from its length - this "_" is mandatory if the <bytes>
// starts with a decimal digit, or "_", in order to keep it unambiguous.
// If the "u" is present then <bytes> is Punycode-encoded.
<identifier> = [<disambiguator>] <undisambiguated-identifier>
<disambiguator> = "s" <base-62-number>
<undisambiguated-identifier> = ["u"] <decimal-number> ["_"] <bytes>

// Namespace of the identifier in a (nested) path.
// It's an a-zA-Z character, with a-z reserved for implementation-internal
// disambiguation categories (and demanglers should never show them), while
// A-Z are used for special namespaces (e.g. closures), which the demangler
// can show in a special way (e.g. `NC...` as `...::{closure}`), or just
// default to showing the uppercase character.
<namespace> = "C"      // closure
            | "S"      // shim
            | <A-Z>    // other special namespaces
            | <a-z>    // internal namespaces

<generic-arg> = <lifetime>
              | <type>
              | "K" <const> // forward-compat for const generics

// An anonymous (numbered) lifetime, either erased or higher-ranked.
// Index 0 is always erased (can show as '_, if at all), while indices
// starting from 1 refer (as de Bruijn indices) to a higher-ranked
// lifetime bound by one of the enclosing <binder>s.
<lifetime> = "L" <base-62-number>

// Specify the number of higher-ranked (for<...>) lifetimes to bound.
// <lifetime> can then later refer to them, with lowest indices for
// innermost lifetimes, e.g. in `for<'a, 'b> fn(for<'c> fn(...))`,
// any <lifetime>s in ... (but not inside more binders) will observe
// the indices 1, 2, and 3 refer to 'c, 'b, and 'a, respectively.
// The number of bound lifetimes is value of <base-62-number> + 1.
<binder> = "G" <base-62-number>

<type> = <basic-type>
       | <path>                      // named type
       | "A" <type> <const>          // [T; N]
       | "S" <type>                  // [T]
       | "T" {<type>} "E"            // (T1, T2, T3, ...)
       | "R" [<lifetime>] <type>     // &T
       | "Q" [<lifetime>] <type>     // &mut T
       | "P" <type>                  // *const T
       | "O" <type>                  // *mut T
       | "F" <fn-sig>                // fn(...) -> ...
       | "D" <dyn-bounds> <lifetime> // dyn Trait<Assoc = X> + Send + 'a
       | <backref>

<basic-type> = "a"      // i8
             | "b"      // bool
             | "c"      // char
             | "d"      // f64
             | "e"      // str
             | "f"      // f32
             | "h"      // u8
             | "i"      // isize
             | "j"      // usize
             | "l"      // i32
             | "m"      // u32
             | "n"      // i128
             | "o"      // u128
             | "s"      // i16
             | "t"      // u16
             | "u"      // ()
             | "v"      // ...
             | "x"      // i64
             | "y"      // u64
             | "z"      // !
             | "p"      // placeholder (e.g. for generic params), shown as _

// If the "U" is present then the function is `unsafe`.
// The return type is always present, but demanglers can
// choose to omit the ` -> ()` by special-casing "u".
<fn-sig> = [<binder>] ["U"] ["K" <abi>] {<type>} "E" <type>

<abi> = "C"
      | <undisambiguated-identifier>

<dyn-bounds> = [<binder>] {<dyn-trait>} "E"
<dyn-trait> = <path> {<dyn-trait-assoc-binding>}
<dyn-trait-assoc-binding> = "p" <undisambiguated-identifier> <type>
<const> = <type> <const-data>
        | "p" // placeholder, shown as _
        | <backref>

// The encoding of a constant depends on its type. Integers use their value,
// in base 16 (0-9a-f), not their memory representation. Negative integer
// values are preceded with "n". The bool value false is encoded as `0_`, true
// value as `1_`. The char constants are encoded using their Unicode scalar
// value.
<const-data> = ["n"] {<hex-digit>} "_"

// <base-62-number> uses 0-9-a-z-A-Z as digits, i.e. 'a' is decimal 10 and
// 'Z' is decimal 61.
// "_" with no digits indicates the value 0, while any other value is offset
// by 1, e.g. "0_" is 1, "Z_" is 62, "10_" is 63, etc.
<base-62-number> = {<0-9a-zA-Z>} "_"

<backref> = "B" <base-62-number>

// We use <path> here, so that we don't have to add a special rule for
// compression. In practice, only a crate root is expected.
<instantiating-crate> = <path>

// There are no restrictions on the characters that may be used
// in the suffix following the `.` or `$`.
<vendor-specific-suffix> = ("." | "$") <suffix>

命名空间标签(Namespace Tags)

命名空间由一个实现定义的单字符标签(<namespace> 产生式)标识。只有闭包(C)和 shim(S)分配了确定的字符,以便 demangler 可靠地调整输出;其他命名空间标签在 demangle 时必须省略或原样显示。

这是对编译器当前实现的让步:语言层面只有两个命名空间(类型和值),但编译器在一些重要的数据结构中使用了更多内部命名空间,消歧义索引也依据这些内部数据结构分配。为了让编译器不必花费处理时间重建不同的消歧义索引,方案直接采用了内部未指明的"命名空间"。这可能在将来改变。

类型级常量(Type-Level Constants)

如文法所示,常量值通过 <const-data> = {<hex-digit>} "_" 产生式编码,其中 {<hex-digit>} 是常量的数值,而非其字节表示。使用数值是平台无关的,但不易扩展到非整数数据类型。

未来 Rust 很可能支持复杂的类型级常量(不只是整数)。RFC 建议把这类常量的正规 mangling 留给未来的 const-generics 工作,目前只为整数值定义 mangling。

Punycode 标识符的细节

Punycode 生成的字符串形如 ([[:ascii:]]+-)?[[:alnum:]]+。这有问题:- 字符不在受支持的字符集内——Punycode 用 - 分隔 ASCII 部分(若存在)与非 ASCII 字符的 base-36 编码。

因此本方案偏离原版 Punycode,将 - 替换为 _。示例如下:

Original Punycode Punycode + Encoding
føø f-5gaa f_5gaa
α_ω _-ylb7e __ylb7e
铁锈 n84amf n84amf
🤦 fq9h fq9h
ρυστ 2xaedc 2xaedc

经过这个后处理,Punycode 字符串就可以像普通标识符一样处理,无需额外特殊逻辑。

厂商特定后缀(Vendor-specific Suffix)

与 Itanium C++ ABI mangling 类似,包含 . 或 $ 的符号名表示该符号的厂商特定版本,. 或 $ 之后的字符没有限制。

这在"局部唯一的名字需要变成全局唯一"时会发生。例如 LLVM 在 LTO 期间可能追加 .llvm.<numbers> 后缀来保证名字唯一;$ 可用于 Mach-O 上的线程局部数据。这些情况下通常可以忽略后缀:带后缀的名字与原符号语义相同。

压缩机制详解

符号名压缩通过把已经出现过的部分替换为 backref 来实现。压缩直接内建于 mangling 算法,如以下伪代码所示:

fn mangle(node, output_string, substitution_dictionary) {
    if let Some(backref) = substitution_dictionary.get(node) {
        // Emit the backref instead of the node's contents
        mangle(backref, output_string)
    } else {
        // Remember where the current node starts in the output
        let start_position = output_string.len()

        // Do the actual mangling, including recursive mangling of child nodes

        // Add the current node to the substitution dictionary
        if node.is_substitutable() {
            substitution_dictionary.insert(node, start_position)
        }
    }
}

该算法自动选择最佳压缩,因为父节点(总是更大)先于子节点被访问。

这种压缩依赖于一个关键事实:所有可替换的 AST 节点都具有自终止的 mangled 形式——给定编码节点的起始位置,文法保证能无歧义地确定节点在哪里结束。这通过"不允许可替换产生式的末尾出现可选或可重复元素"来确保。

解压缩(Decompression)

解压缩同样直接内建于 demangling/解析过程。遇到 backref 时,解码其引用的位置,再用一个临时 demangler/parser 解码该节点的实际内容:

fn demangle_at(&mut pos, mangled, output_string) {
  if is_backref(*pos, mangled) {
    // Read the byte offset of the referenced node and
    // advance `pos` past the backref.
    let mut referenced_pos = decode(pos, mangled);
    demangle_at(&mut referenced_pos, mangled, output_string)
  } else {
    // do regular demangling
  }
}

使用字节偏移作为 backref 键(本方案的做法),而不是 Itanium mangling 的后序(post-order)遍历索引,有一个好处:demangler 不需要复刻 mangler 的替换索引逻辑——后者可能相当复杂(本 RFC 早期版本提出的压缩方案正是如此)。

实现高效 demangler 的要点

mangling 语法在设计上就允许实现高效的 demangler:

  • 信息顺序一致:mangled 名称中的信息顺序与 unmangled 名称预期包含信息的顺序一致。因此 demangler 可以在解析 mangled 形式的同时直接生成输出,无需在内存中显式实例化 AST。
  • 解压缩同理:解压缩可以在栈之外不分配内存的情况下完成。另一种做法是让 demangler 维护一个简单数组,把 backref 索引映射到已生成输出中的区间;遇到需要展开的 <backref> 时,直接查表并做一次简单的 memcpy。

因此,解析、解压缩和 demangle 可以单遍完成,无需复杂数据结构——这对实现 #[no_std] 或 C 版 demangler 非常有用。(注意 Punycode 会让解码略微复杂,因为它一般需要动态内存分配;但在合理的最大支持长度内可以用栈上缓冲区实现。)

Rust 语言实体到符号名的映射

RFC 建议按以下规则把 Rust 实体映射到 mangled 名:

  • 具名函数、方法和静态项用 <path> 产生式表示。
  • 路径应扎根于最内层的可作为路径根的实体。根可以是 crate-id、固有 impl、trait impl,以及(默认方法内的项)trait 定义。
  • 编译器有权在保留范围内自由选择消歧义索引和命名空间标签,只要保证标识符无歧义。
  • 为节省空间,等于默认值的泛型实参不应编码进符号名。

缺陷与备选方案

Drawbacks(为什么不做?)

新旧方案之间的取舍主要在于:

旧版基于符号哈希的方案很灵活——哈希可以随意更改。也就是说,旧方案中不稳定的部分被很好地封装起来,不会持续破坏外部工具。而本方案暴露了更多信息,因此破坏外部工具的风险更大。

备选方案(Rationale and Alternatives)

RFC 讨论了五个替代方案:

  1. 保留现行方案。它毕竟满足了最低要求。但普遍共识是:人们在 backtrace 或剖析器中看到(demangle 后的)符号名时,常会感到意外和困惑。
  2. 保留现行方案但做清理:让非哈希部分更一致、更具表现力,哈希部分继续作为防符号冲突的安全网,其余部分只供 demangle。缺点是哈希仍不可预测;且若符号要包含更多关于泛型实参的人类可读信息,会变得相当长。
  3. 定义标准化的 pretty-printing 格式,再用 Punycode 编码以满足字符集限制。实现简单,符号名保持一定可读性(但有限,因为所有分隔符会被剥离)。缺点:没有额外压缩的话,符号名会相当长。
  4. 在上一方案基础上应用本文描述的压缩方案。可以做,但复杂度并不比 RFC 提出的方案低。
  5. 定义标准化的 pretty-printing 格式,用 zstd 压缩(用针对 Rust 符号专门训练的字典),再以 base63 编码结果。实现简单但完全丧失人类可读性;压缩效果如何也不清楚。它还会把 zstd 规范及预训练字典拽进 mangling 规范。

既有实践参考(Prior Art)

  • 拥有公开规范的现代 mangling 方案之一是 GCC 工具链使用的 Itanium C++ ABI 方案。本 RFC 的早期版本与 Itanium mangling 非常接近,但最终版本只保留了标识符的游程编码和少量标记基本类型的字面量。Itanium 方案因文法庞大且有两套独立压缩机制而被批评为过度复杂。
  • 用 Punycode 处理 Unicode 标识符的想法来自 Swift 编程语言的 mangling 方案。

作为仓库内的补充佐证,text/2457-non-ascii-idents.md 在未决问题中明确列出了"编译器采用哪种 name mangling 方案"这一问题,说明非 ASCII 标识符的支持与符号修改方案是相互纠缠的两个话题——这也正是 RFC 2603 引入 Punycode 编码的动因之一。

未决问题

Punycode 还是 UTF-8?

在 pre-RFC 阶段有人建议:在允许的平台上,Unicode 标识符应该用 UTF-8 而不是 Punycode 编码(GCC、Clang、MSVC 似乎都这么做)。作者对此难以抉择,以下是影响最终决定的论点:

  • 用 UTF-8 代替 Punycode 会让含非 ASCII 标识符的 mangled 字符串更可读;对 demangled 字符串则没有区别。
  • Punycode 支持是不可选的:某些平台只允许非常有限的符号字符集。若在某些平台用 UTF-8、在另一些平台用 Punycode,将更难预测给定项的符号名长什么样。
  • Punycode 的编码与解码对 mangler 和 demangler 而言运行时开销更大。
  • 一旦 demangler 支持了 Punycode,再支持两种编码并不费力:u 标识符前缀告诉 demangler 是否为 Punycode;否则可直接假定 UTF-8(UTF-8 已包含 ASCII)。

最终更新:RFC 建议 demangler 必须支持 Punycode 编码的标识符,但(目前)由编译器实现决定在给定平台上是否使用它。如果 Rust 将来定义稳定 ABI,这个问题需要重新审视。

是否为函数符号编码参数类型?

有人建议函数和方法的参数类型也应编码进 mangled 形式。这对符号唯一性并非必要,但能作为一道额外的安全网,防止 ABI 相关的静默错误(函数定义与其调用方对参数做出不同假设)。RFC 不提议这么做,原因如下:

  • Rust 通过 crate 元数据确保这种情况不会发生;
  • 会让符号名更长;
  • 该安全网只能捕获部分而非全部 ABI 相关错误。

最终更新:RFC 建议不将参数类型编码进函数和方法符号。符号名已经因编码额外信息而显著变长;而且对 Rust 而言,这道针对 ABI 不匹配的额外安全网不如对没有库/crate 元数据概念的语言那么重要。

附录 A:建议的 Demangling 形式

RFC 建议把名字 demangle 成与源码、编译器错误消息和 rustdoc 中一致的 Rust 语法形式:

  • 路径组件以 :: 分隔。
  • 若路径根是 <crate-id>,打印为 crate 名。若上下文需要正确性,也可以打印 crate 消歧义符,例如 std[a0b1c2d3]::collections::HashMap(其中 a0b1c2d3 是消歧义符)。通常为了可读性可以省略消歧义符。
  • 若路径根是 impl,打印为 <SelfType>(固有 impl)或 <SelfType as Trait>(trait impl),与编译器在错误消息中的做法一致。AST 节点中包含的 <impl-path> 通常应省略。
  • 泛型实参列表 demangle 为 <T1, T2, T3>。
  • 标识符可以带数字消歧义符(<disambiguator> 产生式)。其语法形式映射为数字索引:无消歧义符时索引为 0;s_ 形式索引为 1;s<base-62-digit>_ 形式索引为 <base-62-digit> + 2。消歧义符的建议 demangling 是 [<index>]。不过为可读性,消歧义符通常应整体省略;索引为零的消歧义符总是可以省略。
  • 例外是闭包:它们没有名字,消歧义符是唯一标识。闭包的建议 demangling 为 {closure}[<index>]。

附录 B:完整示例对照

以下示例假定都定义在名为 mycrate[1234] 的 crate 中。

自由项

mod foo {
  mod bar {
    fn baz() {}
  }
}
  • unmangled:mycrate::foo::bar::baz
  • mangled:_RNvNtNtCs1234_7mycrate3foo3bar3baz

固有方法内定义的项

struct Foo<T>(T);

impl<T> Foo<T> {
  pub fn bar<U>(_: U) {
    static QUUX: u32 = 0;
    // ...
  }
}
  • unmangled:<mycrate::Foo<_>>::bar::QUUX
  • mangled:_RNvNvMCs1234_7mycrateINtCs1234_7mycrate3FoopE3bar4QUUX

trait 方法内定义的项

struct Foo<T>(T);

impl<T> Clone for Foo<T> {
  fn clone(&self) -> Self {
    static QUUX: u32 = 0;
    // ...
  }
}
  • unmangled:<mycrate::Foo<_> as std::clone::Clone>::clone::QUUX
  • mangled:_RNvNvXCs1234_7mycrateINtCs1234_7mycrate3FoopENtNtC3std5clone5Clone5clone4QUUX

静态项初始化器内定义的项

pub static QUUX: u32 = {
  static FOO: u32 = 1;
  FOO + FOO
};
  • unmangled:mycrate::QUUX::FOO
  • mangled:_RNvNvCs1234_7mycrate4QUUX3FOO

由含替换的前缀构造的压缩前缀(TODO)

  • unmangled:mycrate::foo<mycrate::bar,mycrate::bar::baz>
  • mangled:_RINvCs1234_7mycrate3fooNvB4_3barNvBn_3bazE

渐进式类型压缩

  • unmangled:std::foo<(std::Bar,std::Bar),(std::Bar,std::Bar)>
  • mangled:_RINxC3std3fooTNyB4_3BarBe_EBd_E

附录 C:变更日志要点

RFC 在演进过程中做了大量修订,要点包括:删除了引言中对 Itanium mangling 的提及;弱化了"可预测性"目标;移除了"不提供 lifetime mangling"这一非目标;新增"不标准化 demangled 形式"的非目标;规范与示例更新为 eddyb 提议的新文法;impl 消歧义策略从"参数约束"改为"使用 impl 路径";更新了 prior art 部分以说明本 RFC 并非 Itanium mangling 的改编;移除了"复杂度"这一 drawback;允许标识符以数字开头;使 <binder> 在 <fn-sig> 与 <dyn-bounds> 中可选;扩展 <const-data> 以支持 bool、char 与负整数值;移除常量占位符中的类型;允许厂商特定后缀等。

结语与延伸阅读

RFC 2603 勾勒的这套 _R 前缀符号体系,如今已成为 Rust 生态中 demangler(rustc-demangle、各种调试工具)的事实基础,也是讨论"稳定 Rust ABI"时绕不开的设计基石。它的价值在于:把符号名从"防冲突的黑盒"变成"可解码的结构化文本",同时通过压缩机制控制长度、通过受限字符集保证平台可移植性。

如果你想继续深入:

  • 了解 RFC 流程本身,可阅读仓库根目录的 README.md,其中描述了 RFC 从提交、讨论到 FCP 合并的完整生命周期;
  • 想了解旧版哈希符号方案的历史背景(如 -C metadata 与符号哈希),可参考 text/0109-remove-crate-id.md 的 "Symbol mangling" 一节;
  • 想探索非 ASCII 标识符与符号修改的关联,可阅读 text/2457-non-ascii-idents.md。

对于想亲手验证的读者,可以在本地用 rustc 编译带 #[inline(never)] 的泛型函数并用 nm / objdump 查看符号表,对照本文的 _R 前缀文法逐字节解读——这是理解这套方案最直观的方式。

登录后查看全文
rfcs