commit dc5a4330258deaef7c7da842d31aca0925abf9b3
parent 36ee10057ab9a93144975449cc5e27f9b96e0af3
Author: Ryan Jenkins <2343714+Lanny@users.noreply.github.com>
Date: Sat, 25 Mar 2023 11:25:28 -0500
docs: how to debug TUI using gdb/lldb #22771
docs: Add info to the `Debug: TUI` docs about gdb/lldb usage
Diffstat:
1 file changed, 28 insertions(+), 0 deletions(-)
diff --git a/src/nvim/README.md b/src/nvim/README.md
@@ -198,6 +198,34 @@ possible to see exactly what terminfo values Nvim is using on any system.
nvim -V3log
+### TUI Debugging with gdb/lldb
+
+Launching the nvim TUI involves two processes, one for main editor state and one
+for rendering the TUI. Both of these processes use the nvim binary, so somewhat
+confusingly setting a breakpoint in either will generally succeed but may not be
+hit depending on which process the breakpoints were set in.
+
+To debug the main process, you can debug the nvim binary with the `--headless`
+flag which does not launch the TUI and will allow you to set breakpoints in code
+not related to TUI rendering like so:
+
+```
+lldb -- ./build/bin/nvim --headless --listen ~/.cache/nvim/debug-server.pipe
+```
+
+You can then attach to the headless process to interact with the editor like so:
+
+```
+./build/bin/nvim --remote-ui --server ~/.cache/nvim/debug-server.pipe
+```
+
+Conversely for debugging TUI rendering, you can start a headless process and
+debug the remote-ui process multiple times without losing editor state.
+
+For details on using nvim-dap and automatically debugging the child (main)
+process, see
+[here](https://zignar.net/2023/02/17/debugging-neovim-with-neovim-and-nvim-dap/)
+
### TUI trace
The ancient `script` command is still the "state of the art" for tracing
