246 lines
9.7 KiB
Plaintext
246 lines
9.7 KiB
Plaintext
*turbo-debug.txt* A zero-config debugging experience for Neovim 0.12+
|
|
|
|
==============================================================================
|
|
CONTENTS *turbo-debug-contents*
|
|
|
|
1. Introduction .......................... |turbo-debug-introduction|
|
|
2. Installation .......................... |turbo-debug-installation|
|
|
3. Setup ................................. |turbo-debug.setup|
|
|
4. Debug Mode ............................ |turbo-debug-debug-mode|
|
|
5. Keybindings ........................... |turbo-debug.keys|
|
|
6. Breakpoints ........................... |turbo-debug-breakpoints|
|
|
7. UI Layout ............................. |turbo-debug-layout|
|
|
8. Adapters .............................. |turbo-debug.adapters|
|
|
9. API ................................... |turbo-debug-api|
|
|
10. Troubleshooting ....................... |turbo-debug-troubleshooting|
|
|
|
|
==============================================================================
|
|
1. Introduction *turbo-debug-introduction*
|
|
|
|
turbo-debug.nvim gives you a fully-featured, beautiful debugging experience
|
|
out of one line of config. Under the hood it wires together nvim-dap,
|
|
nvim-dap-ui, nvim-dap-virtual-text, and persistent-breakpoints into a single
|
|
cohesive experience with modal keybindings.
|
|
|
|
Features:
|
|
- Inline virtual text showing variable values in source code
|
|
- Hover inspection with `K`
|
|
- Persistent breakpoints that survive restarts
|
|
- Watch expressions from the code window with `W`
|
|
- Scopes, stacks, REPL, and console panels
|
|
- Modal keybindings active only during debug sessions
|
|
- Help box showing all keybindings
|
|
- Zero-config adapters for 10+ languages
|
|
|
|
==============================================================================
|
|
2. Installation *turbo-debug-installation*
|
|
|
|
Add one line to your init.lua: >lua
|
|
vim.pack.add("swaits/turbo-debug")
|
|
<
|
|
That's it. All dependencies are managed automatically.
|
|
|
|
Requires Neovim >= 0.12.
|
|
|
|
==============================================================================
|
|
3. Setup *turbo-debug.setup*
|
|
|
|
Setup is optional. The plugin works with no configuration. To customize: >lua
|
|
require("turbo-debug").setup({
|
|
help_on_enter = true, -- show help splash on debug mode entry
|
|
quit_exits_mode = true, -- q terminates AND exits debug mode
|
|
builtin_adapters = true, -- register built-in language adapters
|
|
keys = { ... }, -- override modal keybindings
|
|
global_keys = { ... }, -- override always-available keybindings
|
|
adapters = { ... }, -- override or add language adapters
|
|
dapui = { ... }, -- override nvim-dap-ui layout/settings
|
|
virtual_text = { ... }, -- override nvim-dap-virtual-text settings
|
|
})
|
|
<
|
|
*turbo-debug.setup.help_on_enter*
|
|
help_on_enter ~
|
|
Type: boolean, Default: `true`
|
|
Show the help box automatically when entering debug mode.
|
|
|
|
*turbo-debug.setup.builtin_adapters*
|
|
builtin_adapters ~
|
|
Type: boolean, Default: `true`
|
|
Register built-in adapters for supported languages. Set to `false` to
|
|
disable all built-in adapter registration.
|
|
|
|
==============================================================================
|
|
4. Debug Mode *turbo-debug-debug-mode*
|
|
|
|
Press `<leader>dd` to toggle debug mode.
|
|
|
|
Entering debug mode:
|
|
1. Opens nvim-dap-ui with the configured layout
|
|
2. Enables inline virtual text for variable values
|
|
3. Activates modal keybindings (buffer-local)
|
|
4. Shows winbar indicator and help splash (3s)
|
|
|
|
Exiting debug mode (any of):
|
|
- `<leader>dd` again (manual toggle)
|
|
- `q` (terminate session — exits debug mode if `quit_exits_mode`)
|
|
- DAP session ends naturally
|
|
|
|
On exit, everything is restored: keymaps, UI, virtual text, cursor.
|
|
|
|
==============================================================================
|
|
5. Keybindings *turbo-debug.keys*
|
|
|
|
Modal keybindings are active only during debug mode. They shadow editing
|
|
keys you don't need while debugging, but preserve all navigation keys.
|
|
|
|
Default keymap:
|
|
|
|
Key Action Mnemonic ~
|
|
`c` Continue Universal across debuggers
|
|
`s` Step over Step
|
|
`d` Step into Descend into the function
|
|
`r` Step out Return from the function
|
|
`C` Run to cursor Continue to cursor
|
|
`x` Toggle breakpoint X marks the spot
|
|
`X` Conditional breakpoint Shift variant of x
|
|
`D` Clear all breakpoints Delete all
|
|
`W` Watch expr under cursor Watch
|
|
`K` Hover / inspect Matches LSP hover convention
|
|
`E` Eval in REPL Evaluate
|
|
`q` Terminate session Quit debugging
|
|
`R` Restart session Rerun
|
|
`?` Help popup Show keybindings
|
|
|
|
Always available (under `<leader>d` prefix, with which-key support):
|
|
|
|
`<leader>dd` Toggle debug mode
|
|
`<leader>dx` Toggle breakpoint X marks the spot
|
|
`<leader>dX` Conditional breakpoint Shift variant
|
|
`<leader>dD` Clear all breakpoints Delete all
|
|
|
|
Override any key: >lua
|
|
require("turbo-debug").setup({
|
|
keys = { -- modal keys (debug mode only)
|
|
continue = "g",
|
|
step_over = false, -- set to false to disable
|
|
},
|
|
global_keys = { -- always-available keys
|
|
toggle = "<leader>DD",
|
|
breakpoint = "<leader>db",
|
|
},
|
|
})
|
|
<
|
|
Preserved keys (not shadowed):
|
|
- Navigation: `h j k l w b e f F t T / n N 0 ^ $ G g { } % [ ]`
|
|
- Insert: `i a o O` (needed for REPL/terminal)
|
|
- Visual/yank: `v V y p u`
|
|
- All Ctrl/leader combos
|
|
|
|
*turbo-debug.setup.quit_exits_mode*
|
|
quit_exits_mode ~
|
|
Type: boolean, Default: `true`
|
|
Whether `q` (terminate) also exits debug mode. Set to `false` if you
|
|
want `q` to terminate the process but keep the debug UI open.
|
|
|
|
==============================================================================
|
|
6. Breakpoints *turbo-debug-breakpoints*
|
|
|
|
Breakpoints are managed by persistent-breakpoints.nvim. They persist across
|
|
Neovim restarts and are visible in the sign column at all times.
|
|
|
|
`<leader>dx` toggles a breakpoint (always available).
|
|
`<leader>dX` sets a conditional breakpoint (always available).
|
|
`x`, `X`, `D` also work as shortcuts during debug mode.
|
|
|
|
==============================================================================
|
|
7. UI Layout *turbo-debug-layout*
|
|
|
|
Default layout:
|
|
|
|
Left sidebar (40 columns):
|
|
- Scopes (50%) — local/global variables in current frame
|
|
- Watches (25%) — user-added watch expressions
|
|
- Stacks (25%) — call stack navigation
|
|
|
|
Bottom tray (12 lines):
|
|
- REPL (50%) — evaluate expressions
|
|
- Console (50%) — program stdout/stderr
|
|
|
|
Override the layout: >lua
|
|
require("turbo-debug").setup({
|
|
dapui = {
|
|
layouts = { ... }, -- see nvim-dap-ui docs for format
|
|
},
|
|
})
|
|
<
|
|
==============================================================================
|
|
8. Adapters *turbo-debug.adapters*
|
|
|
|
Built-in adapter support (adapter binary must be installed):
|
|
|
|
Language Adapter Binary ~
|
|
Python debugpy python -m debugpy
|
|
JavaScript/TS js-debug js-debug-adapter
|
|
Go delve dlv
|
|
C/C++ codelldb codelldb
|
|
Rust codelldb codelldb
|
|
Swift codelldb codelldb
|
|
C# netcoredbg netcoredbg
|
|
Java java-debug java-debug-adapter
|
|
Kotlin kotlin-debug kotlin-debug-adapter
|
|
PHP php-debug php-debug-adapter
|
|
Ruby rdbg rdbg
|
|
Lua (Neovim) osv one-small-step-for-vimkind
|
|
|
|
Path resolution order:
|
|
1. User override via `opts.adapters`
|
|
2. Binary on `$PATH`
|
|
3. Standard mason install path (~/.local/share/nvim/mason/bin/)
|
|
|
|
Adapter binaries are the user's responsibility to install.
|
|
|
|
Override or add adapters: >lua
|
|
require("turbo-debug").setup({
|
|
adapters = {
|
|
python = { ... }, -- override built-in
|
|
zig = { ... }, -- add new language
|
|
},
|
|
builtin_adapters = false, -- disable all built-ins
|
|
})
|
|
<
|
|
Existing user nvim-dap configurations are never overridden.
|
|
|
|
==============================================================================
|
|
9. API *turbo-debug-api*
|
|
|
|
*turbo-debug.toggle()*
|
|
require("turbo-debug").toggle()
|
|
Toggle debug mode on/off.
|
|
|
|
*turbo-debug.active()*
|
|
require("turbo-debug").active()
|
|
Returns `true` if debug mode is currently active, `false` otherwise.
|
|
Useful for statusline integration.
|
|
|
|
==============================================================================
|
|
10. Troubleshooting *turbo-debug-troubleshooting*
|
|
|
|
No adapter found ~
|
|
Ensure the adapter binary is installed and on your PATH, or installed
|
|
via mason.nvim. turbo-debug configures adapters, it does not install
|
|
them.
|
|
|
|
Breakpoints not persisting ~
|
|
Check that persistent-breakpoints.nvim is loaded. Run:
|
|
`:lua print(require("persistent-breakpoints") and "ok")`
|
|
|
|
Virtual text not appearing ~
|
|
Virtual text only appears during an active DAP session in debug mode.
|
|
Ensure nvim-dap-virtual-text is loaded:
|
|
`:lua print(require("nvim-dap-virtual-text") and "ok")`
|
|
|
|
Version error ~
|
|
turbo-debug.nvim requires Neovim >= 0.12 for vim.pack support.
|
|
|
|
==============================================================================
|
|
vim:tw=78:ts=8:ft=help:norl:
|