libcxxabi/src/demangle/README.txt

   1 Itanium Name Demangler Library
   2 ==============================
   3
   4 Introduction
   5 ------------
   6
   7 This directory contains the generic itanium name demangler
   8 library. The main purpose of the library is to demangle C++ symbols,
   9 i.e. convert the string "_Z1fv" into "f()". You can also use the CRTP
  10 base ManglingParser to perform some simple analysis on the mangled
  11 name, or (in LLVM) use the opaque ItaniumPartialDemangler to query the
  12 demangled AST.
  13
  14 Why are there multiple copies of the this library in the source tree?
  15 ---------------------------------------------------------------------
  16
  17 The canonical sources are in libcxxabi/src/demangle and some of the
  18 files are copied to llvm/include/llvm/Demangle.  The simple reason for
  19 this comes from before the monorepo, and both [sub]projects need to
  20 demangle symbols, but neither can depend on each other.
  21
  22 * libcxxabi needs the demangler to implement __cxa_demangle, which is
  23   part of the itanium ABI spec.
  24
  25 * LLVM needs a copy for a bunch of places, and cannot rely on the
  26   system's __cxa_demangle because it a) might not be available (i.e.,
  27   on Windows), and b) may not be up-to-date on the latest language
  28   features.
  29
  30 The copy of the demangler in LLVM has some extra stuff that aren't
  31 needed in libcxxabi (ie, the MSVC demangler, ItaniumPartialDemangler),
  32 which depend on the shared generic components. Despite these
  33 differences, we want to keep the "core" generic demangling library
  34 identical between both copies to simplify development and testing.
  35
  36 If you're working on the generic library, then do the work first in
  37 libcxxabi, then run the cp-to-llvm.sh script in src/demangle. This
  38 script takes as an optional argument the path to llvm, and copies the
  39 changes you made to libcxxabi over.  Note that this script just
  40 blindly overwrites all changes to the generic library in llvm, so be
  41 careful.
  42
  43 Because the core demangler needs to work in libcxxabi, everything
  44 needs to be declared in an anonymous namespace (see
  45 DEMANGLE_NAMESPACE_BEGIN), and you can't introduce any code that
  46 depends on the libcxx dylib.
  47
  48 FIXME: Now that LLVM is a monorepo, it should be possible to
  49 de-duplicate this code, and have both LLVM and libcxxabi depend on a
  50 shared demangler library.
  51
  52 Testing
  53 -------
  54
  55 The tests are split up between libcxxabi/test/{unit,}test_demangle.cpp, and
  56 llvm/unittest/Demangle. The llvm directory should only get tests for stuff not
  57 included in the core library. In the future though, we should probably move all
  58 the tests to LLVM.
  59
  60 It is also a really good idea to run libFuzzer after non-trivial changes, see
  61 libcxxabi/fuzz/cxa_demangle_fuzzer.cpp and https://llvm.org/docs/LibFuzzer.html.