Introducing kak-dap - an experimental Debug Adapter Protocol client for Kakoune

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.

10 Likes

cool idea! thanks for sharing! I’ll try to check this out next week :slight_smile:

1 Like

This is awesome! Thanks for making it. It’s looking like using this to debug NodeJS is going to be an uphill battle, but I will give it a try soon.

I haven’t yet figured out what the maintainers of this project are suggesting for DAP clients that don’t implement their extensions, so I’ll link the discussion here in case anyone has some insight: DAP documentation · Issue #902 · microsoft/vscode-js-debug · GitHub

1 Like

Thanks for checking it out! FWIW, kak-dap is undergoing a near-complete rewrite ATM, because while it does work in its current state, the overall architecture of the Rust code is awful (and I’m not the biggest fan of Rust in general, after having tried it). It’s slow going, as I don’t have a ton of free time to work on this anymore, but once it’s done maintaining this will be a lot easier.

I did have a look at the discussion you posted, and it seems that the adapter in question requires a custom message during startup for handling multiple child sessions, meaning it isn’t actually DAP compliant and kak-dap wouldn’t be able to use it. Debugpy (the Python debug adapter) does something similar when a child process is spawned from the debuggee, but that’s thankfully behavior that can be disabled. I would indeed suggest using the vscode-node-debug2 adapter instead (incidentally that’s what vimspector (a DAP client for Vim) uses for node).

it isn’t actually DAP compliant

That seems to be the consensus - hopefully soon the DAP and nodejs-debugger teams at Microsoft can get together and figure it out :sweat_smile:

Sorry to hear that Rust is giving you such a headache! I was looking through the issues and saw that you considered Python until it became clear the performance just wasn’t there. I write JS for a living and I’m constantly frustrated with how slow everything feels, so I hope it’s worth it for you to hang in there.

I don’t spend a lot of time looking at code outside work myself, but I’d be happy to try and contribute if there are any tasks that don’t require deep knowledge of the language. Let me know if there’s anything like that on your plate :+1:

Notice: development on this plugin, as well as all my other plugins, has moved to Sourcehut:
https://sr.ht/~jdugan6240/kak-plugins/

Work on the kak-dap rewrite has picked up significantly, and I hope to have it working by the end of next month. :slight_smile:

3 Likes