From 67d985ab8acd32c509c58d7205214a19221087cc Mon Sep 17 00:00:00 2001 From: Michael Stapelberg Date: Tue, 28 Apr 2009 21:10:20 +0200 Subject: [PATCH] Add docs/debugging --- docs/Makefile | 7 ++- docs/debugging | 124 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 130 insertions(+), 1 deletion(-) create mode 100644 docs/debugging diff --git a/docs/Makefile b/docs/Makefile index 448cd68b..720f6387 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,7 +1,12 @@ + +all: hacking-howto.html debugging.html + hacking-howto.html: hacking-howto asciidoc -n $< -all: hacking-howto.html +debugging.html: debugging + asciidoc -n $< + clean: rm -f */*.{aux,log,toc,bm,pdf,dvi} diff --git a/docs/debugging b/docs/debugging new file mode 100644 index 00000000..5dfd95eb --- /dev/null +++ b/docs/debugging @@ -0,0 +1,124 @@ +Debugging i3: How To +================== +Michael Stapelberg +April 2009 + +This document describes how to debug i3 suitably for sending us useful bug reports, even +if you have no clue of C programming. + +First of all: Thank you for being interested in debugging i3. It really means something +to us to get your bug fixed. If you have any questions about the debugging and/or need +further help, do not hesitate to contact us! + +== Enabling logging + +i3 spits out much information onto stdout. To have a clearly defined place where logfiles +will be saved, you should redirect stdout in xsession. While you’re at it, putting each +run of i3 in a separate logfile with date/time in it is a good idea to not get confused +about the different logfiles later on. + +--------------------------------------------------------------- +exec /usr/bin/i3 >/home/michael/i3/i3log-$(date +'%F-%k-%M-%S') +--------------------------------------------------------------- + +== Enabling coredumps + +When i3 crashes, often you have the chance of getting a coredump (an image of the memory +of the i3 process which can be loaded into a debugger). To get a core-dump, you have to +make sure that the user limit for core dump files is set high enough. Many systems ship +with a default value which even forbids core dumps completely. To disable the limit +completely and thus enable coredumps, use the following command (in your .xsession, before +starting i3): + +------------------- +ulimit -c unlimited +------------------- + +Furthermore, to easily recognize core dumps and allow multiple of them, you should set +a custom core dump filename pattern, using a command like the following: + +--------------------------------------------- +sudo sysctl -w kernel.core_pattern=core.%e.%p +--------------------------------------------- + +This will generate files which have the executable’s file name (%e) and the process id +(%p) in it. You can save this setting across reboots using +/etc/sysctl.conf+. + +== Compiling with debug symbols + +To actually get useful coredumps, you should make sure that your version of i3 is compiled +with debug symbols, that is, that they are not stripped during the build process. You +can check whether your executable contains symbols by issuing the following command: + +---------------- +file $(which i3) +---------------- + +You should get an output like this: +------------------------------------------------------------------------------ +/usr/bin/i3: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically +linked (uses shared libs), for GNU/Linux 2.6.18, not stripped +------------------------------------------------------------------------------ + +Notice the +not stripped+, which is the important part. If you have a version which is +stripped, please have a look if your distribution provides debug symbols (package +i3-wm-dbg+ +on Debian for example) or if you can turn off stripping. If nothing helps, please build +i3 from source. + +== Generating a backtrace + +Once you have made sure that your i3 is compiled with debug symbols and that coredumps +are enabled, you can start getting some sense out of the coredumps. + +Because the coredump depends on the original executable (and its debug symbols), please +do this as soon as you encounter the problem. If you re-compile i3, your coredump might +be useless afterwards. + +Please install +gdb+, a debugger for C. No worries, you don’t need to learn it now. +Start gdb using the following command (replacing the actual name of the coredump of +course): + +---------------------------- +gdb $(which i3) core.i3.3849 +---------------------------- + +Then, generate a backtrace using: + +--------- +backtrace +--------- + +Also, getting an overview of the local variables might help: +----------- +info locals +----------- + +If your backtrace looks like this: +--------------------------------------------------------------------------------------------------- +(gdb) backtrace +#0 0x041b1a01 in vfprintf () from /lib/libc.so.6 +#1 0x041b2f80 in vprintf () from /lib/libc.so.6 +#2 0x080555de in slog (fmt=0x8059ba0 "%s:%s:%d - Name should change to \"%s\"\n") at src/util.c:60 +#3 0x0804fa73 in handle_windowname_change_legacy (data=0x0, conn=0x42da908, + state=0 '\0', window=8389918, atom=39, prop=0x4303f90) at src/handlers.c:752 +#4 0x0406cace in ?? () from /usr/lib/libxcb-property.so.1 +#5 0x00000000 in ?? () +--------------------------------------------------------------------------------------------------- + +you need to find the first frame which actually belongs to i3 code. You can easily spot them, as +their filename starts with src/ and has a line number. In this case, frame 2 would be the correct +frame, so before getting the local variables, switch to frame 2: + +----------- +frame 2 +info locals +----------- + +== Sending bugreports/debugging on IRC + +When sending bugreports, please paste the relevant part of the log (if in doubt, please send us rather +too much information than too less) and the whole backtrace (if there was a coredump). + +When debugging with us in IRC, be prepared to use a so called nopaste service such as http://nopaste.info +because pasting large amounts of text in IRC sometimes leads to incomplete lines (servers have line +length limitations) or flood kicks.