LLVM-CXXMAP(1)

✨ llvm-cxxmap — mangled name remapping tool ✨

okay bestie, gather round, because llvm-cxxmap is genuinely one of those little tools that's giving quiet main character energy. It's part of the LLVM fam, and it does fuzzy matching of C++ mangled names. Fr fr. Let's get into it 💅

---

🌸 SYNOPSIS 🌸

llvm-cxxmap [options] symbol-file-1 symbol-file-2

That's it, that's the whole vibe. Two symbol files, some options, boom. 🫶

---

💖 DESCRIPTION 💖

So here's the tea: llvm-cxxmap performs fuzzy matching of C++ mangled names. It doesn't just do a boring exact-string comparison — no ma'am — it uses a file that describes which name components should be considered equivalent. Like, "these two fragments? same thing, bestie." ✨

The symbol files should contain a list of C++ mangled names, one per line.

• Blank lines? Ignored. 🚫
• Lines starting with #? Also ignored. 🚫

The output is a list of pairs of equivalent symbols, one per line, looking like this:

<symbol-1> <symbol-2>

where <symbol-1> is a symbol from symbol-file-1 and <symbol-2> is a symbol from symbol-file-2.

Not me matching symbols that are literally identical — those mappings are omitted, so don't go looking for them, they're not there. 🙈

---

🎀 OPTIONS 🎀

• -remapping-file=file, -r=file — Point at a file containing a list of equivalence rules that should be used to figure out whether two symbols are equivalent. This one is required, bestie, you can't skip it. See REMAPPING FILE down below for the deets. 👑
• -output=file, -o=file — Pick a file to write the list of matched names into. If you don't specify one? It goes to stdout, no cap. 🖨️
• -Wambiguous — Produce a warning if there are multiple equivalent (but distinct) symbols hanging out in symbol-file-2. Lowkey messy of them. ⚠️
• -Wincomplete — Produce a warning if symbol-file-1 contains a symbol that has no equivalent in symbol-file-2. Sad. Tragic, even. 😭

---

🦋 REMAPPING FILE 🦋

The remapping file is a text file full of lines shaped like this:

fragmentkind fragment1 fragment2

where fragmentkind is one of name, type, or encoding — telling you whether the mangled name fragments that follow are <name>s, <type>s, or <encoding>s, respectively. And yes, blank lines and lines starting with # are ignored here too. Consistency icon. ✨

Unmangled C names can be expressed as an encoding that is a (length-prefixed) <source-name>:

# C function "void foo_bar()" is remapped to C++ function "void foo::bar()".
encoding 7foo_bar _Z3foo3barv

For convenience, built-in <substitution>s such as St and Ss are accepted as <name>s — even though technically they are not <name>s. It's giving "rules are more like guidelines." 💅

So, for example, to specify that absl::string_view and std::string_view should be treated as equivalent, you could use this remapping file:

# absl::string_view is considered equivalent to std::string_view
type N4absl11string_viewE St17basic_string_viewIcSt11char_traitsIcEE

# std:: might be std::__1:: in libc++ or std::__cxx11:: in libstdc++
name St St3__1
name St St7__cxx11

NOTE: Symbol remapping is currently only supported for C++ mangled names following the Itanium C++ ABI mangling scheme. This covers all C++ targets supported by Clang other than Windows targets. So if you're on a Windows target, this is not the moment, bestie. 🚫🪟

---

👑 AUTHOR 👑

Maintained by the LLVM Team (https://llvm.org/). Absolute legends, honestly. 🫶

---

🌈 COPYRIGHT 🌈

2003-2024, LLVM Project. Yeah, they've been at this a while. 💜

---

okay that's the whole page!! go forth and remap those mangled names, you've totally got this 💖✨🦋

this cutie was brought to you by LLVM 15, dated 2024-04-14 — mwah, bye bestie! 💅🎀🌸