User:DarioAndres/CreateUsefulReports: Difference between revisions

From KDE TechBase
No edit summary
 
(43 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Template:I18n/Language Navigation Bar|Development/Tutorials/Debugging/How to create useful crash reports}}
 
==Introduction==
==Introduction==


This document describes how to reproduce a useful backtrace of crashing KDE applications. First, some general information is given. Then, we will describe for several distributions how to prepare your KDE packages and gaining the backtrace. This should be enough for most people.
This document describes how to create useful bug reports for crashes of KDE applications. The first section should be enough for most bug reporters and triagers.
There are additional sections on how to create backtraces with the GNU Debugger and with Valgrind, which are in some cases useful.
 
There is a second section which details how to create backtraces with additional tools like the GNU Debugger and Valgrind (advanced).
 
{{note|''KDE3 is currently unmaintained''. Crash reports about KDE3 applications which have a KDE4 version counterpart will not be considered.}}


==How to create useful crash reports==
==How to create useful crash reports==


A good crash report at [http://bugs.kde.org Bugzilla] consists of two parts: a '''description''' of how to reproduce the crash and a '''backtrace''' of the crash. With one of those elements missing, it is much harder (if not impossible) for developers to tackle the problem.
A good crash report consists of two parts: a '''description''' of how to reproduce the crash and a '''backtrace''' of the crash. With any of those elements missing, it is very hard (if not impossible) for developers to tackle the problem.


A description should consist of more than only "it crashed". Try to describe everything you did prior to the crash. Did you click on a button, opened a particular website or file which caused problems? That little detail which may look useless to you may be useful for the developer, so just write it down.
===Description===
 
A description should describe everything that you were doing prior to the crash. It should not just say "it crashed". Did you click on a button, did you open a particular website or file which caused problems? These little details, which may look useless to you, may be useful for the developers, so just write them down.
 
* The '''KDE version''' is an important detail that is often missing in bug reports.
 
If you do not know what KDE version are you using, you can get it by selecting the "About KDE" option in the Help menu of every KDE application, or by running the command <tt>kde4-config --version</tt> in Konsole. You will get an output like this:
 
Qt: 4.5.3
KDE: 4.3.2 (KDE 4.3.2)
kde4-config: 1.0
 
{{note|The crash reporting assistant integrated in KDE 4.3 and later automatically includes the KDE version in your report.}}


A more insightful article on how to write good bug descriptions is available [http://www.chiark.greenend.org.uk/~sgtatham/bugs.html at this link], please read that before reporting bugs.
A more insightful article on how to write good bug descriptions is available [http://www.chiark.greenend.org.uk/~sgtatham/bugs.html at this link], please read that before reporting bugs.


{{note|Don't attach the backtrace to the bug report. Instead, simply '''paste it'''. This way it is much easier for developers to search for duplicate reports, because attachments will not be searched.
====Application specific details====
''However'', if you are providing a backtrace in a report which does not belong to you, consider the report could be unrelated to your crash, even when the symptoms are the same. In this cases, just attach the backtrace as a file, so the bug triagers can check it and say if it is the same crash or not}}
 
For several applications it can be useful to have specific details in bug reports:
 
* '''Plasma''' (the KDE Desktop): Plasmoids you have in your desktop (both official and unofficial), desktop settings (wallpaper plugin, themes), activities and dashboard configuration.
* '''KWin''' (the KDE Window Manager): state of compositing(desktop effects): enabled / suspended / disabled, kind of effects enabled, window decoration.
* '''Konqueror''': Sites you were visiting, number of opened tabs, plugins you have installed, non-default settings.
* '''Dolphin''': file view mode, grouping and sorting settings, preview settings, directory you were browsing.
* '''Kopete''': IM protocols you use, plugins you use.
* '''KMail''': Mail protocols and account-types you use.
* '''KWrite/Kate/KOffice''': Type of the document you were editing.
* '''Multimedia Players''' (Juk/Dragon/Amarok): Type of media (extension and format) you were watching and/or listening to.


If you paste a backtrace to a report, make sure you strip all but one or two of the  
===Backtraces===
(no debugging symbols found)
 
lines from the backtrace as they make it harder to read. (If you are using KDE4.3 or later this is done automatically)
Backtraces are ''essential''. They may look meaningless to you, but they might actually contain a wealth of useful information. A backtrace basically describes what was happening inside the application when it crashed, in a way that developers may track down where the mess started.  


* Don't attach the backtrace to the bug report. Instead, simply '''paste it'''. This way it is much easier for developers to search for duplicate reports, because attachments can not be searched.
{{note|If you are providing a backtrace in a report which does not belong to you, consider that the report could be unrelated to your crash, even when the symptoms are the same. In such cases, just attach the backtrace as a file, so the bug triagers can check it and say if it is the same crash or not}}
Even though pasting backtraces directly is preferred over adding an attachment, please do not paste other things like logs (valgrind, strace or terminal output) or example data (mails, HTML files and so on). Use attachments for these items.
Even though pasting backtraces directly is preferred over adding an attachment, please do not paste other things like logs (valgrind, strace or terminal output) or example data (mails, HTML files and so on). Use attachments for these items.


===Backtraces===
----


Backtraces are essential. They may look meaningless to you, but they might actually contain a wealth of useful information. A backtrace describes which functions were called prior to the crash, so that developers may track down in which function the mess started. Having good backtraces has a downside: [[Development/Tutorials/Debugging/Debugging_symbols|libraries and executables occupy much more disk space than their optimized counter parts]]. That's the reason why many distros choose to install stripped files, '''which results in useless backtraces''':
Having good backtraces has a downside: [[Development/Tutorials/Debugging/Debugging_symbols|Libraries and executables occupy much more disk space than their optimized counter parts]]. That's the reason why many distros choose to install stripped files, '''which results in useless backtraces''':


  (no debugging symbols found)
  (no debugging symbols found)
  Using host libthread_db library "/lib/tls/i686/cmov/libthread_db.so.1".
  Using host libthread_db library "/lib/tls/i686/cmov/libthread_db.so.1".
  (no debugging symbols found)
  debugging using libthread_db enabled]
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
[Thread debugging using libthread_db enabled]
  [New Thread -1233848624 (LWP 12212)]
  [New Thread -1233848624 (LWP 12212)]
  [New Thread -1255081072 (LWP 12820)]
  [New Thread -1255081072 (LWP 12820)]
  [New Thread -1240921200 (LWP 12819)]
  [New Thread -1240921200 (LWP 12819)]
  [New Thread -1266680944 (LWP 12818)]
  [New Thread -1266680944 (LWP 12818)]
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
  (no debugging symbols found)
  (no debugging symbols found)
  (no debugging symbols found)
  (no debugging symbols found)
Line 60: Line 74:
But no worries, with some modifications you can create full blown backtraces for KDE applications.
But no worries, with some modifications you can create full blown backtraces for KDE applications.


===Preparing your KDE packages===
====Preparing your KDE packages====
 
{{tip|If you are using KDE4.4+, the crash handler dialog provides an option to automatically install the missing debug packages. After the first backtrace generation, click the ''"Install Debug Symbols"'' button and follow the process. When the packages are installed the backtrace will be re-generated and it will hopefully be complete}}


If your distribution has debugging-enabled packages, install them.
If your distribution has debugging-enabled packages, install them:


It is easy to see which debug packages you are missing from looking at the backtrace. For example, take the following line from a backtrace:
It is easy to see which debug packages you are missing from looking at the backtrace. For example, take the following line from a backtrace:
Line 68: Line 84:
  #6  0xb7975bdc in ?? () from /usr/lib/libkmailprivate.so.4
  #6  0xb7975bdc in ?? () from /usr/lib/libkmailprivate.so.4


The <tt>??</tt> indicates that the library <tt>libkmailprivate.so.4</tt> does not have debug information, which might be available in separate debug packages. In this case, it is pretty easy to guess that you need to install debug packages for KMail to get a better backtrace.
The <tt>??</tt> indicates that the library <tt>libkmailprivate.so.4</tt> does not have debug information, which might be available in a separate debug package. In this case, it is pretty easy to guess that you need to install the debug package for KMail to get a better backtrace.


Sometimes, you need to install more than one debug package to get a good backtrace. This depends on how the distribution splits up the packages. For example, for some distributions it is enough to install the debug package for <tt>kdepim</tt> to get enough debugging information for a crash in KMail, for other distributions there is an additional debug package just for KMail.
Sometimes, you need to install more than one debug package to get a good backtrace. This depends on how the distribution splits up the packages. For example, for some distributions it is enough to install the debug package for <tt>kdepim</tt> to get enough debugging information for a crash in KMail, for other distributions there is an additional debug package just for KMail.


Here's a list of how to obtain debug packages for some distributions:
=====How to obtain debug package for several distributions=====


*'''Debian''' - Debian offers <tt>-dbg</tt> packages to easy create useful backtraces. Just install the corresponding <tt>-dbg</tt> package. e.g. <tt>kdepim-dbg</tt> for KMail crashes. The dependencies of -dbg makes sure to pull in the other right packages (kdelibs-dbg, gdb, and so on).
*'''Debian''' - Debian offers <tt>-dbg</tt> packages to easily create useful backtraces. Just install the corresponding <tt>-dbg</tt> package. e.g. <tt>kdepim-dbg</tt> for KMail crashes. The dependencies of -dbg makes sure to pull in the other right packages (kdelibs-dbg, gdb, and so on).
<!--*'''Fedora''' ???-->
*'''FreeBSD ports''' - Please refer to the [http://freebsd.kde.org/faq.php#AKDEapplicationcrashedandIwanttofileabugreportathttpbugskdeorgbutthebacktraceintheKDECrashManagerisuselessWhatcanIdo KDE on FreeBSD FAQ].
*'''FreeBSD ports''' - Please refer to the [http://freebsd.kde.org/faq.php#AKDEapplicationcrashedandIwanttofileabugreportathttpbugskdeorgbutthebacktraceintheKDECrashManagerisuselessWhatcanIdo KDE on FreeBSD FAQ].
*'''Gentoo''' - Gentoo has its [http://www.gentoo.org/proj/en/qa/backtraces.xml own document] describing how to proceed.
*'''Gentoo''' - Gentoo has its [http://www.gentoo.org/proj/en/qa/backtraces.xml own document] describing how to proceed.
*'''Mandriva''' - Mandriva 2007.0 and up has additional debugging packages for all of KDE (in fact, for all of its packages). Just install the corresponding <tt>-debug</tt> package, like <tt>kdebase-debug</tt> and <tt>kdemultimedia-debug</tt>. You probably want to install <tt>kdelibs-debug</tt> anyways.
*'''Mandriva''' - Mandriva 2007.0 and up has additional debugging packages for all of KDE (in fact, for all of its packages). Just install the corresponding <tt>-debug</tt> package, like <tt>kdebase-debug</tt> and <tt>kdemultimedia-debug</tt>. You probably want to install <tt>kdelibs-debug</tt> anyways.
** Note: the <tt>-debug</tt> packages are in separate repositories. For instance, for all packages in <tt>main</tt>, you'll find the debugging package in repository <tt>debug_main</tt>.
** Note: the <tt>-debug</tt> packages are in separate repositories. For instance, for all packages in <tt>main</tt>, you'll find the debugging package in repository <tt>debug_main</tt>.
*'''Kubuntu/Ubuntu''' - The Ubuntu family makes things quite easy. Every official KDE module has an additional package in the repository, suffixed with <tt>-dbg</tt>. Always install <tt>kdelibs5-dbg</tt>, because all KDE applications use kdelibs (kdelibs-dbg for KDE 3 applications). Then you should install a -dbg package for the application which crashed. For example if KOrganizer crashed you should install <tt>kdepim-dbg</tt> as well.  If the program is not from an official KDE module and has no -dbg package, you can install the -dbgsym package from the repository listed on this [https://wiki.kubuntu.org/DebuggingProgramCrash Debugging Program Crashes] page.
*'''Kubuntu/Ubuntu''' - The Ubuntu family makes things quite easy. Every official KDE module has an additional package in the repository, suffixed with <tt>-dbg</tt>. Always install <tt>kdelibs5-dbg</tt>, because all KDE applications use kdelibs. Then you should install a -dbg package for the application which crashed. For example if KOrganizer crashed you should install <tt>kdepim-dbg</tt> as well.  If the program is not from an official KDE module and has no -dbg package, you can install the -dbgsym package from the repository listed on this [https://wiki.kubuntu.org/DebuggingProgramCrash Debugging Program Crashes] page.
*'''openSUSE''' - You should only install the <tt>-debuginfo</tt> packages, for example: <tt>kdepimlibs4-debuginfo</tt>. You can find these packages in [http://en.opensuse.org/KDE/Repositories KDE repositories]. There is also a dedicated [http://en.opensuse.org/Bugs:An_application_crashed openSUSE debugging page].
*'''openSUSE''' - You should only install the <tt>-debuginfo</tt> packages, for example: <tt>kdepimlibs4-debuginfo</tt>. You can find these packages in [http://en.opensuse.org/KDE/Repositories KDE repositories]. There is also a dedicated [http://en.opensuse.org/Bugs:An_application_crashed openSUSE debugging page].
*'''Fedora''' - Fedora has its [http://fedoraproject.org/wiki/StackTraces own document] describing how to proceed. (A debuginfo repository has to be enabled.)
*'''Fedora''' - Fedora has its [http://fedoraproject.org/wiki/StackTraces own document] describing how to proceed. (A debuginfo repository has to be enabled.)
Line 87: Line 102:
If your distribution doesn't have debugging-enabled packages for KDE, you'll have to compile KDE from sources:
If your distribution doesn't have debugging-enabled packages for KDE, you'll have to compile KDE from sources:


* If you're using KDE 3, then at the configure stage, you should supply the parameter <tt>--enable-debug=full</tt> in order to build debug symbols in the resulting files.
* With KDE 4, at the cmake stage, you should supply the parameter <tt>-DCMAKE_BUILD_TYPE=debugfull</tt>.  If you want to specify your own CXXFLAGS, then use <tt>-DCMAKE_BUILD_TYPE=None CMAKE_CXX_FLAGS="-O0 -g"</tt>.  You can change the CMAKE_CXX_FLAGS as appropriate for your needs.
* If you're using KDE 4, then at the cmake stage, you should supply the parameter <tt>-DCMAKE_BUILD_TYPE=debugfull</tt>.  If you want to specify your own CXXFLAGS, then use <tt>-DCMAKE_BUILD_TYPE=None CMAKE_CXX_FLAGS="-O0 -g"</tt>.  You can change the CMAKE_CXX_FLAGS as appropriate for your needs.


Then it's just <tt>make</tt> and <tt>make install</tt> as you're used to.
Then it's just <tt>make</tt> and <tt>make install</tt> as you're used to.


===Crash!===
===Reproducing the crash===


Now it's time to crash your application.  
Now it's time to crash your application (reproducing the steps that caused the application to crash the first time).


The KDE Crash Dialog should appear right after the crash.
The KDE Crash Handler Dialog should appear right after the crash:


====KDE4.3 and later====
====KDE 4.3 and later====


Since KDE 4.3 there is a new version of the crash handler dialog.
Since KDE 4.3 there is a new version of the crash handler dialog:


[[Image:CrashHandler-Drkonqi-kde43.png|400px|center|KDE 4.3 Crash Handler Dialog]]
[[Image:CrashHandler-Drkonqi-kde43.png|400px|center|KDE 4.3 Crash Handler Dialog]]


In order to get a backtrace directly you need to click the "Developer Information" tab.
In order to get a backtrace directly you need to click the "Developer Information" tab.
{{note|You can also use the "Report Bug" function to file a new bug report at the bugtracker site, using a user-friendly interface}}


(you can also use the "Report Bug" function to file a new bug report at the bugtracker site, using an user-friendly interface)
====KDE 4.0 - 4.2====
 
====KDE4.0 -4.2====


[[Image:CrashHandler-Drkonqi-kde4.png|center|400px|KDE 4 Crash Handler Dialog]]
[[Image:CrashHandler-Drkonqi-kde4.png|center|400px|KDE 4 Crash Handler Dialog]]


In order to get the backtrace you need to click the "Show Details" checkbox.
In order to get the backtrace you need to click the "Show details" checkbox.


====KDE3====
====Backtrace Generation====


[[Image:Kde crash dialog1.png|center|400px|KDE 3 Crash Handler Dialog]]
This process may take quite some memory and CPU, so things may go sluggish all of a sudden. But the result should look much better. For example:
 
In order to get a backtrace you need to click the "Backtrace" tab.
 
-------
 
This process may take quite some memory, so things may go sluggish all of a sudden. But the result should look much better. For example:


<code>
<code>
Application: Plasma Workspace (plasma-desktop), signal: Segmentation fault
Thread 1 (Thread 0x7f3579b39750 (LWP 14011)):
[Current thread is 0 (LWP 3095)]
 
Thread 2 (Thread 0xa9976b90 (LWP 3096)):
#0  0xb80ce424 in __kernel_vsyscall ()
#1  0xb671fc55 in pthread_cond_wait@@GLIBC_2.3.2 () from /lib/libpthread.so.0
#2  0xb677e73e in QWaitCondition::wait (this=0x9282378, mutex=0x9282374, time=4294967295) at thread/qwaitcondition_unix.cpp:87
#3  0xb7a707d2 in QHostInfoAgent::run (this=0x9282368) at kernel/qhostinfo.cpp:260
#4  0xb677db60 in QThreadPrivate::start (arg=0x9282368) at thread/qthread_unix.cpp:189
#5  0xb671c155 in start_thread () from /lib/libpthread.so.0
#6  0xb657aa5e in clone () from /lib/libc.so.6
 
Thread 1 (Thread 0xb5019930 (LWP 3095)):
[KCrash Handler]
[KCrash Handler]
#6 0xa9b82a4e in TaskManager::AbstractGroupingStrategy::closeGroup (this=0x9aed2b0, group=0x9b01d68)
#5 setCaretInvisibleIfNeeded (part=0x16e2ca0) at
    at /home/kde-devel/kde/src/KDE/kdebase/workspace/libs/taskmanager/abstractgroupingstrategy.cpp:142
/home/kde-devel/kde/src/KDE/kdelibs/khtml/khtml_part.cpp:2796
#7 0xa9b897d7 in TaskManager::ProgramGroupingStrategy::checkGroup (this=0x9aed2b0) at /home/kde-devel/kde/src/KDE/kdebase/workspace/libs/taskmanager/strategies/programgroupingstrategy.cpp:196
#6 0x00007f356a8b92b5 in KHTMLPart::setCaretMode (this=0x16e2ca0,
#8 0xa9b8a47b in TaskManager::ProgramGroupingStrategy::qt_metacall (this=0x9aed2b0, _c=QMetaObject::InvokeMetaMethod, _id=0, _a=0xbf8ea7ac)
enable=false) at /home/kde-devel/kde/src/KDE/kdelibs/khtml/khtml_part.cpp:2812
    at /home/kde-devel/kde/build/KDE/kdebase/workspace/libs/taskmanager/programgroupingstrategy.moc:68
#7 0x00007f356a8c98bd in KHTMLPart::qt_metacall (this=0x16e2ca0,
#9 0xb68834c1 in QMetaObject::activate (sender=0x9b01d68, from_signal_index=<value optimized out>, to_signal_index=22, argv=0xbf8ea7ac) at kernel/qobject.cpp:3066
_c=QMetaObject::InvokeMetaMethod, _id=<value optimized out>, _a=0x7fff81c7a800)
#10 0xb6883ad2 in QMetaObject::activate (sender=0x9b01d68, m=0xa9bab194, local_signal_index=1, argv=0xbf8ea7ac) at kernel/qobject.cpp:3143
  at /home/kde-devel/kde/build/KDE/kdelibs/khtml/khtml_part.moc:327
#11 0xa9b9d7f3 in TaskManager::TaskGroup::itemRemoved (this=0x9b01d68, _t1=0x9715580) at /home/kde-devel/kde/build/KDE/kdebase/workspace/libs/taskmanager/taskgroup.moc:143
#8 0x00007f3577276ac0 in QMetaObject::activate (sender=0x1884c90,
#12 0xa9b9de40 in TaskManager::TaskGroup::remove (this=0x9b01d68, item=0x9715580) at /home/kde-devel/kde/src/KDE/kdebase/workspace/libs/taskmanager/taskgroup.cpp:174
from_signal_index=<value optimized out>, to_signal_index=6, argv=0x1cb7f00) at
#13 0xa9b85120 in TaskManager::GroupManagerPrivate::removeTask (this=0x9063150, task={d = 0xbf8ea83c}) at /home/kde-devel/kde/src/KDE/kdebase/workspace/libs/taskmanager/groupmanager.cpp:289
kernel/qobject.cpp:3028
#14 0xa9b86dba in TaskManager::GroupManager::qt_metacall (this=0x923eb48, _c=QMetaObject::InvokeMetaMethod, _id=10, _a=0xbf8ea91c)
#9  0x00007f3576612a57 in QAction::triggered (this=0x0, _t1=false) at
    at /home/kde-devel/kde/build/KDE/kdebase/workspace/libs/taskmanager/groupmanager.moc:99
.moc/debug-shared/moc_qaction.cpp:216
#15 0xb68834c1 in QMetaObject::activate (sender=0x912b0b0, from_signal_index=<value optimized out>, to_signal_index=5, argv=0xbf8ea91c) at kernel/qobject.cpp:3066
#10 0x00007f3576613204 in QAction::activate (this=0x1884c90, event=<value
#16 0xb6883ad2 in QMetaObject::activate (sender=0x912b0b0, m=0xa9bab35c, local_signal_index=1, argv=0xbf8ea91c) at kernel/qobject.cpp:3143
optimized out>) at kernel/qaction.cpp:1125
#17 0xa9ba1193 in TaskManager::TaskManager::taskRemoved (this=0x912b0b0, _t1={d = 0xbf8ea964}) at /home/kde-devel/kde/build/KDE/kdebase/workspace/libs/taskmanager/taskmanager.moc:159
#11 0x00007f3576616862 in QAction::event (this=0x1884c90, e=0x7fff81c7ad90) at
#18 0xa9ba28cf in TaskManager::TaskManager::windowRemoved (this=0x912b0b0, w=58735595) at /home/kde-devel/kde/src/KDE/kdebase/workspace/libs/taskmanager/taskmanager.cpp:265
kernel/qaction.cpp:1044
#19 0xa9ba4734 in TaskManager::TaskManager::qt_metacall (this=0x912b0b0, _c=QMetaObject::InvokeMetaMethod, _id=7, _a=0xbf8eaa8c)
#12 0x00007f3577faa503 in KAction::event (this=0x0, event=0x7fff81c7ad90) at
    at /home/kde-devel/kde/build/KDE/kdebase/workspace/libs/taskmanager/taskmanager.moc:108
/home/kde-devel/kde/src/KDE/kdelibs/kdeui/actions/kaction.cpp:88
...
#13 0x00007f35766180ad in QApplicationPrivate::notify_helper (this=0x10be800,
receiver=0x1884c90, e=0x7fff81c7ad90) at kernel/qapplication.cpp:3803
#14 0x00007f357661f40e in QApplication::notify (this=0x7fff81c7c510,
receiver=0x1884c90, e=0x7fff81c7ad90) at kernel/qapplication.cpp:3768
#15 0x00007f357808155b in KApplication::notify (this=0x7fff81c7c510,
receiver=0x1884c90, event=0x7fff81c7ad90) at
/home/kde-devel/kde/src/KDE/kdelibs/kdeui/kernel/kapplication.cpp:307
#16 0x00007f3577261d90 in QCoreApplication::notifyInternal
(this=0x7fff81c7c510, receiver=0x1884c90, event=0x7fff81c7ad90) at
kernel/qcoreapplication.cpp:583
</code>
</code>


Line 164: Line 168:
{{note|You '''need''' GDB installed to get the backtrace of a crash. Please read the next section to know what GDB is, and how to install it.}}
{{note|You '''need''' GDB installed to get the backtrace of a crash. Please read the next section to know what GDB is, and how to install it.}}


==Additional Tools==
===Retrieving a backtrace with GDB===
===Retrieving a backtrace with GDB===


Line 178: Line 183:
This will run the application like you are used to, and you can work with it like normal (it only consumes far more memory and may feel sluggish). Now it's time to reproduce your crash. When you succeed, the application just closes and you should return to your GDB prompt. Now it's time to run the 'backtrace' command:
This will run the application like you are used to, and you can work with it like normal (it only consumes far more memory and may feel sluggish). Now it's time to reproduce your crash. When you succeed, the application just closes and you should return to your GDB prompt. Now it's time to run the 'backtrace' command:


{{note|Some KDE applications (such as JuK and KTorrent) have special code to ensure that there is only one running instance of the application at a time.  For these applications you should type in "run --nofork" at the (gdb) prompt instead of "run" because otherwise gdb will try to debug the wrong process.  If you are unsure as to whether to use --nofork just try it.  If the application says it's an unknown option you can remove --nofork.}}
{{note|Some KDE applications (such as Plasma, Dolphin, JuK and KTorrent) have special code to ensure that there is only one running instance of the application at a time.  For these applications you should type in "run --nofork" at the (gdb) prompt instead of "run" because otherwise gdb will try to debug the wrong process.  If you are unsure as to whether to use --nofork just try it.  If the application says it's an unknown option you can remove --nofork.}}


  (gdb) thread apply all backtrace
  (gdb) thread apply all backtrace
Line 206: Line 211:
Now reproduce the crash. As soon as this happens, the application and valgrind will terminate. What's left is a file named <tt>someKDEapp.pid</tt> where ''pid'' is replaced by the process ID of the valgrind process. The file may list more errors than the one causing the crash. Here's the bit causing the crash which corresponds to the GDB backtrace above:
Now reproduce the crash. As soon as this happens, the application and valgrind will terminate. What's left is a file named <tt>someKDEapp.pid</tt> where ''pid'' is replaced by the process ID of the valgrind process. The file may list more errors than the one causing the crash. Here's the bit causing the crash which corresponds to the GDB backtrace above:


==23292== Invalid read of size 4
<code>
==23292==    at 0x806BD9E: TreeMapItem::parent() const (treemap.h:285)
==4538== Invalid read of size 4                                          
==23292==    by 0x8065FB9: TreeMapItemList::compareItems(void*, void*) (treemap.cpp:720)
==4538==    at 0xA143AAF: setCaretInvisibleIfNeeded(KHTMLPart*) (khtml_part.cpp:2846)
==23292==    by 0x50AC618: QGList::operator==(QGList const&) const (in /usr/qt/3/lib/libqt-mt.so.3.3.8)
==4538==    by 0xA14CCC9: KHTMLPart::setCaretMode(bool) (khtml_part.cpp:2862)      
==23292==    by 0x806D3BF: QPtrList<TreeMapItem>::operator==(QPtrList<TreeMapItem> const&) const (qptrlist.h:74)
==4538==    by 0xA14CDA9: KHTMLPart::slotToggleCaretMode() (khtml_part.cpp:7155)    
==23292==    by 0x8062DE7: TreeMapWidget::mousePressEvent(QMouseEvent*) (treemap.cpp:1840)
==4538==    by 0xA177107: KHTMLPart::qt_metacall(QMetaObject::Call, int, void**) (khtml_part.moc:337)
==23292==    by 0x4E2FA62: QWidget::event(QEvent*) (in /usr/qt/3/lib/libqt-mt.so.3.3.8)
==4538==    by 0x4ED79C9: QMetaObject::activate(QObject*, int, int, void**) (qobject.cpp:3112)
==23292==    by 0x4D96CA6: QApplication::internalNotify(QObject*, QEvent*) (in /usr/qt/3/lib/libqt-mt.so.3.3.8)
==4538==    by 0x4ED7E0C: QMetaObject::activate(QObject*, QMetaObject const*, int, int, void**) (qobject.cpp:3206)
==23292==    by 0x4D97A87: QApplication::notify(QObject*, QEvent*) (in /usr/qt/3/lib/libqt-mt.so.3.3.8)
==4538==    by 0x51884F7: QAction::triggered(bool) (moc_qaction.cpp:236)
==23292==    by 0x4809AC3: KApplication::notify(QObject*, QEvent*) (kapplication.cpp:550)
==4538==    by 0x5187ABC: QAction::activate(QAction::ActionEvent) (qaction.cpp:1160)
==23292==    by 0x4D36FD1: QETWidget::translateMouseEvent(_XEvent const*) (in /usr/qt/3/lib/libqt-mt.so.3.3.8)
==4538==    by 0x518781C: QAction::event(QEvent*) (qaction.cpp:1079)
==23292==    by 0x4D368AF: QApplication::x11ProcessEvent(_XEvent*) (in /usr/qt/3/lib/libqt-mt.so.3.3.8)
==4538==    by 0x46FF902: KAction::event(QEvent*) (kaction.cpp:88)
==23292==    by 0x4D46760: QEventLoop::processEvents(unsigned) (in /usr/qt/3/lib/libqt-mt.so.3.3.8)
==4538==    by 0x51972DA: QApplicationPrivate::notify_helper(QObject*, QEvent*) (qapplication.cpp:4056)
==23292==  Address 0x2C is not stack'd, malloc'd or (recently) free'd
==4538==    by 0x519573B: QApplication::notify(QObject*, QEvent*) (qapplication.cpp:3603)
==4538==  Address 0x0 is not stack'd, malloc'd or (recently) free'd
</code>


But to be sure, just attach the whole log file to the crash report.
But to be sure, just attach the whole log file to the crash report.

Latest revision as of 13:17, 18 July 2012

Introduction

This document describes how to create useful bug reports for crashes of KDE applications. The first section should be enough for most bug reporters and triagers.

There is a second section which details how to create backtraces with additional tools like the GNU Debugger and Valgrind (advanced).

Note
KDE3 is currently unmaintained. Crash reports about KDE3 applications which have a KDE4 version counterpart will not be considered.


How to create useful crash reports

A good crash report consists of two parts: a description of how to reproduce the crash and a backtrace of the crash. With any of those elements missing, it is very hard (if not impossible) for developers to tackle the problem.

Description

A description should describe everything that you were doing prior to the crash. It should not just say "it crashed". Did you click on a button, did you open a particular website or file which caused problems? These little details, which may look useless to you, may be useful for the developers, so just write them down.

  • The KDE version is an important detail that is often missing in bug reports.

If you do not know what KDE version are you using, you can get it by selecting the "About KDE" option in the Help menu of every KDE application, or by running the command kde4-config --version in Konsole. You will get an output like this:

Qt: 4.5.3
KDE: 4.3.2 (KDE 4.3.2)
kde4-config: 1.0
Note
The crash reporting assistant integrated in KDE 4.3 and later automatically includes the KDE version in your report.


A more insightful article on how to write good bug descriptions is available at this link, please read that before reporting bugs.

Application specific details

For several applications it can be useful to have specific details in bug reports:

  • Plasma (the KDE Desktop): Plasmoids you have in your desktop (both official and unofficial), desktop settings (wallpaper plugin, themes), activities and dashboard configuration.
  • KWin (the KDE Window Manager): state of compositing(desktop effects): enabled / suspended / disabled, kind of effects enabled, window decoration.
  • Konqueror: Sites you were visiting, number of opened tabs, plugins you have installed, non-default settings.
  • Dolphin: file view mode, grouping and sorting settings, preview settings, directory you were browsing.
  • Kopete: IM protocols you use, plugins you use.
  • KMail: Mail protocols and account-types you use.
  • KWrite/Kate/KOffice: Type of the document you were editing.
  • Multimedia Players (Juk/Dragon/Amarok): Type of media (extension and format) you were watching and/or listening to.

Backtraces

Backtraces are essential. They may look meaningless to you, but they might actually contain a wealth of useful information. A backtrace basically describes what was happening inside the application when it crashed, in a way that developers may track down where the mess started.

  • Don't attach the backtrace to the bug report. Instead, simply paste it. This way it is much easier for developers to search for duplicate reports, because attachments can not be searched.
Note
If you are providing a backtrace in a report which does not belong to you, consider that the report could be unrelated to your crash, even when the symptoms are the same. In such cases, just attach the backtrace as a file, so the bug triagers can check it and say if it is the same crash or not

Even though pasting backtraces directly is preferred over adding an attachment, please do not paste other things like logs (valgrind, strace or terminal output) or example data (mails, HTML files and so on). Use attachments for these items.


Having good backtraces has a downside: Libraries and executables occupy much more disk space than their optimized counter parts. That's the reason why many distros choose to install stripped files, which results in useless backtraces:

(no debugging symbols found)
Using host libthread_db library "/lib/tls/i686/cmov/libthread_db.so.1".
debugging using libthread_db enabled]
[New Thread -1233848624 (LWP 12212)]
[New Thread -1255081072 (LWP 12820)]
[New Thread -1240921200 (LWP 12819)]
[New Thread -1266680944 (LWP 12818)]
(no debugging symbols found)
(no debugging symbols found)
(no debugging symbols found)
0xffffe410 in __kernel_vsyscall ()
#0  0xffffe410 in __kernel_vsyscall ()
#1  0xb6a1210b in ?? () from /lib/tls/i686/cmov/libpthread.so.0
#2  0xb6a85afe in ?? () from /usr/lib/libX11.so.6
#3  0x00000003 in ?? ()
#4  0x082149c0 in ?? ()
#5  0x00003ffc in ?? ()
#6  0x00000000 in ?? ()

But no worries, with some modifications you can create full blown backtraces for KDE applications.

Preparing your KDE packages

Tip
If you are using KDE4.4+, the crash handler dialog provides an option to automatically install the missing debug packages. After the first backtrace generation, click the "Install Debug Symbols" button and follow the process. When the packages are installed the backtrace will be re-generated and it will hopefully be complete


If your distribution has debugging-enabled packages, install them:

It is easy to see which debug packages you are missing from looking at the backtrace. For example, take the following line from a backtrace:

#6  0xb7975bdc in ?? () from /usr/lib/libkmailprivate.so.4

The ?? indicates that the library libkmailprivate.so.4 does not have debug information, which might be available in a separate debug package. In this case, it is pretty easy to guess that you need to install the debug package for KMail to get a better backtrace.

Sometimes, you need to install more than one debug package to get a good backtrace. This depends on how the distribution splits up the packages. For example, for some distributions it is enough to install the debug package for kdepim to get enough debugging information for a crash in KMail, for other distributions there is an additional debug package just for KMail.

How to obtain debug package for several distributions
  • Debian - Debian offers -dbg packages to easily create useful backtraces. Just install the corresponding -dbg package. e.g. kdepim-dbg for KMail crashes. The dependencies of -dbg makes sure to pull in the other right packages (kdelibs-dbg, gdb, and so on).
  • FreeBSD ports - Please refer to the KDE on FreeBSD FAQ.
  • Gentoo - Gentoo has its own document describing how to proceed.
  • Mandriva - Mandriva 2007.0 and up has additional debugging packages for all of KDE (in fact, for all of its packages). Just install the corresponding -debug package, like kdebase-debug and kdemultimedia-debug. You probably want to install kdelibs-debug anyways.
    • Note: the -debug packages are in separate repositories. For instance, for all packages in main, you'll find the debugging package in repository debug_main.
  • Kubuntu/Ubuntu - The Ubuntu family makes things quite easy. Every official KDE module has an additional package in the repository, suffixed with -dbg. Always install kdelibs5-dbg, because all KDE applications use kdelibs. Then you should install a -dbg package for the application which crashed. For example if KOrganizer crashed you should install kdepim-dbg as well. If the program is not from an official KDE module and has no -dbg package, you can install the -dbgsym package from the repository listed on this Debugging Program Crashes page.
  • openSUSE - You should only install the -debuginfo packages, for example: kdepimlibs4-debuginfo. You can find these packages in KDE repositories. There is also a dedicated openSUSE debugging page.
  • Fedora - Fedora has its own document describing how to proceed. (A debuginfo repository has to be enabled.)
  • ArchLinux - If you are using the KDEMod repository you can install the -debug packages for each KDE module. If you are using the standard Arch repositories you need to recompile your packages manually. You will find more help in this article: Debug, Getting Traces

If your distribution doesn't have debugging-enabled packages for KDE, you'll have to compile KDE from sources:

  • With KDE 4, at the cmake stage, you should supply the parameter -DCMAKE_BUILD_TYPE=debugfull. If you want to specify your own CXXFLAGS, then use -DCMAKE_BUILD_TYPE=None CMAKE_CXX_FLAGS="-O0 -g". You can change the CMAKE_CXX_FLAGS as appropriate for your needs.

Then it's just make and make install as you're used to.

Reproducing the crash

Now it's time to crash your application (reproducing the steps that caused the application to crash the first time).

The KDE Crash Handler Dialog should appear right after the crash:

KDE 4.3 and later

Since KDE 4.3 there is a new version of the crash handler dialog:

KDE 4.3 Crash Handler Dialog
KDE 4.3 Crash Handler Dialog

In order to get a backtrace directly you need to click the "Developer Information" tab.

Note
You can also use the "Report Bug" function to file a new bug report at the bugtracker site, using a user-friendly interface


KDE 4.0 - 4.2

KDE 4 Crash Handler Dialog
KDE 4 Crash Handler Dialog

In order to get the backtrace you need to click the "Show details" checkbox.

Backtrace Generation

This process may take quite some memory and CPU, so things may go sluggish all of a sudden. But the result should look much better. For example:

Thread 1 (Thread 0x7f3579b39750 (LWP 14011)): [KCrash Handler]

  1. 5 setCaretInvisibleIfNeeded (part=0x16e2ca0) at

/home/kde-devel/kde/src/KDE/kdelibs/khtml/khtml_part.cpp:2796

  1. 6 0x00007f356a8b92b5 in KHTMLPart::setCaretMode (this=0x16e2ca0,

enable=false) at /home/kde-devel/kde/src/KDE/kdelibs/khtml/khtml_part.cpp:2812

  1. 7 0x00007f356a8c98bd in KHTMLPart::qt_metacall (this=0x16e2ca0,

_c=QMetaObject::InvokeMetaMethod, _id=<value optimized out>, _a=0x7fff81c7a800)

  at /home/kde-devel/kde/build/KDE/kdelibs/khtml/khtml_part.moc:327
  1. 8 0x00007f3577276ac0 in QMetaObject::activate (sender=0x1884c90,

from_signal_index=<value optimized out>, to_signal_index=6, argv=0x1cb7f00) at kernel/qobject.cpp:3028

  1. 9 0x00007f3576612a57 in QAction::triggered (this=0x0, _t1=false) at

.moc/debug-shared/moc_qaction.cpp:216

  1. 10 0x00007f3576613204 in QAction::activate (this=0x1884c90, event=<value

optimized out>) at kernel/qaction.cpp:1125

  1. 11 0x00007f3576616862 in QAction::event (this=0x1884c90, e=0x7fff81c7ad90) at

kernel/qaction.cpp:1044

  1. 12 0x00007f3577faa503 in KAction::event (this=0x0, event=0x7fff81c7ad90) at

/home/kde-devel/kde/src/KDE/kdelibs/kdeui/actions/kaction.cpp:88

  1. 13 0x00007f35766180ad in QApplicationPrivate::notify_helper (this=0x10be800,

receiver=0x1884c90, e=0x7fff81c7ad90) at kernel/qapplication.cpp:3803

  1. 14 0x00007f357661f40e in QApplication::notify (this=0x7fff81c7c510,

receiver=0x1884c90, e=0x7fff81c7ad90) at kernel/qapplication.cpp:3768

  1. 15 0x00007f357808155b in KApplication::notify (this=0x7fff81c7c510,

receiver=0x1884c90, event=0x7fff81c7ad90) at /home/kde-devel/kde/src/KDE/kdelibs/kdeui/kernel/kapplication.cpp:307

  1. 16 0x00007f3577261d90 in QCoreApplication::notifyInternal

(this=0x7fff81c7c510, receiver=0x1884c90, event=0x7fff81c7ad90) at kernel/qcoreapplication.cpp:583

This looks better, right? It shows memory addresses, the source files and line numbers and the parameters passed to functions. Which make it more helpful to the developer where to look for the problem.

Note
You need GDB installed to get the backtrace of a crash. Please read the next section to know what GDB is, and how to install it.


Additional Tools

Retrieving a backtrace with GDB

In some cases, it is not possible to create a backtrace with the KDE Crash Dialog. This may be caused by an application which entered an infinite loop, or the crash dialog did not appear at all for some reason. You can try to grab a backtrace with gdb, the GNU Debugger. GDB is widely available through distribution packages.

Invoking GDB differs from the situation. You can run an application from inside gdb, or attach gdb to an already running process. The latter may be useful when an application already has entered an infinite loop. But we will first start with running an application inside gdb. From the shell, run:

$ gdb someKDEapp

The GDB prompt will appear. Note that this does not start the application itself, you should run it by invoking the run command:

(gdb) run

This will run the application like you are used to, and you can work with it like normal (it only consumes far more memory and may feel sluggish). Now it's time to reproduce your crash. When you succeed, the application just closes and you should return to your GDB prompt. Now it's time to run the 'backtrace' command:

Note
Some KDE applications (such as Plasma, Dolphin, JuK and KTorrent) have special code to ensure that there is only one running instance of the application at a time. For these applications you should type in "run --nofork" at the (gdb) prompt instead of "run" because otherwise gdb will try to debug the wrong process. If you are unsure as to whether to use --nofork just try it. If the application says it's an unknown option you can remove --nofork.


(gdb) thread apply all backtrace

This should give a good backtrace which can be posted at the KDE Bugzilla.

In case you want to attach to an existing process, run the following command in the shell:

$ gdb someKDEapp pid

where pid is the process ID of the process you want to attach to. Once attached, and the process is in an infinite loop, after using the 'backtrace' command again a useful backtrace will appear. You can use 'continue' command to let the application run again and press Ctrl+C in gdb to be able to again enter commands.

Retrieving a backtrace with Valgrind

When it comes to crashes, Valgrind is also a useful tool to create a backtrace. It's not a substitution for GDB, but rather a supplement.

When you run an application in valgrind, every piece of memory read or written by the application is being checked. Valgrind will report erroneous memory operations in the standard output or in a log file. Since most crashes are due to an invalid memory read, valgrind can be useful to track down where the problem occurs.

Note
Valgrind consists of several tools in order to check or profile an application. For this article, we only use memcheck, the default tool when valgrind is being invoked.


Like GDB, Valgrind makes running an application much slower, while consuming a lot more resources.

Start the application within valgrind:

$ valgrind --log-file=someKDEapp someKDEapp

Now reproduce the crash. As soon as this happens, the application and valgrind will terminate. What's left is a file named someKDEapp.pid where pid is replaced by the process ID of the valgrind process. The file may list more errors than the one causing the crash. Here's the bit causing the crash which corresponds to the GDB backtrace above:

==4538== Invalid read of size 4 ==4538== at 0xA143AAF: setCaretInvisibleIfNeeded(KHTMLPart*) (khtml_part.cpp:2846) ==4538== by 0xA14CCC9: KHTMLPart::setCaretMode(bool) (khtml_part.cpp:2862) ==4538== by 0xA14CDA9: KHTMLPart::slotToggleCaretMode() (khtml_part.cpp:7155) ==4538== by 0xA177107: KHTMLPart::qt_metacall(QMetaObject::Call, int, void**) (khtml_part.moc:337) ==4538== by 0x4ED79C9: QMetaObject::activate(QObject*, int, int, void**) (qobject.cpp:3112) ==4538== by 0x4ED7E0C: QMetaObject::activate(QObject*, QMetaObject const*, int, int, void**) (qobject.cpp:3206) ==4538== by 0x51884F7: QAction::triggered(bool) (moc_qaction.cpp:236) ==4538== by 0x5187ABC: QAction::activate(QAction::ActionEvent) (qaction.cpp:1160) ==4538== by 0x518781C: QAction::event(QEvent*) (qaction.cpp:1079) ==4538== by 0x46FF902: KAction::event(QEvent*) (kaction.cpp:88) ==4538== by 0x51972DA: QApplicationPrivate::notify_helper(QObject*, QEvent*) (qapplication.cpp:4056) ==4538== by 0x519573B: QApplication::notify(QObject*, QEvent*) (qapplication.cpp:3603) ==4538== Address 0x0 is not stack'd, malloc'd or (recently) free'd

But to be sure, just attach the whole log file to the crash report.