doc/wkddap.txt — rendered from the plugin's own vimdoc
*wkddap.txt* Adapters & launch configs for nvim-dap, batteries included *wkddap* *dap.nvim* Author: Stefan Bartl Version: 0.1.0
CONTENTS
1. Introduction .............. |wkddap-intro| 2. Requirements .............. |wkddap-requirements| 3. Installation .............. |wkddap-installation| 4. Configuration ............. |wkddap-config| Panel UI .................. |wkddap-panel-ui| 5. Keymaps ................... |wkddap-keymaps| 6. User commands .............. |wkddap-commands| Memory view ............... |wkddap-memory| 7. Health check .............. |wkddap-health| 8. Architecture .............. |wkddap-architecture|
1. INTRODUCTION
dap.nvim is a config layer on top of nvim-dap (mfussenegger/nvim-dap). It registers adapters and launch configurations for eleven targets (Lua, JavaScript/TypeScript, C/C++, Go, Python, Rust, Zig, Assembly, Bash, C#/.NET, and Chrome-based browser debugging), auto-detects and validates adapter binaries with Mason fallback (auto-installable, see |wkddap-config|), wires up a panel UI (nvim-dap-view by default, nvim-dap-ui opt-in — see |wkddap-panel-ui|) and nvim-dap-virtual-text, and ships user-configurable keymaps, commands, and a which-key group label. Depends on lib.nvim and ui.nvim (deliberate shared dependencies).
2. REQUIREMENTS
- Neovim 0.9 or later
- nvim-dap (mfussenegger/nvim-dap) — required, dap.nvim configures it
- lib.nvim — the :Dap command tree
- ui.nvim — ui.kit backs the breakpoint condition/log-point prompts,
per-language input and validation selects
- Panel UI, optional, pick one: nvim-dap-view (default) or nvim-dap-ui
(opt-in via ui.provider) — see |wkddap-panel-ui|
- Optional: nvim-dap-virtual-text, which-key.nvim, mason.nvim
(for adapter binary installation)
3. INSTALLATION
lazy.nvim:
{
"WKDSteve/dap.nvim",
dependencies = {
"WKDSteve/lib.nvim",
"WKDSteve/ui.nvim",
"mfussenegger/nvim-dap",
"igorlfs/nvim-dap-view",
"theHamsta/nvim-dap-virtual-text",
"jbyuki/one-small-step-for-vimkind",
},
event = "VeryLazy",
opts = {},
}
packer.nvim:
use({
"WKDSteve/dap.nvim",
requires = {
"WKDSteve/lib.nvim",
"WKDSteve/ui.nvim",
"mfussenegger/nvim-dap",
"igorlfs/nvim-dap-view",
"theHamsta/nvim-dap-virtual-text",
"jbyuki/one-small-step-for-vimkind",
},
config = function()
require("wkddap").setup({})
end,
})
4. CONFIGURATION
require("wkddap").setup({
languages = {}, -- empty = all available
ui = {
enable = true,
provider = "dap-view", -- "dap-view"|"dap-ui"|"auto"|"none"
-- dap_view = {}, -- optional, passed to dap-view's setup()
-- dap_ui = {}, -- optional, passed to dapui's setup()
virtual_text = true, -- true | false | options table for its setup()
signs = true,
highlights = true,
},
keymaps = {
enable = true,
prefix = "<leader>d",
},
which_key = {
enable = true,
},
autocmds = {
enable = true,
},
-- Memory view (|wkddap-memory|): 16-byte rows shown above the target
-- when it opens or jumps (0..15; 0 = the target is the first row).
memory = {
context_rows = 4,
},
-- Keyed by nvim-dap adapter name (codelldb, pwa-node, ...); a table is
-- deep-merged over the built-in definition, a function replaces it.
adapters = {},
-- Appended to a language's built-in configurations by default; add
-- `replace = true` to the list to replace them instead.
configurations = {},
-- Install missing required adapters via `:MasonInstall` (mason.nvim
-- must be installed separately).
auto_install = false,
-- Level of nvim-dap's own log file (handed to |dap.set_log_level()|):
-- a vim.log.levels value or a name such as "debug".
log_level = vim.log.levels.WARN,
})
Every key is independently overridable. Unknown keys (top level, or insideui,which_key,autocmds,menu,memory) are ignored with a warning naming the nearest known key; an option table given as a non-table falls back to its defaults. Both are listed again by:checkhealth wkddap.languagesis the one exception: given as a non-table (`languages = "python"), it does NOT fall back to its own default -- that default ({}`) means "every available language", so falling back to it would silently register (and, withauto_install = true, Mason-install) everything instead of what was asked for. It resolves to no real language instead, registering nothing. PANEL UI *wkddap-panel-ui* dap.nvim wires exactly one panel UI — running nvim-dap-view and nvim-dap-ui side by side means two competing layouts and two sets of auto-open/close listeners on the same nvim-dap events.ui.providerselects it: "dap-view" default; wires nvim-dap-view (igorlfs/nvim-dap-view) "dap-ui" wires nvim-dap-ui (rcarriga/nvim-dap-ui); needs nvim-nio "auto" first of the two that is installed, nvim-dap-view winning "none" no panel UI; signs, highlights and virtual text still apply If the preferred provider is not installed but the other is, dap.nvim falls back to it and warns once. Any other value is treated as "dap-view" with a warning.ui.enable = falsedisables the panel UI entirely. Both providers open onevent_initializedand close when the session terminates or exits.<leader>du/:Dap toggle-uiand<leader>de/:Dap evaldispatch through the active provider, so the bindings are unchanged when switching. nvim-dap-ui's eval opens a floating window; nvim-dap-view has no float and adds the expression to its watch list instead.:checkhealth wkddapreports both the configured preference and the provider that was actually wired, and flags an unrecognised preference.
5. KEYMAPS
Installed under the configurable prefix (default "<leader>d") when
|wkddap-config| keymaps.enable is true. Full table in doc/../docs/BINDINGS.md.
<leader>dc Continue
<leader>ds Step Over
<leader>di Step Into
<leader>do Step Out
<leader>dt Terminate
<leader>dr Restart
<leader>db Toggle Breakpoint
<leader>dB Conditional Breakpoint
<leader>dL Log Point
<leader>dl List Breakpoints
<leader>du Toggle UI
<leader>de Evaluate Expression/Selection (normal + visual)
<leader>dR Open REPL
<leader>dm Memory View (prompts for an address or expression)
<leader>dM Memory View in a read-only companion window (prompts)
6. USER COMMANDS
One command, :Dap <subcommand> (built via lib.nvim.bindings.usercmd.composer, with <Tab> completion). Always registered, independent ofkeymaps.enable. *:Dap* :Dap continue *:Dap-continue* :Dap step-over *:Dap-step-over* :Dap step-into *:Dap-step-into* :Dap step-out *:Dap-step-out* :Dap terminate *:Dap-terminate* :Dap restart *:Dap-restart* :Dap toggle-breakpoint *:Dap-toggle-breakpoint* :Dap conditional-breakpoint [condition] *:Dap-conditional-breakpoint* Prompts for the condition when omitted. :Dap log-point [message] *:Dap-log-point* Prompts for the message when omitted. :Dap list-breakpoints *:Dap-list-breakpoints* :Dap toggle-ui *:Dap-toggle-ui* :Dap eval *:Dap-eval* :Dap repl *:Dap-repl* :Dap memory [address-or-expression] *:Dap-memory* Memory view, see |wkddap-memory|. Prompts when omitted. :Dap memory-window [address-or-expression] *:Dap-memory-window* The same view, read-only, in a companion window (a second Neovim in its own terminal), see |wkddap-memory-window|. Prompts when omitted. MEMORY VIEW *wkddap-memory* A hex/bits view of an address range of the running debuggee, in a float, over DAP readMemory/writeMemory of the active nvim-dap session. Needs an adapter with supportsReadMemoryRequest (supportsWriteMemoryRequest for edits); GDB 16.3'sgdb -i daphas both. A literal address ("0x404010") is used as is; anything else ("&buffer", "ptr") is evaluated in the current frame: a value that is an address is used (a pointer's value, as in Visual Studio), otherwise the result's memoryReference. Like Visual Studio's memory window, the view does not start at the target: it opens (and jumps witha)memory.context_rowsrows (default 4, 16 bytes each) above it, rows aligned to 16 bytes, never below address 0, with the cursor on the target byte. The target byte is highlighted (WkddapMemoryTarget, linked toSearch) whenever it is on the page. When that first read does not reach the target (the memory before it cannot be read, or the adapter stops at a region boundary as codelldb does), a second read starts where the first stopped, or at the target itself, instead of showing the error or a page of??. Keys in the view: e, <CR> edit the byte under the cursor (writeMemory, then re-read) <2-LeftMouse> edit that byte; in bits mode flip that bit <Space> flip the bit under the cursor (bits mode) u undo the last write (writes the previous value back) b toggle hex / bits a go to address/expression n, <PageDown> next page p, <PageUp> previous page r refresh q, <Esc> close Edits are byte-wise, so endianness never matters for them; the display is the byte order in memory, bits MSB first. The undo stack is the plugin's own and lives as long as the view. When the session terminates, exits or disconnects (or nvim-dap closes it because the adapter died), the view turns stale (read-only). While a new page is still being read, edits are refused. Full description: docs/FEATURES/MEMORY.md. *wkddap-memory-window*:Dap memory-window(<leader>dM; `require("wkddap.memory").open(target, { companion = true })`) shows the view in a companion window instead of the float: a second Neovim in its own terminal window (lib.nvim.companion; Windows Terminal, $TERMINAL, Terminal.app, ...), for a second monitor. It gets the same lines and highlights after every read and is read-only: no edit keys. Keys there, each running in the main instance: a go to address/expression (asks in the companion) n/p next / previous page b toggle hex / bits r refresh q close the companion The DAP requests, the state and the undo stack stay in the main instance. When the session ends the companion showsMemory [stale]like the float. One view at a time::Dap memoryreplaces an open companion with the float and the other way round. The cursor cannot be moved from the main instance; the target byte is highlighted withSearchthere.
7. HEALTH CHECK
:checkhealth wkddap
Verifies Neovim version, nvim-dap presence, lib.nvim and ui.nvim modules, optional UI companions, per-language adapter availability, and registry state (registry.stats()counts plus anyregistry.validate()errors for already-enabled languages).
8. ARCHITECTURE
See the "Architecture" section of README.md for the full module tree. Each language's adapter and launch configurations live together in a singlelua/wkddap/languages/<lang>.luamodule (setup()+load()), required byadapters/init.lua(viaregistry.register()) andconfigurations/init.luarespectively. lib.nvim provides notify,cross(platform detection / Mason path resolution), andnormalize(path helpers). ui.nvim'sui.kitbacks every prompt and picker (breakpoint condition/log-point, per-language input, validation selects) andui.contextmenubacks the context-menu integration.