Repository: rust
Issue: Tracking issue for RFC 2603, "Rust Symbol Mangling (v0)"
Labels: T-compiler,B-unstable,B-RFC-implemented,C-tracking-issue,S-tracking-needs-to-bake

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 #57967

(Before #90128, this flag was the nightly-only `-Z symbol-mangling-version`)

</details>

To test the new mangling, set `RUSTFLAGS=-Csymbol-mangling-version=v0` (or change [`rustflags` in `.cargo/config.toml`](https://doc.rust-lang.org/cargo/reference/config.html#configuration-keys)). 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`](https://crates.io/crates/rustfilt) should work out of the box with either mangling version.

**Steps:**

- [x] Implement the RFC (https://github.com/rust-lang/rust/pull/57967 + https://github.com/alexcrichton/rustc-demangle/pull/23)
- [x] Upstream C implementation of the demangler to:
  - [x] `binutils`/`gdb` (GNU `libiberty`)
    - [x] [[PATCH] Move rust_{is_mangled,demangle_sym} to a private libiberty header.
](https://gcc.gnu.org/pipermail/gcc-patches/2019-June/523011.html) committed as https://github.com/gcc-mirror/gcc/commit/979526c9ce7bb79315f0f91fde0668a5ad8536df
    - [x] [[PATCH] Simplify and generalize rust-demangle's unescaping logic.
](https://gcc.gnu.org/pipermail/gcc-patches/2019-August/527835.html) committed as https://github.com/gcc-mirror/gcc/commit/42bf58bb137992b876be37f8b2e683c49bc2abed
    - [x] [[PATCH] Remove some restrictions from rust-demangle.
](https://gcc.gnu.org/pipermail/gcc-patches/2019-September/530445.html) committed as https://github.com/gcc-mirror/gcc/commit/e1cb00db670e4eb277f8315ecc1da65a5477298d
    - [x] [[PATCH] Refactor rust-demangle to be independent of C++ demangling.
](https://gcc.gnu.org/pipermail/gcc-patches/2019-November/533719.html) ([original submission](https://gcc.gnu.org/pipermail/gcc-patches/2019-October/532388.html)) committed as https://github.com/gcc-mirror/gcc/commit/32fc3719e06899d43e2298ad6d0028efe5ec3024
    - [x] [[PATCH] Support the new ("v0") mangling scheme in rust-demangle.
](https://gcc.gnu.org/pipermail/gcc-patches/2020-November/558905.html) ([original submission](https://gcc.gnu.org/pipermail/gcc-patches/2020-March/542012.html)) committed as https://github.com/gcc-mirror/gcc/commit/84096498a7bd788599d4a7ca63543fc7c297645e
  - [x] Linux `perf` (through `binutils 2.36` and/or `libiberty 11.0`, or later versions - may vary between distros)
  - [x] `valgrind`
- [x] Implement demangling support in LLVM, including lldb, lld, llvm-objdump, llvm-nm, llvm-symbolizer, llvm-cxxfilt
- [x] Resolve issue around rustc generating invalid symbol names (https://github.com/rust-lang/rust/issues/83611)
- [ ] Adjust documentation ([see instructions on rustc-guide][doc-guide])
- [ ] Stabilization PR ([see instructions on rustc-guide][stabilization-guide])

[stabilization-guide]: https://rust-lang.github.io/rustc-guide/stabilization_guide.html#stabilization-pr
[doc-guide]: https://rust-lang.github.io/rustc-guide/stabilization_guide.html#documentation-prs

**Unresolved questions:**

- [x] [Punycode vs UTF-8](https://github.com/rust-lang/rfcs/blob/master/text/2603-symbol-name-mangling-v2.md#punycode-vs-utf-8), some prior discussion in https://github.com/rust-lang/rust/issues/7539
- [x] [Encoding parameter types for function symbols](https://github.com/rust-lang/rfcs/blob/master/text/2603-symbol-name-mangling-v2.md#encoding-parameter-types-for-function-symbols)

**Desired availability of tooling:**

Linux:

- Tools: binutils, gdb, lldb, perf, valgrind

| Distro | Has versions of all tools with support? |
| - | - |
| Debian (latest stable) | ? |
| Arch | ? |
| Ubuntu (latest release) | ? |
| Ubuntu (latest LTS) | ? |
| Fedora (latest release) | ? |
| Alpine (latest release) | ? |

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:

More investigation is needed to determine to what extent macOS system tools already support Rust v0 mangling.