Difference between revisions of "Debugging Claws"

From Claws Mail FAQ
Jump to: navigation, search
(Add pointer to WinDbg (thanks to jerry at seibercom dot net))
 
(One intermediate revision by one user not shown)
Line 1: Line 1:
Calcium Magnesium Acetate (CMA100)
+
If you find a bug in Claws Mail, reporting it is the best way to have it fixed. Here are some pointers on how to make the most useful bug report possible.
Product Information
+
 
What is CMA100?
+
== Functionality bug (non crasher) ==
CMA100 is a simple combination of dolomitic lime and acetic acid (a principal component of vinegar) and is produced at the manufacturing facility in Fort Madison, Iowa. It is noteworthy that CMA100 (calcium magnesium acetate) is manufactured in the US and held to high standards of quality control. Such standards can vary greatly in foreign material, thereby seriously compromising effectiveness.
+
If you face a functional bug, where Claws Mail doesn't crash, but doesn't do the right thing in your opinion, open a bug on the [http://thewildbeast.co.uk/claws-mail/bugzilla/ bug tracker] describing the action you're trying to do.
Why was CMA100 developed?
+
 
There has long been a concern for damage to the environment and to structures like bridges and parking garages caused by the use of chloride deicers. In the 1970’s, the Federal Highway Administration (FHA) identified calcium magnesium acetate as the only low-corrosion chemical alternative to road salt that also protected the environment. Years of research and field applications have proven CMA is no more corrosive than tap water and does not harm vegetation or receiving watersToday many engineering specifications for new structures, primarily parking garages, specify CMA100 (calcium magnesium acetate) be used.
+
== Crasher bug ==
CMA100 is produced primarily for new concrete, less than 2 years old. For aged or cured concrete (2 years old or more), CMA40 or sodium acetate (NAAC) is recommended.
+
If Claws Mail crashes when you're trying to perform some action, we will need more information than just the steps to reproduce: this sort of bug often depends on many variables, previous actions, your setup, etc. We will need a backtrace, which shows us precisely where in the code Claws crashes and where it came from.
 +
 
 +
To generate a good backtrace, Claws Mail needs to have "debug symbols" available. Without debug symbols, the backtrace is useless because it will not show function information, line numbers and other interesting things.
 +
 
 +
The way to have debug symbols available depends on the way you installed Claws Mail:
 +
 
 +
* Self-compiled Claws Mail: if you compile Claws Mail yourself, rebuild it using the following:
 +
  $ '''make clean'''
 +
  $ '''export CFLAGS=-g'''
 +
  $ '''./configure'''
 +
  $ '''make'''
 +
  $ '''sudo make install'''
 +
 
 +
* Claws Mail packages from your distribution: if you installed Claws Mail from pre-compiled packages, you will often have to install a special "debug" package that have the debug symbols; here are a few examples:
 +
** For Debian and Ubuntu:
 +
  $ '''sudo apt-get install claws-mail-dbg'''
 +
** For Mandriva:
 +
  $ '''sudo urpmi claws-mail-debug'''
 +
** For Fedora:
 +
  $ '''sudo yum install claws-mail-debuginfo'''
 +
** For Suse:
 +
  $ '''sudo smart install claws-mail-debuginfo'''
 +
 
 +
Once you have done that, you can proceed to reproduce the crash inside gdb, the Gnu DeBugger. From a command-line, start claws-mail from gdb:
 +
  $ '''gdb claws-mail'''
 +
  GNU gdb 6.4-debian
 +
  [...]
 +
  (gdb) '''run --debug'''
 +
  Starting program: /usr/local/bin/claws-mail
 +
  [...] ''Here, Claws Mail starts. Make it crash, and you will get the following:''
 +
  Program received signal SIGSEGV, Segmentation fault.
 +
  [Switching to Thread -1227139392 (LWP 10159)]
 +
  0xffffe410 in __kernel_vsyscall ()
 +
  ''You can now ask gdb for the backtrace:''
 +
  (gdb) '''thread apply all bt'''
 +
 
 +
You should now get an output resembling this:
 +
  Thread 2 (Thread -1249215568 (LWP 10168)):
 +
  #0  0xffffe410 in __kernel_vsyscall ()
 +
  #1  0xb7aeec76 in pthread_cond_wait@@GLIBC_2.3.2 ()
 +
    from /lib/tls/i686/cmov/libpthread.so.0
 +
  #2 0xb71ead5a in mailsem_internal_wait (s=0x82fe798) at mailsem.c:121
 +
  #3  0xb71eaf11 in mailsem_down (sem=0xfffffffc) at mailsem.c:321
 +
  #4  0x081c96e0 in thread_run (data=0x82e9eb0) at etpan-thread-manager.c:318
 +
  #5  0xb7aec341 in start_thread () from /lib/tls/i686/cmov/libpthread.so.0
 +
  #6  0xb6fef4ee in clone () from /lib/tls/i686/cmov/libc.so.6
 +
 
 +
  Thread 1 (Thread -1227139392 (LWP 10159)):
 +
  #0  0xffffe410 in __kernel_vsyscall ()
 +
  #1  0xb6fe58c4 in poll () from /lib/tls/i686/cmov/libc.so.6
 +
  #2  0xb72b9b08 in g_main_context_iterate (context=0x833efd0, block=1,
 +
      dispatch=1, self=0x8311100) at gmain.c:2977
 +
  #3  0xb72b9fd8 in IA__g_main_loop_run (loop=0x82d1180) at gmain.c:2879
 +
  #4  0xb7710765 in IA__gtk_main () at gtkmain.c:1026
 +
  #5  0x08102191 in main (argc=1, argv=0xbf9131a4) at main.c:1093
 +
  (gdb) '''quit'''
 +
 
 +
