From 593bff5ffdff63fdb6be72bd6321c2bb183df0e1 Mon Sep 17 00:00:00 2001 From: Michael Stapelberg Date: Wed, 10 Mar 2010 13:01:27 +0100 Subject: [PATCH] reformat docs/debugging --- docs/debugging | 84 +++++++++++++++++++++++++++----------------------- 1 file changed, 45 insertions(+), 39 deletions(-) diff --git a/docs/debugging b/docs/debugging index d32329d4..f2a92739 100644 --- a/docs/debugging +++ b/docs/debugging @@ -3,19 +3,20 @@ 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. +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. -- 2.39.5