<h1>Debugging i3: How To</h1>\r
<span id="author">Michael Stapelberg</span><br />\r
<span id="email"><tt><<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>></tt></span><br />\r
-<span id="revdate">February 2012</span>\r
+<span id="revdate">December 2012</span>\r
</div>\r
<div id="preamble">\r
<div class="sectionbody">\r
-<div class="paragraph"><p>This document describes how to debug i3 suitably for sending us useful bug\r
-reports, even if you have no clue of C programming.</p></div>\r
-<div class="paragraph"><p>First of all: Thank you for being interested in debugging i3. It really means\r
+<div class="paragraph"><p>This document describes how to debug i3 to send us useful bug\r
+reports, even if you have no knowledge of C programming.</p></div>\r
+<div class="paragraph"><p>Thank you for being interested in debugging i3. It really means\r
something to us to get your bug fixed. If you have any questions about the\r
-debugging and/or need further help, do not hesitate to contact us!</p></div>\r
+process and/or need further help, do not hesitate to contact us!</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
<div class="paragraph"><p>Your version can look like this:</p></div>\r
<div class="dlist"><dl>\r
<dt class="hdlist1">\r
-4.1.2\r
+4.1.2 (release version)\r
</dt>\r
<dd>\r
<p>\r
-You are using a release version. Please\r
-upgrade to a development version first, or read\r
-<a href="debugging-release-version.html">Debugging i3: How To (release version)</a>.\r
+You are using a release version. In many cases, bugs are already\r
+fixed in the development version of i3. If they aren’t, we will still ask you\r
+to reproduce your error with the most recent development version of i3.\r
+Therefore, please upgrade to a development version if you can.\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
-4.1.2-248-g51728ba\r
+4.1.2-248-g51728ba (development version)\r
</dt>\r
<dd>\r
<p>\r
</p>\r
</dd>\r
</dl></div>\r
-<div class="paragraph"><p>Development versions of i3 have several properties which make debugging easier:</p></div>\r
-<div class="olist arabic"><ol class="arabic">\r
-<li>\r
-<p>\r
-Shared memory debug logging is enabled by default. You do not have to enable\r
- logging explicitly.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Core dumps are enabled by default.\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-If you are using a version from the Debian/Ubuntu autobuilder, it is\r
- compiled without optimization. Debug symbols are available in the i3-wm-dbg\r
- package. When compiling i3 yourself, debug mode is the default.\r
-</p>\r
-</li>\r
-</ol></div>\r
+<div class="paragraph"><p>Development versions of i3 have logging enabled by default and are compiled\r
+with debug symbols.</p></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_enabling_logging">2. Enabling logging</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>If you are using a development version (see previous section), you don’t need\r
+to do anything — skip to section 3.</p></div>\r
+<div class="paragraph"><p>If you are using a release version with a custom <tt>~/.xsession</tt> (or xinitrc)\r
+file, execute i3 with a line like this:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt># Use 25 MiB of RAM for debug logs\r
+exec i3 --shmlog-size=26214400</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>If you are <strong>NOT</strong> using an <tt>~/.xsession</tt> file but you just chose "i3" from the\r
+list of sessions in your desktop manager (gdm, lxdm, …), edit\r
+<tt>/usr/share/xsessions/i3.desktop</tt> and replace the <tt>Exec=i3</tt> line with:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>Exec=i3 --shmlog-size=26214400</tt></pre>\r
+</div></div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_obtaining_the_debug_logfile">2. Obtaining the debug logfile</h2>\r
+<h2 id="_obtaining_the_debug_logfile">3. Obtaining the debug logfile</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>No matter whether i3 misbehaved in some way without crashing or whether it just\r
crashed, the logfile provides all information necessary to debug the problem.</p></div>\r
bugreport), use:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>i3-dump-log | gzip -9c > /tmp/i3.log.gz</tt></pre>\r
-</div></div>\r
-<div class="paragraph"><p>This command does not depend on i3 (it also works when i3 currently displays\r
-the crash dialog), but it requires a working X11 connection. When running it\r
-from a virtual console (Ctrl-Alt-F1), use:</p></div>\r
-<div class="listingblock">\r
-<div class="content">\r
<pre><tt>DISPLAY=:0 i3-dump-log | gzip -9c > /tmp/i3.log.gz</tt></pre>\r
</div></div>\r
+<div class="paragraph"><p>This command does not depend on i3 (it also works while i3 displays\r
+the crash dialog), but it requires a working X11 connection.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_obtaining_a_backtrace">3. Obtaining a backtrace</h2>\r
+<h2 id="_compiling_with_debug_symbols">4. Compiling with debug symbols</h2>\r
<div class="sectionbody">\r
-<div class="paragraph"><p>When i3 displays its crash dialog, do the following:</p></div>\r
-<div class="olist arabic"><ol class="arabic">\r
-<li>\r
-<p>\r
-Switch to a virtual console (Ctrl-Alt-F1) or login from a different computer\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Generate a backtrace (see below)\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Switch back to the crash dialog (Ctrl-Alt-F7)\r
-</p>\r
-</li>\r
-<li>\r
-<p>\r
-Restart i3 in-place (you will keep your session), continue working\r
-</p>\r
-</li>\r
-</ol></div>\r
-<div class="paragraph"><p>This is how you get a backtrace from a running i3 process:</p></div>\r
+<div class="paragraph"><p>To actually get useful backtraces, you should make sure that your version of i3\r
+is compiled with debug symbols:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>I3PID=$(pidof i3)\r
-gdb /proc/$I3PID/exe $I3PID \\r
- --batch --quiet \\r
- --ex 'backtrace full' > /tmp/i3-backtrace.txt 2>&1</tt></pre>\r
+<pre><tt>$ file `which i3`\r
+/usr/bin/i3: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically\r
+linked (uses shared libs), for GNU/Linux 2.6.18, not stripped</tt></pre>\r
</div></div>\r
+<div class="paragraph"><p>Notice the <tt>not stripped</tt>, which is the important part. If you have a version\r
+which is stripped, please check whether your distribution provides debug\r
+symbols (package <tt>i3-wm-dbg</tt> on Debian for example) or if you can turn off\r
+stripping. If nothing helps, please build i3 from source.</p></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_obtaining_a_backtrace">5. Obtaining a backtrace</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>Once you have made sure that your i3 is compiled with debug symbols and the C\r
+debugger <tt>gdb</tt> is installed on your machine, you can let i3 generate a\r
+backtrace in the crash dialog.</p></div>\r
+<div class="paragraph"><p>After pressing "b" in the crash dialog, you will get a file called\r
+<tt>/tmp/i3-backtrace.%d.%d.txt</tt> where the first <tt>%d</tt> is replaced by i3’s process\r
+id (PID) and the second one is incremented each time you generate a backtrace,\r
+starting at 0.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_sending_bug_reports_debugging_on_irc">4. Sending bug reports/debugging on IRC</h2>\r
+<h2 id="_sending_bug_reports_debugging_on_irc">6. Sending bug reports/debugging on IRC</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>When sending bug reports, please attach the <strong>whole</strong> log file. Even if you think\r
you found the section which clearly highlights the problem, additional\r
projects / i3 / i3.github.io / blobdiff