llvm/docs/CommandGuide/llvm-cxxmap.rst

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