Native debugging

kvim debugs native programs through the Debug Adapter Protocol (DAP). It launches adapters directly without a shell and includes adapter definitions for lldb-dap and gdb -i=dap. Install one of those executables separately, or configure another stdio DAP adapter.

Kvim home

Profiles

Launch and attach profiles keep adapter-specific DAP arguments as structured TOML. This LLDB profile starts a program built in the workspace:

[debug.profiles.cpp]
adapter = "lldb"
request = "launch"

[debug.profiles.cpp.arguments]
program = "${workspace}/build/app.exe"
cwd = "${workspace}"
args = []
stopOnEntry = false

On Linux or macOS, use the executable's native path instead of the .exe suffix. ${workspace} expands to the active workspace root and ${file} to the focused file. Unknown placeholders are rejected. Adapter arguments are not interpreted or rewritten beyond those two substitutions.

An attach profile receives the PID selected from the process picker or supplied directly in the command:

[debug.profiles.native-attach]
adapter = "gdb"
request = "attach"

[debug.profiles.native-attach.arguments]
program = "${workspace}/build/app"

Custom adapters are command-plus-argv definitions:

[debug.adapters.custom]
command = "path-to-adapter"
args = ["--stdio"]

:health lists the active adapter commands and launch/attach profiles. It does not display profile argument values.

Commands and keys

Use bare :debug start to choose and launch a profile; :debug start cpp skips the picker. Bare :debug attach chooses an attach profile, then a running process. Each picker preselects its own most recently selected profile, and both selections persist across restarts. Use :debug attach native-attach to skip directly to the process list. Fuzzy-filter either picker and select with Enter; Esc cancels. Each process result shows the PID and process name on its first row and the full command line on its second row. The explicit :debug attach native-attach 1234 form remains available when the PID is already known. :debug opens the full-screen Debug workspace. Source breakpoints persist with the workspace. :debug profiles opens debug.config.toml in the platform configuration directory, creating it with launch and attach profile examples when it does not exist. Profile changes take effect the next time kvim starts.

kvim loads config.toml first, followed by every regular *.config.toml file in that same directory in lexical filename order. Fragment discovery is non-recursive. Tables are merged recursively; when the same scalar, array, or other non-table value appears more than once, the later file wins. Invalid fragments are reported with their path and skipped without hiding valid files.

Action Command Normal-mode key
Open Debug workspace :debug <space>Do
Toggle breakpoint :debug breakpoint <space>Db
Continue :debug continue <space>Dc
Pause :debug pause <space>Dp
Step over :debug next <space>Dn
Step in :debug step-in <space>Di
Step out :debug step-out <space>DO
Restart :debug restart <space>Dr
Stop/disconnect :debug stop <space>Dx

Visual Studio-style aliases are also available in Normal mode and the Debug workspace:

Action Alias
Continue F5
Stop/disconnect Shift-F5
Restart Ctrl-Shift-F5
Toggle breakpoint F9
Step over F10
Step in F11
Step out Shift-F11
Open Debug workspace F12

The Debug workspace uses tabs for Threads, Stack, Variables, Breakpoints, Console, and Modules. Switch with gt/gT, Tab/Shift-Tab, or 1 through 6; navigate with j/k, gg/G, PageUp/PageDown, and Ctrl-d/Ctrl-u. The Modules tab shows each adapter-reported module's symbol status and symbol-file path when available. In Variables, l loads or expands a value and h collapses it. Enter selects a thread or frame and opens source where available. q or Esc returns to the editor.

When execution stops, kvim jumps to the selected frame automatically only when its canonical source path is inside the active workspace. Explicit frame selection can open external source.

Current boundary

V1 supports adapter-output launches and process-picker or explicit-PID attach. It rejects DAP runInTerminal requests and does not provide interactive debuggee stdin. Adapter messages, variable collections, stack frames, console output, and source paths are bounded; protocol and adapter failures are reported rather than replaced with empty results.