• Introduction
• gdb
• Starting NAEV
• Getting the Backtrace
• Valgrind
• Starting NAEV
• Getting Results

Introduction

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.

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

r

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

r -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 using trunk.

Valgrind

Valgrind is much more powerful then gdb, but it's only good for memory issues and it's exceedingly slow. 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.