| Developing Freeciv |
|---|
 |
To report a bug you should use our bug tracking system here. Before submitting a report you should check if the bug has already been reported. Take a look at the list of major Known Bugs, or search the full list of bugs.
A good bug report should contain:
- Description of the problem. The easiest bugs to fix are those which developers can reproduce. If it is possible please provide a step by step instruction to trigger a bug. A savegame is often very useful for this.
- Freeciv version. Please specify how you downloaded or compiled your copy. If you report a problem in the client please tell us the client type (gtk3, gtk2, qt, sdl, etc -- this information is on the starting screen in recent versions).
- Information about environment which your copy is run in: OS (Windows, Unix, etc), OS version, language, unusual compiler options (if you built it yourself), etc.
After submitting the report you should expect further questions. You may be asked for a savegame or backtrace. Therefore you should keep the savegame for some time.
Backtrace
A stack backtrace provides very useful information about state of a process. Usually when a program crashes, programmers look at the state to investigate a cause of the bug.
Backtrace on Windows
If the client or server crashes, Windows builds of Freeciv create a file called something like freeciv-gtk2.RPT or freeciv-server.RPT in the installation directory. This contains a stack backtrace, so please tell us its contents when reporting a crash.
Backtrace on Unix
To provide a backtrace you can either investigate a core file, which the program may have left on disc after it crashed (see below):
$ gdb freeciv-gtk2 -c core
or run the program inside the gdb program:
$ gdb freeciv-gtk2 (gdb) run
(You may have to install gdb first.)
In the second case you have to reproduce the crash first.
In either case, now you should type:
(gdb) bt full
The result will look something like this:
#0 0xb78969e7 in raise () from /lib/tls/libc.so.6
#1 0xb789831b in abort () from /lib/tls/libc.so.6
#2 0xb788f885 in __assert_fail () from /lib/tls/libc.so.6
#3 0x08072414 in meswin_thaw () at messagewin_common.c:54
#4 0x0805d31c in reports_thaw () at climisc.c:967
#5 0x0807a718 in handle_thaw_hint () at packhand.c:2701
#6 0x0807aa36 in client_handle_packet (type=PACKET_THAW_HINT,
packet=0x8bdfb90) at packhand_gen.c:35
#7 0x08059ae8 in handle_packet_input (packet=0x8bdfb90, type=3)
at civclient.c:390
This is the information we are interested in. If you compile your copy with the '-g' compiler option, the result will contain more useful information.
Getting a core file
On modern Linux, core files are not generated by default when a program crashes, so you may need to run the following command to enable them (in the same shell session as the program you're debugging, before you start it):
$ ulimit -c unlimited
You may see a crash message like "Segmentation fault" change to "Segmentation fault (core dumped)". (However, confusingly, some distributions like Ubuntu are configured such that the message always says "(core dumped)" regardless of whether a file is produced.)
If it's correctly configured, a file will be created nearby with a name like core or core.12345 which contains debugging information. (Note however that if a core file already exists, it won't be overwritten -- so make sure you clear out any previous core files.)
It is not generally useful to attach a core file directly to a bug report, as it can't be interpreted without your compiled version of the program; this is why we ask for you to generate the backtrace.
Backtrace on failed assertion
If you get a message like:
in copy_chars_to_string16() [gui_string.c::196]: assertion 'pString != ((void *)0)' failed
and you can reproduce it, you can start your client or the server with the -F parameter to raise a signal on assertion failure; by default it will cause a crash with a backtrace, which will probably be useful to diagnose the issue. If you've enabled coredumps, a core file will be produced by default, which will allow you to get a more detailed backtrace.
If you are running with gdb, -F SIGINT (usually 2) is especially useful to interrupt the process, as you can resume with the continue gdb command.