demangle-mode
is an Emacs minor mode that automatically demangles
C++, D, and Rust symbols. For example, in this mode:
-
the mangled C++ symbol
_ZNSaIcED2Ev
displays asstd::allocator<char>::~allocator()
-
the mangled C++ symbol
_GLOBAL__I_abc
displays asglobal constructors keyed to abc
-
the mangled D symbol
_D4test3fooAa
displays astest.foo
-
the mangled Rust symbol
_RNvNtNtCs1234_7mycrate3foo3bar3baz
displays asmycrate::foo::bar::baz
Install demangle-mode
from the fantastic
MELPA
repository:
,
.
Or save
demangle-mode.el
somewhere in your Emacs
load-path
,
then use M-x load-library RET demangle-mode RET
to load the package.
Now use M-x demangle-mode
to toggle demangling on or off in any
buffer. Turn on font-lock-mode
as well: demangle-mode
uses this
to stay in sync as buffer contents change.
If you did not install from the
MELPA
repository, add (autoload 'demangle-mode "demangle-mode" nil t)
to
your
Emacs init file
to load demangle-mode
whenever you start Emacs.
If you always want demangling on in certain major modes, add
demangle-mode
to the appropriate major-mode hook, such as:
;; demangle symbols in LLVM bitcode
(add-hook 'llvm-mode-hook #'demangle-mode)
;; demangle symbols in linker error messages
(add-hook 'compilation-minor-mode-hook 'demangle-mode)
File
and
directory
variables allow selective activation. For example, -*- eval: (demangle-mode) -*-
anywhere on the first line of a file will turn on
demangle-mode
for that file only. To activate demangling for all
LLVM assembly files in a specific directory, save the following text
as .dir-locals.el
in that same directory:
((llvm-mode
(eval . (demangle-mode))))
Explore the demangle
customization group for configurable options
that affect this mode’s behavior: M-x customize-group RET demangle RET
. You can choose between two styles of showing mangled/demangled
symbols:
-
show the demangled symbol (read-only) on screen, with the original mangled symbol available as a help message or tooltip; or
-
show the mangled symbol on screen, with the demangled symbol available as a help message or tooltip.
Customization changes the initial style. A mode-specific menu allows
switching between these styles when demangle-mode
is on.
Additionally, you can customize the display face (font, color, underline, etc.) used for highlighting mangled and demangled symbols. The default highlighting face uses a thin gray box or wavy gray underline, depending on the output terminal’s capabilities.
Finally, you can change the set of languages that used mangled symbols. For example, you can add new mangled symbol patterns or change the external commands used to demangle them.
Name mangling is “a way
of encoding additional information in the name of a function,
structure, class or another datatype in order to pass more semantic
information from the compilers to linkers.” For example, a C++
function named print
taking a single int
parameter might mangle to
_Z5printi
. A different print
function taking two chars might
mangle to _Z5printcc
. This lets linkers and other tools distinguish
the two functions.
Most programmer-facing tools demangle symbols back to their
human-readable forms when producing output. Sometimes, though, we must
work with “raw” text containing mangled, hard-to-read symbols. For
example, LLVM assembly source
from the Clang C++ compiler contains many
raw, mangled symbols. It can be useful to demangle these in-place to
make such files easier to read and understand. demangle-mode
scratches that
itch.
demangle-mode
uses
font-lock-mode
to recognize and change the display style of mangled symbols. If you
want demangle-mode
on in some buffer, you should usually turn on
font-lock-mode
as well. If you use demangle-mode
without
font-lock-mode
, demangling happens only when explicitly requested
(e.g., via M-x font-lock-fontify-buffer
).
demangle-mode
sets the
help-echo
and
display
text properties on mangled symbols. This could interfere with other
packages or user actions that set these properties.
demangle-mode
recognizes the popular
Itanium ABI mangling scheme
plus a few Linux/GCC extensions. Adding other mangled forms would be
easy, if needed.
Mangled C++ and D symbols may optionally begin with an extra leading
underscore, as some platforms prefix all symbols in this manner. Both
_Z5printi
and __Z5printi
demangle identically to print(int)
,
regardless of the host platform’s prefixing conventions.
C++ and D demangling uses the
c++filt
command. On GNU systems, this is part of
binutils
. If you need
demangle-mode
at all, you probably have binutils
installed
already.
Rust demangling uses the
rustfilt
command. If you need
Rust demangling, then install rustfilt
using your native package
manager or using cargo
as suggested
here.
The standard
search commands
are unaware of demangled symbol text. If _ZNSaIcED2Ev
is being
displayed as std::allocator<char>::~allocator()
,
incremental search
and related commands will find this text as a match for SaI
but not
for ::
.
When showing the demangled version of a symbol using a boxed face, the right edge of the box is missing in Emacs 24.3 and earlier. This was a known bug; the fix appears in Emacs 24.4 and later.
The faces used for mangled and demangled symbols are identical to each other, and picked somewhat arbitrarily. I welcome suggestions for nicer ways to mark such symbols or distinguish the mangled and demangled variants.
Building atop font-lock-mode
simplifies keeping demangled symbols
current as buffer contents change. However, this may surprise a user
who turns on demangle-mode
without font-lock-mode
, then sees
nothing happen.
Running an external demangler command once per symbol is too slow. Instead, we demangle in asynchronous background processes. This boosts performance but complicates the implementation. Demangling directly within Emacs would be clean and fast. Unfortunately, I know of no pure Emacs Lisp implementation of name demangling and do not wish to create one myself. Demanglers as C libraries do exist, but Emacs offers no in-process way to call into such a library.
Continuous Integration | General Info | Current Versions |
---|---|---|