*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.