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