dap.nvim · Debug & inspect · vimdoc

:help wkddap

Adapters & launch configs for nvim-dap, batteries included

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 *wkddap-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 *wkddap-intro*

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 *wkddap-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 *wkddap-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 *wkddap-config*

  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 inside
ui, 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.

languages is 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, with auto_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.provider selects 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 = false disables the panel UI entirely.

Both providers open on event_initialized and close when the session
terminates or exits. <leader>du / :Dap toggle-ui and <leader>de /
:Dap eval dispatch 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 wkddap reports both the configured preference and the
provider that was actually wired, and flags an unrecognised preference.

5. KEYMAPS *wkddap-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 *wkddap-commands*

One command, :Dap <subcommand> (built via lib.nvim.bindings.usercmd.composer, with
<Tab> completion). Always registered, independent of keymaps.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's gdb -i dap has 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 with a) memory.context_rows rows (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 to Search) 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 shows Memory [stale] like the float. One
view at a time: :Dap memory replaces 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 with Search there.

7. HEALTH CHECK *wkddap-health*

  :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 any registry.validate() errors for
already-enabled languages).

8. ARCHITECTURE *wkddap-architecture*

See the "Architecture" section of README.md for the full module tree.
Each language's adapter and launch configurations live together in a single
lua/wkddap/languages/<lang>.lua module (setup() + load()), required by
adapters/init.lua (via registry.register()) and configurations/init.lua
respectively.
lib.nvim provides notify, cross (platform detection / Mason path
resolution), and normalize (path helpers). ui.nvim's ui.kit backs every
prompt and picker (breakpoint condition/log-point, per-language input,
validation selects) and ui.contextmenu backs the context-menu integration.