13164fcfdSRichard Smithllvm-cxxmap - Mangled name remapping tool 23164fcfdSRichard Smith========================================= 33164fcfdSRichard Smith 4a056684cSJames Henderson.. program:: llvm-cxxmap 5a056684cSJames Henderson 63164fcfdSRichard SmithSYNOPSIS 73164fcfdSRichard Smith-------- 83164fcfdSRichard Smith 93164fcfdSRichard Smith:program:`llvm-cxxmap` [*options*] *symbol-file-1* *symbol-file-2* 103164fcfdSRichard Smith 113164fcfdSRichard SmithDESCRIPTION 123164fcfdSRichard Smith----------- 133164fcfdSRichard Smith 143164fcfdSRichard SmithThe :program:`llvm-cxxmap` tool performs fuzzy matching of C++ mangled names, 153164fcfdSRichard Smithbased on a file describing name components that should be considered equivalent. 163164fcfdSRichard Smith 173164fcfdSRichard SmithThe symbol files should contain a list of C++ mangled names (one per line). 183164fcfdSRichard SmithBlank lines and lines starting with ``#`` are ignored. The output is a list 193164fcfdSRichard Smithof pairs of equivalent symbols, one per line, of the form 203164fcfdSRichard Smith 213164fcfdSRichard Smith.. code-block:: none 223164fcfdSRichard Smith 233164fcfdSRichard Smith <symbol-1> <symbol-2> 243164fcfdSRichard Smith 253164fcfdSRichard Smithwhere ``<symbol-1>`` is a symbol from *symbol-file-1* and ``<symbol-2>`` is 263164fcfdSRichard Smitha symbol from *symbol-file-2*. Mappings for which the two symbols are identical 273164fcfdSRichard Smithare omitted. 283164fcfdSRichard Smith 293164fcfdSRichard SmithOPTIONS 303164fcfdSRichard Smith------- 313164fcfdSRichard Smith 323164fcfdSRichard Smith.. program:: llvm-cxxmap 333164fcfdSRichard Smith 343164fcfdSRichard Smith.. option:: -remapping-file=file, -r=file 353164fcfdSRichard Smith 363164fcfdSRichard Smith Specify a file containing a list of equivalence rules that should be used 373164fcfdSRichard Smith to determine whether two symbols are equivalent. Required. 383164fcfdSRichard Smith See :ref:`remapping-file`. 393164fcfdSRichard Smith 403164fcfdSRichard Smith.. option:: -output=file, -o=file 413164fcfdSRichard Smith 423164fcfdSRichard Smith Specify a file to write the list of matched names to. If unspecified, the 433164fcfdSRichard Smith list will be written to stdout. 443164fcfdSRichard Smith 453164fcfdSRichard Smith.. option:: -Wambiguous 463164fcfdSRichard Smith 473164fcfdSRichard Smith Produce a warning if there are multiple equivalent (but distinct) symbols in 483164fcfdSRichard Smith *symbol-file-2*. 493164fcfdSRichard Smith 503164fcfdSRichard Smith.. option:: -Wincomplete 513164fcfdSRichard Smith 523164fcfdSRichard Smith Produce a warning if *symbol-file-1* contains a symbol for which there is no 533164fcfdSRichard Smith equivalent symbol in *symbol-file-2*. 543164fcfdSRichard Smith 553164fcfdSRichard Smith.. _remapping-file: 563164fcfdSRichard Smith 573164fcfdSRichard SmithREMAPPING FILE 583164fcfdSRichard Smith-------------- 593164fcfdSRichard Smith 603164fcfdSRichard SmithThe remapping file is a text file containing lines of the form 613164fcfdSRichard Smith 623164fcfdSRichard Smith.. code-block:: none 633164fcfdSRichard Smith 643164fcfdSRichard Smith fragmentkind fragment1 fragment2 653164fcfdSRichard Smith 663164fcfdSRichard Smithwhere ``fragmentkind`` is one of ``name``, ``type``, or ``encoding``, 673164fcfdSRichard Smithindicating whether the following mangled name fragments are 683164fcfdSRichard Smith<`name <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.name>`_>s, 693164fcfdSRichard Smith<`type <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.type>`_>s, or 703164fcfdSRichard Smith<`encoding <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.encoding>`_>s, 713164fcfdSRichard Smithrespectively. 723164fcfdSRichard SmithBlank lines and lines starting with ``#`` are ignored. 733164fcfdSRichard Smith 74*b6e90a1aSRichard SmithUnmangled C names can be expressed as an ``encoding`` that is a (length-prefixed) 75*b6e90a1aSRichard Smith<`source-name <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.source-name>`_>: 76*b6e90a1aSRichard Smith 77*b6e90a1aSRichard Smith.. code-block:: none 78*b6e90a1aSRichard Smith 79*b6e90a1aSRichard Smith # C function "void foo_bar()" is remapped to C++ function "void foo::bar()". 80*b6e90a1aSRichard Smith encoding 7foo_bar _Z3foo3barv 81*b6e90a1aSRichard Smith 823164fcfdSRichard SmithFor convenience, built-in <substitution>s such as ``St`` and ``Ss`` 833164fcfdSRichard Smithare accepted as <name>s (even though they technically are not <name>s). 843164fcfdSRichard Smith 853164fcfdSRichard SmithFor example, to specify that ``absl::string_view`` and ``std::string_view`` 863164fcfdSRichard Smithshould be treated as equivalent, the following remapping file could be used: 873164fcfdSRichard Smith 883164fcfdSRichard Smith.. code-block:: none 893164fcfdSRichard Smith 903164fcfdSRichard Smith # absl::string_view is considered equivalent to std::string_view 913164fcfdSRichard Smith type N4absl11string_viewE St17basic_string_viewIcSt11char_traitsIcEE 923164fcfdSRichard Smith 933164fcfdSRichard Smith # std:: might be std::__1:: in libc++ or std::__cxx11:: in libstdc++ 943164fcfdSRichard Smith name St St3__1 953164fcfdSRichard Smith name St St7__cxx11 963164fcfdSRichard Smith 973164fcfdSRichard Smith.. note:: 983164fcfdSRichard Smith 993164fcfdSRichard Smith Symbol remapping is currently only supported for C++ mangled names 1003164fcfdSRichard Smith following the Itanium C++ ABI mangling scheme. This covers all C++ targets 1013164fcfdSRichard Smith supported by Clang other than Windows targets. 102