Currently Online

Latest Posts

Changes in How to Write a Good Bug Report

Editor Comment

gdb info added


Revision Differences of Revision 34

[TOC] ¶

For very in-depth guidelines on how to report bugs in a way that assists the programmer, check out this [article](http://www.chiark.greenend.org.uk/~sgtatham/bugs.html). It is available in a number of languages. ¶

##1. Where to report the bug ¶

The best way to report a bug is to craft a bug report at [Launchpad](https://bugs.launchpad.net/widelands). ¶

You will need to have an Account on Launchpad. ¶

On the right hand side are two options: ¶

* Report a bug ¶
* Ask a question ¶

Before filling out a Bug Report, use the "Search" function to see if your problem has already been addressed. ¶

If your bug is not listed or nothing was found, click "Report a Bug" to fill out the form with the needed information (see below), then scroll down and attach files. ¶

Do not forget to add the proper tags - if you are not sure about the tags just invent some or leave the field empty and we will add them later on. ¶

For more help specifically with Launchpad, check [here](https://help.launchpad.net/Bugs). ¶

**If you are unable or unwilling to use Lanchpad, mention the bug in the "Technical Help" Forum here: <https://wl.widelands.org/forum/forum/1/>.** ¶



##2. Operating System Information ¶

Please provide ALL of the following information: ¶

* Operating System (OS) and patch level/kernel: ¶
* e. g.: Windows XP SP3 ¶
* e. g.: Xubuntu 12.04.3, Linux xubuntu 3.8.0-35-generic #52~precise1-Ubuntu SMP Thu Jan 30 17:24:40 UTC 2014 x86_64 x86_64 x86_64 GNU/Linux ¶


* Widelands release: ¶
* e. g.: 17 ¶
* e. g.: bzr6826 ¶
* e. g.: 1:17-ppa0-bzr6827-201402020556~ubuntu12.04.1 ¶



##3. Description of the problem ¶

Describe the error / bug / false behaviour as specifically as possible: ¶

* The best idea is to use the tile line from crash report: ¶

* e. g.: widelands crashed with SIGSEGV in \__GI__pthread_mutex_lock() ¶


* Think about your headline; try to be succinct as well as descriptive. ¶

* e. g.: wanted to attack the enemy --> no soldier attacks ¶
* e. g.: game crashed while opening up statistic details ¶


* Describe what you did and what you expected to happen, as well as what actually occurred. ¶

Again, be descriptive, but try not to write the next A Song of Ice and Fire or installment of Linux from scratch. ¶



##4. Hardware ¶

If you believe the trouble could depend on your hardware, be sure to indicate this in the bug report or as an attachment: ¶

* Mainboard and CPU ¶
* RAM ¶
* Graphics card ¶
* SSD/HDD and extraordinary configuration (RAID ?; LVM2 ?; ...) ¶
* Network card (?) ¶
* Sound card (?) ¶

* e. g.: Gigabyte GA-MA790GP-UD4H F7c w/ AMD Phenom II X4 810 + 2× 2×2048 MB AData DDR2 800 MHz; Gigabyte GV-R667D3-2GI; 64 GB AData SP900 /; 2×1 TB Seagate ST31000523AS /home (LVM2) + 1.5 TB Seagate ST31500521AS /pub; Pioneer BDR-208DBK ¶

If you do not know exactly which hardware elements you are referring to, check the following: ¶

* in the system management (Start --> Execute... --> compmgmt.msc --> Device Manager --> ) ¶

* in "Terminal" by typing "sudo lshw > lshw.txt" ¶

* look on in your manual and/or bill(s), if you bought single components ¶



##5. Savegames and Replays ¶

Attach save games and/or replays. The way to do this is dependent on your OS: ¶

###5a. Apple Operating Systems ¶


* Mac OS X: Open Finder. ¶
In the Menu "Go" click on "Go to Folder". Enter "~/.widelands" and press return. ¶

This will open a hidden folder in your home directory that contains Widelands files. ¶
In the "save" directory you will find your save games and the replays are in "replays". ¶



###5b. Microsoft Operating Systems ¶

* Windows XP and Vista: C:\\Documents\\[username]\\.widelands ¶

* Windows 7 and 8 / 8.1: C:\\Users\\[username]\\.widelands ¶

In the "save" directory you will find your save games and the replays are in "replays". ¶



###5c. GNU/Linux ¶


* /home/[username]/.widelands ¶
* tested with Ubuntu and Fedora ¶

In the "save" directory you will find your save games and the replays are in "replays". ¶

##6. Crash backtrace ¶

Providing a backtrace is advanced stuff, but if you are Linux user, it is not that complicated. You will need: ¶

* Debug build of the game (this might mean own compilation of game) ¶
* gdb debugger installed (common package that should be available in your distribution repository)

gdb is best used from terminal and the session might look like: ¶

gdb ./widelands ¶
....... # takes 1-3 seconds to pre-load the game ¶
(gdb) run #6 type run and optionally with command line switches ¶
....... # if crash happened you will get the prompt again: ¶
(gdb) bt # type bt and bt will be printed out. ¶

There is easier way how to get this (especially because fullscreen mode can make typing into console impossible). You can use just this one-liner: ¶

gdb -batch -ex "run" -ex "bt" ${widelands binary with path if needed} > ${log with gdb output} 2>&1 ¶

the actual command can look like: ¶

gdb -batch -ex "run" -ex "bt" ./widelands >> gdb.log 2>&1 ¶

This will start the game, just play as usual and if game crashes, the file gdb.log will contain all console output including gdb backtrace at the end of file. Than you can provide it as a part of bug report. ¶

##7. Reporting a crash ¶

If you had a crash, attach the file to the bug report. ¶

The path differs according to your OS: ¶

* Mac OS X: The file is not written by default. Just try to explain as good as you can. ¶

* Microsoft OS's: C:\\Programs\\Widelands\\stdout.txt (or wherever you installed Widelands) ¶
* In new version, a stdout.txt in not created automatically. To do so, you have to start Widelands via the command line. For example: ¶
* Go to C:\\Programs (or wherever you installed Widelands) ¶
* Shift + right-click on the Widelands directory. Choose "Open command prompt". ¶
* In the new window, type `widelands.exe 1>stdout.txt 2>stderr.txt`. Widelands is now started, and the output goes to the respective files. They are overwritten everytime you do this. ¶

* GNU/Linux: /var/crash/ ¶

**Is Widelands installed via ppa you will get a message, that an automatic report is not possible cause of third party packages.** ¶

In this case you can report the bug / crash via Launchpad and add the crash report as an attachment. ¶
If a error message about missing rights comes up, just copy the crash report into your home directory and change the permissions: ¶

* e. g.: sudo cp /var/crash/_usr_games_widelands.1001.crash . (<-- don't forget this point :) ) ¶

* than: sudo chown laza: _usr_games_widelands.1001.crash (<-- make sure, you correct 'laza' into YOUR username!) ¶


The number in the crash report can slightly differ from 1001, so look out for the actual one and check date and time! ¶



##7. Still have more questions about bug reporting? ¶

Cannot figure it out on the damn machine? Struggling with my bad English or this guide? ¶

Try in this order: ¶

* search in the Forums ¶
* search on Launchpad for questions ¶
* ask them on [chat](/webchat) ¶
* raise hands in despair, listen to Despair, fall on the floor, watch as everyone else becomes a dinosaur (or at least an Atlantean)