Add docs/debugging

diff --git a/docs/Makefile b/docs/Makefile
index 448cd68b5cfccad38da5030eab2ca20a49802164..720f6387c8af1a575bd5487ab6df6d6c850e84d9 100644 (file)
--- 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 (file)
index 0000000..5dfd95e
--- /dev/null
+++ b/docs/debugging
@@ -0,0 +1,124 @@
+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 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.