1llvm-cxxmap - Mangled name remapping tool
2=========================================
3
4SYNOPSIS
5--------
6
7:program:`llvm-cxxmap` [*options*] *symbol-file-1* *symbol-file-2*
8
9DESCRIPTION
10-----------
11
12The :program:`llvm-cxxmap` tool performs fuzzy matching of C++ mangled names,
13based on a file describing name components that should be considered equivalent.
14
15The symbol files should contain a list of C++ mangled names (one per line).
16Blank lines and lines starting with ``#`` are ignored. The output is a list
17of pairs of equivalent symbols, one per line, of the form
18
19.. code-block:: none
20
21  <symbol-1> <symbol-2>
22
23where ``<symbol-1>`` is a symbol from *symbol-file-1* and ``<symbol-2>`` is
24a symbol from *symbol-file-2*. Mappings for which the two symbols are identical
25are omitted.
26
27OPTIONS
28-------
29
30.. program:: llvm-cxxmap
31
32.. option:: -remapping-file=file, -r=file
33
34 Specify a file containing a list of equivalence rules that should be used
35 to determine whether two symbols are equivalent. Required.
36 See :ref:`remapping-file`.
37
38.. option:: -output=file, -o=file
39
40 Specify a file to write the list of matched names to. If unspecified, the
41 list will be written to stdout.
42
43.. option:: -Wambiguous
44
45 Produce a warning if there are multiple equivalent (but distinct) symbols in
46 *symbol-file-2*.
47
48.. option:: -Wincomplete
49
50 Produce a warning if *symbol-file-1* contains a symbol for which there is no
51 equivalent symbol in *symbol-file-2*.
52
53.. _remapping-file:
54
55REMAPPING FILE
56--------------
57
58The remapping file is a text file containing lines of the form
59
60.. code-block:: none
61
62  fragmentkind fragment1 fragment2
63
64where ``fragmentkind`` is one of ``name``, ``type``, or ``encoding``,
65indicating whether the following mangled name fragments are
66<`name <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.name>`_>s,
67<`type <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.type>`_>s, or
68<`encoding <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.encoding>`_>s,
69respectively.
70Blank lines and lines starting with ``#`` are ignored.
71
72For convenience, built-in <substitution>s such as ``St`` and ``Ss``
73are accepted as <name>s (even though they technically are not <name>s).
74
75For example, to specify that ``absl::string_view`` and ``std::string_view``
76should be treated as equivalent, the following remapping file could be used:
77
78.. code-block:: none
79
80  # absl::string_view is considered equivalent to std::string_view
81  type N4absl11string_viewE St17basic_string_viewIcSt11char_traitsIcEE
82
83  # std:: might be std::__1:: in libc++ or std::__cxx11:: in libstdc++
84  name St St3__1
85  name St St7__cxx11
86
87.. note::
88
89  Symbol remapping is currently only supported for C++ mangled names
90  following the Itanium C++ ABI mangling scheme. This covers all C++ targets
91  supported by Clang other than Windows targets.
92