Debugging

Introduction
This guide is primarily intended to assist advanced users and developers in debugging crash issues.

There are two basic ways to debug Naev: You can either use gdb (GNU Debugger) or Valgrind. Both serve different purposes and complement each other well.

Valgrind is for memory issues, while gdb can be used for other issues also. gdb is much faster then valgrind and is the recommended first tool.

gdb
The main goal to track an issue with gdb is to get a backtrace. This can be done by running Naev via gdb and requesting a backtrace in the event it crashes. In the event you've found a bug that is reproducible, a backtrace can help get it fixed swiftly.

Given that there's minimal performance loss when running under gdb, it's recommended to run with it whenever possible, due to the useful output in the event of a crash.

Linux
Install gdb through your package manager, the package name is most likely gdb.

Windows
If you've followed our Windows compiling guide, you can also install gdb through the MinGW shell:

pacman -S mingw-w64-i686-gdb  # 32-bit pacman -S mingw-w64-x86_64-gdb # 64-bit

Otherwise, install the MinGW wersion of gdb. Both 32-bit and 64-bit versions are available.

Mac OS X
gdb is installed with the developer tools. The location of the file to use with gdb is:

Starting Naev
The basics are as follows: Run Naev through gdb from the console like so: gdb naev

Do not pass parameters to Naev directly, as you can't at this point. Don't run Naev in fullscreen when using gdb.

A prompt should appear and you'll want to have it run the program. Type run

in the prompt. If you want to pass parameters, you can do so by adding them after run, like so:

run -W 1024 -H 768

Getting the Backtrace
Now Naev should be running normally. Do whatever you can do to trigger the issue. If the issue is a segfault it'll freeze Naev when it occurs and open up the prompt again. If the game hangs, you'll have to go to the console and hit Ctrl-C to send SIGINT and have gdb stop execution. In order to get the backtrace, type:

bt full

You should see function names, parameters, code lines and variables all over. Now save all the console output (from gdb ./naev to the end) and put it on the issue tracker. This will make catching the bug much easier. Be sure to specify the version you're using and the revision if you're running from Git.

Valgrind
Note: Valgrind does not run natively on Windows. It's primarily a *nix utility and is mostly listed here for Linux users, though it's also usable on many other Unix-like OSes.

Valgrind is primarily useful for tracking down memory issues, but it's exceedingly slow (20-100 times slower than running normally). Debugging with Valgrind is simpler, however.

Starting Naev
To start Naev via Valgrind, type:

valgrind --leak-check=full --error-limit=no naev 2>v.txt

That will start Valgrind doing a full leak check and not limiting errors (which is useful for some drivers) and put all the output in v.txt which is a nice file you can send the development team later

Getting Results
Once Naev starts, (it'll be very slow) try to trigger bugs or issues you know of. You can also just play around to see if Valgrind can pick up a possible issue. Once done you can send v.txt to the developers via the mailing list, IRC, or the issue tracker.

]