Editing Bug Reporting

{{CodingNav}}

To report a bug you should use our bug tracking system [https://osdn.net/projects/freeciv/ticket/ 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 [https://osdn.net/projects/freeciv/ticket/ 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 [[#Savegames|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). In the client, Help / About Freeciv has useful version information that you can paste into a bug report.
* 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.

== Savegames ==

Save games are very useful in bug reports. As well as your game specifics, they tell us about settings you might have changed from the defaults, etc.

If you can provide the savegame from the turn '''before''' you noticed a problem, we have a much better chance of diagnosing or reproducing it than if you provide a savegame from afterward. You can also try reproducing the problem from the savegame in order to give us a good set of steps to replicate it.

For single-player games, by default Freeciv creates a save file every turn (see the [[FAQ#Where are the save games located by default?|FAQ]] to find them), so you should be able to provide us with this file. The save filename includes the turn and year number (for instance <tt>freeciv-T0270-Y01790-auto.sav.bz2</tt>); you can compare that to what you saw in the client when you saw the problem.

If your bug report is going to refer to specific units, tiles, etc in your savegame, then you can use the chatline shortcuts to point to them instead of writing "the Explorer in the Swamp near Poznań".

In the Gtk clients, you can use Ctrl+Alt+right-click to link to cities or tiles, or Ctrl+Shift+Alt+right-click to link to units; see the help for Controls and Chatline. Use these keys and paste the resulting markup (that will look like <tt>[l tgt="unit" id=101 name="Settlers" /]</tt>) into the bug report. We can then paste it into our client, or look at the ID, and see exactly what you're referring to.

== Editor ==

If you have the effort, you can try to make a minimal reproduction case. The built-in game editor in the Gtk clients is very useful for setting up particular situations for testing. Use Ctrl+E in single-player mode to enter the editor.

== 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 [[#Getting a core file|below]]):
 $ gdb freeciv-gtk3.22 -c core
or run the program inside the ''gdb'' program:
 $ gdb freeciv-gtk3.22
 (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 [[#Backtrace on Unix|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 [[#Getting a core file|enabled coredumps]], a core file will be produced by default, which will allow you to get [[#Backtrace on Unix|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.
[[Category:Game Development]]