125 lines
5.1 KiB
Plaintext
125 lines
5.1 KiB
Plaintext
Debugging i3: How To
|
||
==================
|
||
Michael Stapelberg <michael+i3@stapelberg.de>
|
||
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 and stderr 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') 2>&1
|
||
--------------------------------------------------------------------
|
||
|
||
== 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.
|