docs/CommandGuide/llvm-cxxmap.rst

   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.