| Richard Smith | 61be1ad | 2018-09-13 20:22:02 +0000 | [diff] [blame] | 1 | llvm-cxxmap - Mangled name remapping tool |
| 2 | ========================================= |
| 3 | |
| 4 | SYNOPSIS |
| 5 | -------- |
| 6 | |
| 7 | :program:`llvm-cxxmap` [*options*] *symbol-file-1* *symbol-file-2* |
| 8 | |
| 9 | DESCRIPTION |
| 10 | ----------- |
| 11 | |
| 12 | The :program:`llvm-cxxmap` tool performs fuzzy matching of C++ mangled names, |
| 13 | based on a file describing name components that should be considered equivalent. |
| 14 | |
| 15 | The symbol files should contain a list of C++ mangled names (one per line). |
| 16 | Blank lines and lines starting with ``#`` are ignored. The output is a list |
| 17 | of pairs of equivalent symbols, one per line, of the form |
| 18 | |
| 19 | .. code-block:: none |
| 20 | |
| 21 | <symbol-1> <symbol-2> |
| 22 | |
| 23 | where ``<symbol-1>`` is a symbol from *symbol-file-1* and ``<symbol-2>`` is |
| 24 | a symbol from *symbol-file-2*. Mappings for which the two symbols are identical |
| 25 | are omitted. |
| 26 | |
| 27 | OPTIONS |
| 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 | |
| 55 | REMAPPING FILE |
| 56 | -------------- |
| 57 | |
| 58 | The remapping file is a text file containing lines of the form |
| 59 | |
| 60 | .. code-block:: none |
| 61 | |
| 62 | fragmentkind fragment1 fragment2 |
| 63 | |
| 64 | where ``fragmentkind`` is one of ``name``, ``type``, or ``encoding``, |
| 65 | indicating 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, |
| 69 | respectively. |
| 70 | Blank lines and lines starting with ``#`` are ignored. |
| 71 | |
| 72 | For convenience, built-in <substitution>s such as ``St`` and ``Ss`` |
| 73 | are accepted as <name>s (even though they technically are not <name>s). |
| 74 | |
| 75 | For example, to specify that ``absl::string_view`` and ``std::string_view`` |
| 76 | should 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. |