This is what you should copy and paste in a [http://thewildbeast.co.uk/claws-mail/bugzilla/ new bug report].
 +
Don't forget to briefly explain what you were doing, which version you were using, and so on.
 +
 
 +
Finally, gdb can also be used to attach to an already running Claws Mail:
 +
  $ '''gdb -p `pidof claws-mail`'''
 +
You can use that for example if Claws Mail is unresponsive; once in gdb, you can use '''Ctrl-C''' to interrupt execution and '''thread apply all bt''' to see where Claws Mail was stuck.
 +
 
 +
If you're on a Windows based system and don't have gdb you may also try to [https://wiki.documentfoundation.org/How_to_get_a_backtrace_with_WinDbg get a Claws Mail backtrace using WinDbg].
 +
 
 +
== Strange crasher bug ==
 +
Some crashes are due to memory corruptions that occured before the crash. In this case, gdb doesn't help as much as it could, but valgrind does a great job in tracing the execution and showing clearly where the problem lies.
 +
 
 +
You can run valgrind with:
 +
  $ '''G_SLICE=always-malloc G_DEBUG=gc-friendly valgrind \'''
 +
  '''--tool=memcheck --error-limit=no --leak-check=full \'''
 +
  '''--show-reachable=yes claws-mail 2>&1 | tee valgrind.log'''
 +
 
 +
Valgrind slows down the execution a lot. Just redo the actions needed to reproduce the crash, then exit. If the crash doesn't happen under valgrind, the log may still contain the crash causes (and valgrind just changes the result).
 +
 
 +
Thanks for helping making Claws Mail better!

Latest revision as of 14:38, 2 June 2014

If you find a bug in Claws Mail, reporting it is the best way to have it fixed. Here are some pointers on how to make the most useful bug report possible.

Functionality bug (non crasher)

If you face a functional bug, where Claws Mail doesn't crash, but doesn't do the right thing in your opinion, open a bug on the bug tracker describing the action you're trying to do.

Crasher bug

If Claws Mail crashes when you're trying to perform some action, we will need more information than just the steps to reproduce: this sort of bug often depends on many variables, previous actions, your setup, etc. We will need a backtrace, which shows us precisely where in the code Claws crashes and where it came from.

To generate a good backtrace, Claws Mail needs to have "debug symbols" available. Without debug symbols, the backtrace is useless because it will not show function information, line numbers and other interesting things.

The way to have debug symbols available depends on the way you installed Claws Mail:

  • Self-compiled Claws Mail: if you compile Claws Mail yourself, rebuild it using the following:
 $ make clean
 $ export CFLAGS=-g
 $ ./configure
 $ make
 $ sudo make install
  • Claws Mail packages from your distribution: if you installed Claws Mail from pre-compiled packages, you will often have to install a special "debug" package that have the debug symbols; here are a few examples:
    • For Debian and Ubuntu:
 $ sudo apt-get install claws-mail-dbg
    • For Mandriva:
 $ sudo urpmi claws-mail-debug
    • For Fedora:
 $ sudo yum install claws-mail-debuginfo
    • For Suse:
 $ sudo smart install claws-mail-debuginfo

Once you have done that, you can proceed to reproduce the crash inside gdb, the Gnu DeBugger. From a command-line, start claws-mail from gdb:

 $ gdb claws-mail
 GNU gdb 6.4-debian
 [...]
 (gdb) run --debug
 Starting program: /usr/local/bin/claws-mail
 [...] Here, Claws Mail starts. Make it crash, and you will get the following:
 Program received signal SIGSEGV, Segmentation fault.
 [Switching to Thread -1227139392 (LWP 10159)]
 0xffffe410 in __kernel_vsyscall ()
 You can now ask gdb for the backtrace:
 (gdb) thread apply all bt

You should now get an output resembling this:

 Thread 2 (Thread -1249215568 (LWP 10168)):
 #0  0xffffe410 in __kernel_vsyscall ()
 #1  0xb7aeec76 in pthread_cond_wait@@GLIBC_2.3.2 ()
    from /lib/tls/i686/cmov/libpthread.so.0
 #2  0xb71ead5a in mailsem_internal_wait (s=0x82fe798) at mailsem.c:121
 #3  0xb71eaf11 in mailsem_down (sem=0xfffffffc) at mailsem.c:321
 #4  0x081c96e0 in thread_run (data=0x82e9eb0) at etpan-thread-manager.c:318
 #5  0xb7aec341 in start_thread () from /lib/tls/i686/cmov/libpthread.so.0
 #6  0xb6fef4ee in clone () from /lib/tls/i686/cmov/libc.so.6
 
 Thread 1 (Thread -1227139392 (LWP 10159)):
 #0  0xffffe410 in __kernel_vsyscall ()
 #1  0xb6fe58c4 in poll () from /lib/tls/i686/cmov/libc.so.6
 #2  0xb72b9b08 in g_main_context_iterate (context=0x833efd0, block=1,
     dispatch=1, self=0x8311100) at gmain.c:2977
 #3  0xb72b9fd8 in IA__g_main_loop_run (loop=0x82d1180) at gmain.c:2879
 #4  0xb7710765 in IA__gtk_main () at gtkmain.c:1026
 #5  0x08102191 in main (argc=1, argv=0xbf9131a4) at main.c:1093
 (gdb) quit

This is what you should copy and paste in a new bug report. Don't forget to briefly explain what you were doing, which version you were using, and so on.

Finally, gdb can also be used to attach to an already running Claws Mail:

 $ gdb -p `pidof claws-mail`

You can use that for example if Claws Mail is unresponsive; once in gdb, you can use Ctrl-C to interrupt execution and thread apply all bt to see where Claws Mail was stuck.

If you're on a Windows based system and don't have gdb you may also try to get a Claws Mail backtrace using WinDbg.

Strange crasher bug

Some crashes are due to memory corruptions that occured before the crash. In this case, gdb doesn't help as much as it could, but valgrind does a great job in tracing the execution and showing clearly where the problem lies.

You can run valgrind with:

 $ G_SLICE=always-malloc G_DEBUG=gc-friendly valgrind \
  --tool=memcheck --error-limit=no --leak-check=full \
  --show-reachable=yes claws-mail 2>&1 | tee valgrind.log

Valgrind slows down the execution a lot. Just redo the actions needed to reproduce the crash, then exit. If the crash doesn't happen under valgrind, the log may still contain the crash causes (and valgrind just changes the result).

Thanks for helping making Claws Mail better!