Tracking issue for RFC 2603, "Rust Symbol Mangling (v0)"

[Centril]

This is a tracking issue for the RFC "Rust Symbol Mangling (v0)" (rust-lang/rfcs#2603).

Current status:

Since #90128, you can control the mangling scheme with -C symbol-mangling-version, which can be:

• legacy: the older mangling version, still the default currently
  • explicitly specifying this is unstable-only and also requires -Z unstable-options
    (to allow for eventual removal after v0 becomes the default)
• v0: the new RFC mangling version, as implemented by Introduce Rust symbol mangling scheme. #57967

(Before #90128, this flag was the nightly-only -Z symbol-mangling-version)

To test the new mangling, set RUSTFLAGS=-Csymbol-mangling-version=v0 (or change rustflags in .cargo/config.toml). Please note that only symbols from crates built with that flag will use the new mangling, and that tool support (e.g. debuggers) will be limited initially, until everything is upstreamed. However, RUST_BACKTRACE and rustfilt should work out of the box with either mangling version.

Steps:

• Implement the RFC (Introduce Rust symbol mangling scheme. #57967 + Support demangling the new Rust mangling scheme (v0). rustc-demangle#23)
• Upstream C implementation of the demangler to:
  • binutils/gdb (GNU libiberty)
    • [PATCH] Move rust_{is_mangled,demangle_sym} to a private libiberty header.
      committed as gcc-mirror/gcc@979526c
    • [PATCH] Simplify and generalize rust-demangle's unescaping logic.
      committed as gcc-mirror/gcc@42bf58b
    • [PATCH] Remove some restrictions from rust-demangle.
      committed as gcc-mirror/gcc@e1cb00d
    • [PATCH] Refactor rust-demangle to be independent of C++ demangling.
      (original submission) committed as gcc-mirror/gcc@32fc371
    • [PATCH] Support the new ("v0") mangling scheme in rust-demangle.
      (original submission) committed as gcc-mirror/gcc@8409649
  • Linux perf (through binutils 2.36 and/or libiberty 11.0, or later versions - may vary between distros)
  • valgrind
• Implement demangling support in LLVM, including lldb, lld, llvm-objdump, llvm-nm, llvm-symbolizer, llvm-cxxfilt
• Resolve issue around rustc generating invalid symbol names (v0 mangled symbol doesn't match specification nor can it be demangled with rustfilt or c++filt #83611)
• Adjust documentation (see instructions on rustc-guide)
• Stabilization PR (see instructions on rustc-guide)

Unresolved questions:

• Punycode vs UTF-8, some prior discussion in Ident mangling and unicode. #7539
• Encoding parameter types for function symbols

Desired availability of tooling:

Linux:

• Tools: binutils, gdb, lldb, perf, valgrind

Distro	binutils1	gdb2	lldb3	perf4	valgrind5
Debian (latest stable): 13	2.44 ✅	16.3 ✅	19.0 ✅	6.12 ❌	3.24 ✅
Arch	2.45 ✅	16.3 ✅	21.1 ✅	6.17 ✅	3.25 ✅
Ubuntu (latest release): 25.10	2.45 ✅	16.3 ✅	20.0 ✅	6.17 ✅	3.25 ✅
Ubuntu (latest LTS): 24.04	2.42 ✅	15.0 ✅	18.0 ✅	6.8 ❌	3.22 ✅
Fedora (latest release): 42	2.44 ✅	16.2 ✅	20.1 ✅	6.14 ❌	3.24 ✅
Alpine (latest release): 3.22	2.44 ✅	15.2 ✅	20.1 ✅	6.15 ❌	3.25 ✅

Windows:

Windows does not have support for demangling either legacy or v0 Rust symbols and requires debuginfo to load the appropriate function name. As such, no special support is required.

macOS:

• Xcode lldb / Xcode debugger: v0 supported since Xcode 13.
• Xcode c++filt (llvm-cxxfilt): v0 supported since Xcode 13 (note: remember to add extra _ in front of symbols to match Mach-O convention).
• Xcode objdump --demangle: v0 supported since Xcode 13.
• ld -demangle: Does not support v0.
• System Crash Reporter: Does not support v0.
• dtrace / Instruments.app (CoreSymbolication.framework): Does not support v0.
• dsymutil: Relies on DWARF debuginfo, does not demangle.
• backtrace_symbols / -[NSException callStackSymbols]: Does not demangle.

Footnotes

1. https://github.com/rust-lang/rust/issues/60705#:~:text=However%2C%20looking%20closer%20at%20how%20it%27s%20driven%2C%20Rust%20v0%20support%20seems%20to%20%22just%22%20require%20libbfd%20from%20binutils%202.36%20(or%20later) ↩

2. https://sourceware.org/bugzilla/show_bug.cgi?id=27194 ↩

3. https://github.com/llvm/llvm-project/commit/0a2d4f3f24a377dc7d3cbed16d30603dc27554a8 ↩

4. https://github.com/rust-lang/rust/issues/60705#:~:text=The%20patches%20have%20been%20included%20into%20Linux%20v6.16%3A%0Ahttps%3A//lore.kernel.org/lkml/20250603203501.1961487%2D1%2Dacme%40kernel.org/ ↩

5. https://valgrind.org/docs/manual/dist.news.html#:~:text=*%C2%A0%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%C2%A0CORE%C2%A0CHANGES%C2%A0%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D-,*%C2%A0Fix%C2%A0Rust%C2%A0v0%C2%A0name%C2%A0demangling.,-*%C2%A0The%C2%A0Linux%C2%A0rseq ↩

[eddyb]

cc @rust-lang/compiler

I'd add this as an unresolved question: rust-lang/rfcs#2603 (comment)

I'd rather change the grammar now, if ever, before merging #57967.

[michaelwoerister]

I think the Punycode vs UTF-8 and Encoding parameters types for function symbols questions are actually resolved. The RFC text contains a recommendation on what the resolution should look like (since before the motion to merge) and nobody objected.

[eddyb]

I tried the "type/value namespace" shorthands, and this is what I got, stats-wise:
(apologies for having two tables, but it was hard to combine them further)

986807 symbols: sizes and compression ratios (▶)

v0 without shorthands (types use Nt and values use Nv)

	legacy	mw	▶	mw + compress	v0	▶	v0 + compress
min	30	25	0.97x	25	25	0.96x	25
avg	81	313	1.46x	193	318	1.47x	194
max	688	13409	14.83x	1115	13759	15.24x	1105
total	76.6MiB	295.4MiB	1.62x	182.0MiB	300.2MiB	1.64x	183.5MiB

v0 with shorthands (types use Z and values use V)

	legacy	mw	▶	mw + compress	v0	▶	v0 + compress
min	30	25	0.97x	25	24	0.96x	24
avg	81	313	1.46x	193	303	1.48x	184
max	688	13409	14.83x	1115	12925	14.99x	1047
total	76.6MiB	295.4MiB	1.62x	182.0MiB	285.5MiB	1.64x	173.9MiB

So that's around 5% reduction, kinda nice, but not that much.

[robinmoussu]

I just opened a bug in compiler-explorer because I noticed collision in the demangled name of different monomorphisation of the same function. As far as I understand, the current mangling scheme of rust still use the v1 witch doesn't contains the required information, while this proposed v2 would solved it? Did I correctly understood what the current situation is?