It’s been a long time coming (as in over a year), but this project is finally in a state where I’m not completely embarrassed to showcase it.
This is a proof of concept for a Debug Adapter Protocol client for Kakoune. Before explaining what the plugin does, though, it may help to explain what the Debug Adapter Protocol even is first.
Essentially, the Debug Adapter Protocol (DAP) is a JSON-based protocol created by Microsoft to represent a generic interface through which editors can communicate with debuggers. The purpose is so that one standardized interface can be used for an editor to communicate with a variety of different debuggers for a variety of different languages, theoretically allowing for an editor to implement the protocol once and support debugging for every language that has a debug adapter. Clients to support this protocol have been developed for a number of editors, like Visual Studio Code, Vim, Atom, Sublime Text, Emacs, and now Kakoune.
kak-dap
essentially tries to simulate a debugger UI by employing three buffers shown in three clients - a code buffer, a stack trace buffer, and a variables buffer, and employing the terminal
command to run the debuggee in an external terminal. Breakpoints are toggled in the code buffer, and the stack trace and variables buffer appear when the debugger is started, and disappear when the debugger is stopped. The stack trace buffer and variables buffer will be updated with the current stack trace and variable hierarchy respectively whenever the debugger hits a breakpoint or some other stopping point, and the code buffer will automatically jump to the current line. The variables buffer additionally allows for expanding and collapsing the variable hierarchy by pressing Enter to expand a variable on the current line.
Like Visual Studio Code, kak-dap
relies on JSON files to configure the debug adapter for the current project. Every project that is to be debugged must contain a .kak-dap.json
file in its root directory, so that kak-dap
can know how to debug your program.
In order to get an idea of what it looks like, here’s a demo of kak-dap
debugging the Python demo script located in the repo:
https://asciinema.org/a/fjU1GBrXSxplfP6lEo7cqYcj9
Note that since kak-dap
can’t make any assumptions about what windowing system you’re using, the default layout is fairly primitive. It’s fairly easy to change the layout, and I have done so for the demo above. More details on how to do that can be found here: Customizing debugger UI - jdugan6240/kak-dap - Codeberg.org
This plugin has been tested with adapters that debug Python, C, C++, and Rust, although it likely works with some others.
At this point, kak-dap
is currently very limited, and only implements a small subset of the DAP. Notably, it doesn’t support the following:
- Multiple threads (so I wouldn’t try debugging Kakoune with this)
- Function/Exception/Conditional breakpoints (line breakpoints only)
- Expanding evaluation results (they’re currently shown in an
info
box) - Attaching to already-running debuggees (only launching a new debuggee is supported)
- Debug adapters that communicate over TCP/IP instead of stdio
- Probably a couple dozen other things I haven’t thought of
Like kak-lsp
, this is a Rust plugin, so a fairly recent version of Rust will be needed to compile this. I currently don’t have any binaries to download, but I am working on making something happen on that front. More information about building and running the plugin can be found in the project README and wiki. I have tried to make the documentation fairly comprehensive, but if there’s something I missed, please let me know.
This was my very first Rust project, and also my first Kakoune-related project of this scale, so it has been a massive learning experience. It is also very likely to be extremely buggy, given my unfamiliarity with Rust. Any and all feedback is appreciated - feature requests, bug reports, pull requests, code reviews, etc.