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 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 recent Debian and Ubuntu you need first to add debug symbol repositories to your package sources (see specific instructions for Debian and Ubuntu), later:

 $ sudo apt install claws-mail-dbgsym

• • For Debian (jessie or older) and Ubuntu (xenial or older) debug packages are in the main repositories:

 $ 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!