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