Debugging Claws

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 bugreport 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.

Thanks for helping making Claws Mail better!