DebuggingWesnoth

A common problem is that a user of Wesnoth has Wesnoth crash on them, but no developers can reproduce the problem, and so that makes it very difficult for us to fix it.

Fortunately, if you are using GNU/Linux or another Unix-like system, have compiled Wesnoth yourself, and you have debugging symbols in (the default when compiling), or your packager has left debugging symbols in, you can do a little debugging yourself to send to a developer. Even a non-programmer can do enough to give a developer alot of clues about where Wesnoth is crashing.

When a program crashes, if the system is configured correctly it will leave behind a 'core' file. A 'core' file contains the contents of memory [1] at the time the program crashed. However, many systems by default have the maximum size of cores set very low, or to 0, meaning that the system won't dump cores. So, before running Wesnoth, use the following command in the same terminal you plan to run Wesnoth from to make it so that cores will be always dumped, no matter how large they are.

ulimit -c unlimited

Then, run Wesnoth, and do whatever you have to do to make it crash. The last line of output should be something like,

Segmentation Fault (core dumped)

or perhaps,

Aborted (core dumped)

or something similiar. The core file will then be in the current working directory, and will either be called 'core' or 'core.<pid>' where <pid> is the process ID of Wesnoth before it crashed. You can of course list all cores in the current directory using,

ls core*

Now that you have your core, you can open it and see where Wesnoth crashed. To open it, you run gdb giving it the path to the Wesnoth binary as its first argument, and the core file as its second. The most common usage is,

gdb ./wesnoth ./core

This should run gdb, and print out alot of information which is generally of no consequence (unless there is an error message). gdb should give you a prompt, at which you can type the command,

bt full

This should make gdb print out what is known as a 'backtrace' -- a list of all the functions Wesnoth was in when it crashed. Copy everything that gdb printed out below where you typed bt full, and send it to a developer. It's a good idea if you keep the core file around, because the developer may need you to open it again with gdb to run some more commands.

[1] 'core' is an old-fashioned Unix term for memory.