From fef6672c5e788eec12001ce2bb5ed0df67e0ea1a Mon Sep 17 00:00:00 2001 From: Stephen Waits Date: Sat, 11 Apr 2026 16:44:40 -0600 Subject: [PATCH] docs: readme, contributing guide --- CONTRIBUTING.md | 69 +++++++++++++++++++++++++++ README.md | 124 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 193 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e98bf7c..c021e43 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1 +1,70 @@ # Contributing to tiny-debugger.nvim + +## Source Control + +We use **jj** (Jujutsu), not git. All commits should be made with `jj commit`. + +## Adding a New Adapter + +1. Create `lua/tiny-debugger/adapters/.lua` +2. Implement a `register(dap)` function that calls `loader.register()` +3. Add the module name to the adapters list in `lua/tiny-debugger/adapters/init.lua` +4. Add the language to the README and vimdoc tables + +Example adapter (minimal): + +```lua +local loader = require("tiny-debugger.adapters.init") + +local M = {} + +function M.register(dap) + local binary = loader.find_executable({ "my-debug-adapter" }) + if not binary then return end + + loader.register(dap, "my-adapter", { + type = "executable", + command = binary, + }, { + { + type = "my-adapter", + request = "launch", + name = "Launch file", + program = "${file}", + }, + }, { "mylang" }) +end + +return M +``` + +## Running Tests + +```sh +nvim --headless -u tests/minimal_init.lua -c 'luafile tests/test_config.lua' -c 'qa!' +nvim --headless -u tests/minimal_init.lua -c 'luafile tests/test_mode.lua' -c 'qa!' +nvim --headless -u tests/minimal_init.lua -c 'luafile tests/test_keys.lua' -c 'qa!' +nvim --headless -u tests/minimal_init.lua -c 'luafile tests/test_help.lua' -c 'qa!' +nvim --headless -u tests/minimal_init.lua -c 'luafile tests/test_breakpoints.lua' -c 'qa!' +nvim --headless -u tests/minimal_init.lua -c 'luafile tests/test_adapters.lua' -c 'qa!' +``` + +## Code Style + +- Clean, readable Lua. No metaprogramming tricks. +- Every file should be short enough to read in one sitting. +- No abstraction for abstraction's sake. +- If a plugin does something we can do in <50 lines, we don't add the dependency. + +## Dependencies + +We depend on exactly five plugins (managed via `vim.pack.add`): + +- nvim-dap +- nvim-dap-ui +- nvim-nio +- nvim-dap-virtual-text +- persistent-breakpoints.nvim + +No language-specific plugin dependencies. Adapter configs are inlined as plain +Lua tables. diff --git a/README.md b/README.md index 2e58fe5..04644da 100644 --- a/README.md +++ b/README.md @@ -1 +1,125 @@ # tiny-debugger.nvim + +A zero-config debugging experience for Neovim 0.12+. One line of config, full +IDE-class debugging: inline variable values, hover inspection, persistent +breakpoints, watch expressions, and modal keybindings that just work. + +## Install + +```lua +vim.pack.add("swaits/tiny-debugger.nvim") +``` + +That's it. No other config needed. + +## What You Get + +- **Inline virtual text** — variable values appear right in your source code, + updated live as you step +- **Hover inspection** — press `K` on any expression to see its value +- **Persistent breakpoints** — survive Neovim restarts, visible in the sign + column at all times +- **Watch expressions** — press `W` to add the expression under your cursor +- **Scopes panel** — all local/global variables in the current frame +- **Stack traces** — navigate the call stack, jump to any frame +- **REPL** — evaluate arbitrary expressions in the debug context +- **Console** — program stdout/stderr +- **Modal keybindings** — single-key controls, active only during debug sessions +- **Help box** — shows all keybindings, re-openable with `?` +- **Zero-config adapters** for 10+ languages + +## UI Layout + +``` +┌──────────────────────────────────┬──────────────────┐ +│ │ Scopes (50%) │ +│ Source Code │ │ +│ ├──────────────────┤ +│ x = 42 -- « virtual text │ Watches (25%) │ +│ ├──────────────────┤ +│ │ Stacks (25%) │ +├──────────────────────────────────┴──────────────────┤ +│ REPL (50%) │ Console (50%) │ +└──────────────────────────┴──────────────────────────┘ +``` + +## Keybindings + +`d` toggles debug mode. During debug mode: + +| Key | Action | Mnemonic | +|-----|------------------------|---------------------| +| `c` | Continue | Continue | +| `s` | Step over | Step | +| `d` | Step into | Descend | +| `r` | Step out | Return | +| `C` | Run to cursor | Continue to cursor | +| `x` | Toggle breakpoint | X marks the spot | +| `X` | Conditional breakpoint | Shift-x | +| `W` | Watch expression | Watch | +| `K` | Hover / inspect | LSP hover convention| +| `E` | Eval in REPL | Evaluate | +| `q` | Terminate session | Quit | +| `R` | Restart session | Rerun | +| `?` | Help popup | Help | + +`x` and `X` work outside debug mode too. + +All navigation keys preserved: `h j k l w b e f / n` etc. + +## Supported Languages + +| Language | Adapter | Binary needed | +|-----------------|-----------------|----------------------| +| 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 | + +Adapter binaries are the user's responsibility to install (via mason, system +package manager, or manually). tiny-debugger configures, it doesn't install. + +## Configuration (optional) + +```lua +require("tiny-debugger").setup({ + help_on_enter = true, -- show help box when entering debug mode + builtin_adapters = true, -- register built-in language adapters + + keys = { + continue = "c", -- override any key + step_over = false, -- set to false to disable + }, + + adapters = { + zig = { ... }, -- add new language adapters + }, + + dapui = { ... }, -- override nvim-dap-ui layout + virtual_text = { ... }, -- override virtual text settings +}) +``` + +## Statusline + +```lua +require("tiny-debugger").active() -- returns true/false +``` + +## Help + +``` +:help tiny-debugger +``` + +## License + +MIT