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.
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.
Install gdb through your package manager, the package name is most likely gdb.
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
Mac OS X
gdb is installed with the developer tools. The location of the file to use with gdb is:
The basics are as follows: Run Naev through gdb from the console like so:
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
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:
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.
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.
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
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.]