diff --git a/README.md b/README.md index 14e78b8..885dde0 100644 --- a/README.md +++ b/README.md @@ -4,24 +4,46 @@ A zero-config debugging experience for Neovim 0.12+. One plugin install, full IDE-class debugging: inline variable values, hover inspection, persistent breakpoints, watch expressions, and modal keybindings that just work. +Inspired by Turbo Pascal — the first IDE where you could just hit a key +and start debugging. + +![turbo-debug screenshot](https://github.com/user-attachments/assets/TODO) + ## Install ```lua -vim.pack.add("swaits/turbo-debug.nvim") +vim.pack.add("swaits/turbo-debug") ``` That's it. No other config needed. See `:help turbo-debug` for customization. -## Usage +## How It Works -Everything lives under `d` (with which-key support if installed): +turbo-debug is **modal**. Press `dd` and you enter debug mode — the +UI opens, keybindings activate, and you're debugging. Press `q` or +`dd` again and everything disappears. Your editor is exactly as it +was before. -| Key | Action | Available | -|-----|--------|-----------| -| `dd` | Toggle debug mode | Always | -| `dx` | Toggle breakpoint | Always | -| `dX` | Conditional breakpoint | Always | -| `dD` | Clear all breakpoints | Always | +This modal approach is inspired by +[debugmaster.nvim](https://github.com/MironPascalCaseFan/debugmaster.nvim). +During a debug session you need to **navigate** code and **inspect** state. +You do not need to **edit**. So debug mode shadows editing keys (`c`, `d`, +`s`, `r`, `x`) with debug actions and leaves all navigation keys untouched +(`h`, `j`, `k`, `l`, `w`, `b`, `e`, `f`, `/`, `n`, etc.). + +When debug mode ends, every keybinding is restored to exactly what it was. + +## Keybindings + +Everything lives under `d` (with +[which-key](https://github.com/folke/which-key.nvim) support if installed): + +| Key | Action | +|-----|--------| +| `dd` | Toggle debug mode | +| `dx` | Toggle breakpoint | +| `dX` | Conditional breakpoint | +| `dD` | Clear all breakpoints | During debug mode, single-key controls: @@ -35,11 +57,13 @@ During debug mode, single-key controls: | `q` | Terminate session | `E` | Eval in REPL | | `R` | Restart session | `?` | Help popup | -All navigation keys preserved. Modal keybindings vanish when you exit debug mode. +Press `?` during debug mode for a quick reference. ## Supported Languages -Adapter binaries must be installed (via mason, package manager, etc). +turbo-debug ships adapter configs for 12 languages. You install the adapter +binary (via [mason.nvim](https://github.com/williamboman/mason.nvim), your +package manager, or manually) — turbo-debug handles all the configuration. | Language | Adapter | Language | Adapter | |----------|---------|----------|---------| @@ -50,6 +74,36 @@ Adapter binaries must be installed (via mason, package manager, etc). | Rust | codelldb | Ruby | rdbg | | Swift | codelldb | Lua (Neovim) | osv | +Rust gets special treatment: pressing `c` runs `cargo build` automatically +and picks the binary via `vim.ui.select`. + +## What This Plugin Actually Does + +turbo-debug is **glue**. It does not implement a debugger, a UI framework, +virtual text rendering, or breakpoint persistence. It configures and wires +together these excellent plugins into a single cohesive experience: + +| Plugin | What it provides | +|--------|-----------------| +| [nvim-dap](https://github.com/mfussenegger/nvim-dap) | DAP client — the core debug engine | +| [nvim-dap-ui](https://github.com/rcarriga/nvim-dap-ui) | Scopes, stacks, watches, REPL, console UI | +| [nvim-nio](https://github.com/nvim-neotest/nvim-nio) | Async IO (required by nvim-dap-ui) | +| [nvim-dap-virtual-text](https://github.com/theHamsta/nvim-dap-virtual-text) | Inline variable values in source code | +| [persistent-breakpoints.nvim](https://github.com/Weissle/persistent-breakpoints.nvim) | Breakpoints that survive restarts | + +All five are loaded automatically via `vim.pack.add`. You never declare them. + +Adapter configurations are inlined from the work of these projects (no +runtime dependency, we just studied their configs and wrote plain Lua tables): + +- [nvim-dap-python](https://github.com/mfussenegger/nvim-dap-python) +- [nvim-dap-go](https://github.com/leoluz/nvim-dap-go) +- [nvim-dap-vscode-js](https://github.com/mxsdev/nvim-dap-vscode-js) +- [nvim-dap-lldb](https://github.com/julianolf/nvim-dap-lldb) +- [nvim-dap-cs](https://github.com/NicholasMata/nvim-dap-cs) +- [nvim-dap-ruby](https://github.com/suketa/nvim-dap-ruby) +- [nvim-dap-kotlin](https://github.com/Mgenuit/nvim-dap-kotlin) + ## License MIT diff --git a/doc/turbo-debug.txt b/doc/turbo-debug.txt index 1ad9446..5f0ab1a 100644 --- a/doc/turbo-debug.txt +++ b/doc/turbo-debug.txt @@ -36,7 +36,7 @@ Features: 2. Installation *turbo-debug-installation* Add one line to your init.lua: >lua - vim.pack.add("swaits/turbo-debug.nvim") + vim.pack.add("swaits/turbo-debug") < That's it. All dependencies are managed automatically. diff --git a/turbo-debug-spec.md b/turbo-debug-spec.md index 93c7834..81a24ff 100644 --- a/turbo-debug-spec.md +++ b/turbo-debug-spec.md @@ -14,7 +14,7 @@ and persistent-breakpoints into a single cohesive experience with modal keybindings. The user installs one plugin and gets everything. ```lua -vim.pack.add("swaits/turbo-debug.nvim") +vim.pack.add("swaits/turbo-debug") ``` That's it. That's the whole setup. @@ -132,7 +132,7 @@ C/C++/Rust only). Out of scope. ```lua -- init.lua -vim.pack.add("swaits/turbo-debug.nvim") +vim.pack.add("swaits/turbo-debug") ``` One line. One plugin. Everything works. @@ -582,7 +582,7 @@ Autocmd to close on any keypress. Content built from the keys table. A user who has never configured DAP should be able to: -1. Add one line to their init.lua: `vim.pack.add("swaits/turbo-debug.nvim")` +1. Add one line to their init.lua: `vim.pack.add("swaits/turbo-debug")` 2. Open a file in any of the world's top 10 languages. 3. Press `x` on a line to set a breakpoint (visible immediately in gutter). 4. Press `d` to enter debug mode. See the help box. See the UI.