dev_tools.txt Nvim NVIM REFERENCE MANUAL Tools and techniques for developing Nvim dev-tools The following advice is helpful when working on or debugging issues with Nvim itself. TODO: merge debug.txt into here. Type gO to see the table of contents. ============================================================================== Backtraces dev-tools-backtrace LINUX Core dumps are disabled by default on Ubuntu, CentOS and others. To enable core dumps: >bash ulimit -c unlimited < On systemd-based systems getting a backtrace is as easy as: >bash coredumpctl -1 gdb < coredumpctl is an optional tool, so you may need to install it: >bash sudo apt install systemd-coredump < The full backtrace is most useful; please send us the backtrace.txt file when reporting a bug related to a crash: >bash 2>&1 coredumpctl -1 gdb | tee -a backtrace.txt (gdb) thread apply all bt full < On systems without coredumpctl, you may find a core dump file appearing in the current directory or in other locations. On Linux systems where apport is installed (such as Ubuntu), the directory where core dump files are saved can be /var/lib/apport/coredump or elsewhere, depending on the system configuration (see /proc/sys/kernel/core_pattern). See also: https://stackoverflow.com/a/18368068 To get a backtrace from the ./core dump file: >bash gdb build/bin/nvim ./core 2>&1 | tee backtrace.txt (gdb) thread apply all bt full < MACOS If nvim crashes, you can see the backtrace in Console.app (under "Crash Reports" or "User Diagnostic Reports" for older macOS versions). >bash open -a Console < You may also want to enable core dumps on macOS. To do this, first make sure the /cores/ directory exists and is writable: >bash sudo mkdir /cores sudo chown root:admin /cores sudo chmod 1775 /cores < Then set the core size limit to unlimited: >bash ulimit -c unlimited < Note that this is done per shell process. If you want to make this the default for all shells, add the above line to your shell's init file (e.g. ~/.bashrc or similar). You can then open the core file in lldb: >bash lldb -c /cores/core.12345 < Apple's documentation archive has some other useful information https://developer.apple.com/library/archive/technotes/tn2124/_index.html#//apple_ref/doc/uid/DTS10003391-CH1-SECCOREDUMPS, but note that some of the things on this page are out of date (such as enabling core dumps with /etc/launchd.conf). ============================================================================== Gdb dev-tools-gdb USING GDB TO STEP THROUGH FUNCTIONAL TESTS Use TEST_TAG to run tests matching busted tags (of the form #foo e.g. `it("test #foo ...", ...)`): >bash GDB=1 TEST_TAG=foo make functionaltest < Then, in another terminal: >bash gdb build/bin/nvim (gdb) target remote localhost:7777 -- See nvim_argv in https://github.com/neovim/neovim/blob/master/test/functional/testnvim.lua. USING LLDB TO STEP THROUGH UNIT TESTS lldb .deps/usr/bin/luajit -- .deps/usr/bin/busted --lpath="./build/?.lua" test/unit/ USING GDB To attach to a running nvim process with a pid of 1234 (Tip: the pid of a running Nvim instance can be obtained by calling getpid()), for instance: >bash gdb -tui -p 1234 build/bin/nvim < The gdb interactive prompt will appear. At any time you can: - `break foo` to set a breakpoint on the foo() function - n to step over the next statement - <Enter> to repeat the last command - s to step into the next statement - c to continue - finish to step out of the current function - `p zub` to print the value of zub - bt to see a backtrace (callstack) from the current location - `CTRL-x CTRL-a` or `tui enable` to show a TUI view of the source file in the current debugging context. This can be extremely useful as it avoids the need for a gdb "frontend". - <up> and <down> to scroll the source file view GDB REVERSE DEBUGGING - `set record full insn-number-max unlimited` - continue for a bit (at least until main() is executed - record - provoke the bug, then use revert-next, reverse-step, etc. to rewind the debugger USING GDBSERVER You may want to connect multiple gdb clients to the same running nvim process, or you may want to connect to a remote nvim process with a local gdb. Using gdbserver, you can attach to a single process and control it from multiple gdb clients. Open a terminal and start gdbserver attached to nvim like this: >bash gdbserver :6666 build/bin/nvim 2> gdbserver.log < gdbserver is now listening on port 6666. You then need to attach to this debugging session in another terminal: >bash gdb build/bin/nvim < Once you've entered gdb, you need to attach to the remote session: (gdb) target remote localhost:6666 In case gdbserver puts the TUI as a background process, the TUI can become unable to read input from pty (and receives SIGTTIN signal) and/or output data (SIGTTOU signal). To force the TUI as the foreground process, you can add >c signal (SIGTTOU, SIG_IGN); if (!tcsetpgrp(data->input.in_fd, getpid())) { perror("tcsetpgrp failed"); } < to tui.c:terminfo_start. USING GDBSERVER IN TMUX Consider using a custom makefile https://github.com/neovim/neovim/blob/master/BUILD.md#custom-makefile to quickly start debugging sessions using the gdbserver method mentioned above. This example local.mk will create the debugging session when you type `make debug`. >make .PHONY: dbg-start dbg-attach debug build build: @$(MAKE) nvim dbg-start: build @tmux new-window -n 'dbg-neovim' 'gdbserver :6666 ./build/bin/nvim -D' dbg-attach: @tmux new-window -n 'dbg-cgdb' 'cgdb -x gdb_start.sh ./build/bin/nvim' debug: dbg-start dbg-attach < Here gdb_start.sh includes gdb commands to be called when the debugger starts. It needs to attach to the server started by the dbg-start rule. For example: (gdb) target remote localhost:6666 (gdb) br main vim:tw=78:ts=8:et:ft=help:norl: