Compare C++ Symbols Across ABI Names with llvm-cxxmap

llvm-cxxmap-18 compares two lists of mangled C++ names and tells you which pairs the ABI still treats as the same type underneath. Allow 10 to 15 minutes for a small comparison and a review of the output. It is most useful when a library's spelling of std:: shifts between a libc++ and libstdc++ namespace.

This guide uses Ubuntu's llvm-18 package, version 18.1.3. The local manual page is labelled LLVM 15, so the examples below are checked against the installed 18.1.3 executable as well as the documented syntax.

1. Check the installed tool

Start by confirming which executable will run. No elevated privileges are needed. The tool reads ordinary text files and writes either standard output or a file you own.

$ command -v llvm-cxxmap-18
/usr/bin/llvm-cxxmap-18
$ llvm-cxxmap-18 --version
Ubuntu LLVM version 18.1.3
  Optimized build.

The command requires exactly two symbol-file arguments and a remapping file. Do not confuse this with a general demangler: the inputs are mangled names, one per line, not compiler output containing extra columns.

2. Prepare the two symbol lists

Put one Itanium ABI mangled name on each line. Blank lines and lines beginning with # are ignored. In this example, the first list contains an inline namespace spelling and the second contains the ordinary standard-library spelling.

$ cat old-symbols.txt
_ZNSt3__16vectorIiSaIiEEC1Ev
_ZN3foo3barEv
_ZN3missingEv
$ cat new-symbols.txt
_ZNSt6vectorIiSaIiEEC1Ev
_ZN3foo3bazEv

Tip: keep the files as evidence of the comparison. Avoid feeding nm output directly if it includes addresses, symbol types or demangled text. Extract only the mangled-name column first, then inspect a few lines before running the comparison.

3. Describe equivalent name fragments

Create a remapping file that states which encoded fragments may be treated as equivalent. Each rule has a kind followed by two fragments. The kind is name, type or encoding.

$ cat > remapping.txt <<'EOF'
# std:: may be encoded with libc++'s inline namespace.
name St St3__1
EOF

Warning: do not guess at lengths or fragment boundaries. A malformed rule stops the command with a non-zero status.

4. Run the comparison to standard output

Use the short -r option or the long --remapping-file spelling. The first name in each output pair comes from the first input file; the second comes from the second input file.

$ llvm-cxxmap-18 -r remapping.txt old-symbols.txt new-symbols.txt
_ZNSt3__16vectorIiSaIiEEC1Ev _ZNSt6vectorIiSaIiEEC1Ev

Checkpoint: the unmatched foo and missing names do not appear because no equivalent was found in the second file. There is no progress display. Treat a quiet command with no pairs as a result to investigate, not automatically as an error.

5. Save the report without overwriting an old one

Use -o or --output when another process needs a report file. Shell redirection and the --output option both write state, so choose a new destination when the existing report matters.

$ llvm-cxxmap-18 --remapping-file=remapping.txt \
    --output=matches.txt old-symbols.txt new-symbols.txt
$ sed -n '1,20p' matches.txt
_ZNSt3__16vectorIiSaIiEEC1Ev _ZNSt6vectorIiSaIiEEC1Ev

For a replace-in-place workflow, write to a temporary file in the same directory, check it, then move it over the old report:

$ llvm-cxxmap-18 -r remapping.txt -o matches.txt.new old-symbols.txt new-symbols.txt
$ test -s matches.txt.new && mv matches.txt.new matches.txt

If the command fails, the old report remains untouched. Remove an unwanted temporary file only after checking its path. That deletion is irreversible; no sudo is required for this workflow.

6. Turn on warnings while reviewing coverage

-Wincomplete warns when a symbol from the first file has no equivalent in the second. -Wambiguous warns when a first-file symbol has multiple equivalent, distinct candidates in the second. These warnings go to standard error, while matched pairs remain on standard output.

$ llvm-cxxmap-18 -r remapping.txt -Wincomplete \
    old-symbols.txt new-symbols.txt
_ZNSt3__16vectorIiSaIiEEC1Ev _ZNSt6vectorIiSaIiEEC1Ev
warning: old-symbols.txt:2: no new symbol matches old symbol _ZN3foo3barEv
warning: old-symbols.txt:3: no new symbol matches old symbol _ZN3missingEv

Warning text includes filenames and line numbers, so the exact wording changes with your paths and inputs. Capture both streams separately in automation if a warning should fail a review:

$ llvm-cxxmap-18 -r remapping.txt -Wincomplete \
    old-symbols.txt new-symbols.txt >matches.txt 2>warnings.txt
$ test ! -s warnings.txt && echo "no incomplete matches"

7. Check the important boundaries

The documented support is for C++ names using the Itanium C++ ABI. It does not make Windows-target mangling comparable. If the lists came from different toolchains, first establish that they use compatible mangling and that your remapping rules describe a real ABI difference.

The manual says identical mappings are omitted. On this installed 18.1.3 binary, an identical line in both input files was observed in the output as an identity pair. If your consumer needs only changed names, filter identity pairs after reviewing the raw report:

$ awk '$1 != $2' matches.txt > changed-matches.txt
$ sed -n '1,20p' changed-matches.txt

Warning: keep the unfiltered report beside the filtered one when the comparison is used for an audit. Do not treat a successful exit status as proof that every match is semantically correct. Review representative pairs and the remapping rules, especially before using the result to drive a binary-compatibility decision.

Done means