reformat docs/debugging
This commit is contained in:
Michael Stapelberg
parent
5d4d9681a0
commit
593bff5ffd
|
|
@ -3,19 +3,20 @@ 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.
|
||||
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!
|
||||
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.
|
||||
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
|
||||
|
|
@ -23,32 +24,35 @@ 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):
|
||||
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:
|
||||
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+.
|
||||
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:
|
||||
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)
|
||||
|
|
@ -60,23 +64,23 @@ You should get an output like this:
|
|||
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.
|
||||
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.
|
||||
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.
|
||||
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):
|
||||
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
|
||||
|
|
@ -90,9 +94,11 @@ backtrace full
|
|||
|
||||
== 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 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.
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue