mirror of
https://github.com/neovim/neovim.git
synced 2025-10-26 12:27:24 +00:00
56b7a18995
Problem: Docs about how to obtain backtraces on Linux is not very beginner-friendly; some users used to have difficulties in getting stacktrace against Nvim crash. For instance, the `core` dump file might not appear in the current directory on Ubuntu systems with apport, and the current docs do not fully cover such cases. Solution: Add more hints about where core dump files can be found. For example, on Ubuntu where apport is managing core dump files, users would want to find them in `/var/lib/apport/coredump`.
197 lines
6.2 KiB
Plaintext
197 lines
6.2 KiB
Plaintext
*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. See also |debug.txt| for advice that applies to Vim.
|
|
|
|
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:
|