<div id="header">\r
<h1>Debugging i3: How To</h1>\r
<span id="author">Michael Stapelberg</span><br />\r
-<span id="email"><tt><<a href="mailto:michael+i3@stapelberg.de">michael+i3@stapelberg.de</a>></tt></span><br />\r
-<span id="revdate">July 2011</span>\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
</div>\r
<div id="preamble">\r
<div class="sectionbody">\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_enabling_logging">1. Enabling logging</h2>\r
+<h2 id="_verify_you_are_using_the_latest_development_version">1. Verify you are using the latest (development) version</h2>\r
<div class="sectionbody">\r
-<div class="paragraph"><p>i3 logs useful information to stdout. To have a clearly defined place where log\r
-files will be saved, you should redirect stdout and stderr in your\r
-<tt>~/.xsession</tt>. While you’re at it, putting each run of i3 in a separate log\r
-file with date/time in its filename is a good idea to not get confused about\r
-the different log files later on.</p></div>\r
+<div class="paragraph"><p>Please verify that you are using the latest version of i3:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>exec /usr/bin/i3 >~/i3log-$(date +'%F-%k-%M-%S') 2>&1</tt></pre>\r
+<pre><tt>$ i3 --version\r
+i3 version 4.1.2-248-g51728ba (2012-02-12, branch "next")</tt></pre>\r
</div></div>\r
-<div class="paragraph"><p>To enable verbose output and all levels of debug output (required when\r
-attaching logfiles to bugreports), add the parameters <tt>-V -d all</tt>, like this:</p></div>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>exec /usr/bin/i3 -V -d all >~/i3log-$(date +'%F-%k-%M-%S') 2>&1</tt></pre>\r
-</div></div>\r
-</div>\r
-</div>\r
-<div class="sect1">\r
-<h2 id="_enabling_core_dumps">2. Enabling core dumps</h2>\r
-<div class="sectionbody">\r
-<div class="paragraph"><p>When i3 crashes, often you have the chance of getting a <em>core dump</em> (an image\r
-of the memory of the i3 process which can be loaded into a debugger). To get a\r
-core dump, you have to make sure that the user limit for core dump files is set\r
-high enough. Many systems ship with a default value which even forbids core\r
-dumps completely. To disable the limit completely and thus enable core dumps,\r
-use the following command (in your <tt>~/.xsession</tt>, before starting i3):</p></div>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>ulimit -c unlimited</tt></pre>\r
-</div></div>\r
-<div class="paragraph"><p>Furthermore, to easily recognize core dumps and allow multiple of them, you\r
-should set a custom core dump filename pattern, using a command like the\r
-following:</p></div>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>sudo sysctl -w kernel.core_pattern=core.%e.%p</tt></pre>\r
-</div></div>\r
-<div class="paragraph"><p>This will generate files which have the executable’s file name (%e) and the\r
-process id (%p) in it. You can save this setting across reboots using\r
-<tt>/etc/sysctl.conf</tt>.</p></div>\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
+</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
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+4.1.2-248-g51728ba\r
+</dt>\r
+<dd>\r
+<p>\r
+Your version is 248 commits newer than 4.1.2, and the git revision of your\r
+version is <tt>51728ba</tt>. Go to <a href="http://code.i3wm.org/i3/commit/?h=next">http://code.i3wm.org/i3/commit/?h=next</a> and see if\r
+the line "commit" starts with the same revision. If so, you are using the\r
+latest version.\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>\r
</div>\r
<div class="sect1">\r
-<h2 id="_compiling_with_debug_symbols">3. Compiling with debug symbols</h2>\r
+<h2 id="_obtaining_the_debug_logfile">2. Obtaining the debug logfile</h2>\r
<div class="sectionbody">\r
-<div class="paragraph"><p>To actually get useful core dumps, you should make sure that your version of i3\r
-is compiled with debug symbols, that is, that the symbols are not stripped\r
-during the build process. You can check whether your executable contains\r
-symbols by issuing the following command:</p></div>\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
+<div class="paragraph"><p>To save a compressed version of the logfile (suitable for attaching it to a\r
+bugreport), use:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>file $(which i3)</tt></pre>\r
+<pre><tt>i3-dump-log | gzip -9c > /tmp/i3.log.gz</tt></pre>\r
</div></div>\r
-<div class="paragraph"><p>You should get an output like this:</p></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>/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
+<pre><tt>DISPLAY=:0 i3-dump-log | gzip -9c > /tmp/i3.log.gz</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 have a look if 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="_generating_a_backtrace">4. Generating a backtrace</h2>\r
+<h2 id="_obtaining_a_backtrace">3. 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 that\r
-core dumps are enabled, you can start making sense out of the core dumps.</p></div>\r
-<div class="paragraph"><p>Because the core dump depends on the original executable (and its debug\r
-symbols), please do this as soon as you encounter the problem. If you\r
-re-compile i3, your core dump might be useless afterwards.</p></div>\r
-<div class="paragraph"><p>Please install <tt>gdb</tt>, a debugger for C. No worries, you don’t need to learn it\r
-now. Start gdb using the following command (replacing the actual name of the\r
-core dump of course):</p></div>\r
-<div class="listingblock">\r
-<div class="content">\r
-<pre><tt>gdb $(which i3) core.i3.3849</tt></pre>\r
-</div></div>\r
-<div class="paragraph"><p>Then, generate a backtrace using:</p></div>\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="listingblock">\r
<div class="content">\r
-<pre><tt>backtrace full</tt></pre>\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
</div></div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_sending_bug_reports_debugging_on_irc">5. Sending bug reports/debugging on IRC</h2>\r
+<h2 id="_sending_bug_reports_debugging_on_irc">4. Sending bug reports/debugging on IRC</h2>\r
<div class="sectionbody">\r
-<div class="paragraph"><p>When sending bug reports, please paste the relevant part of the log (if in\r
-doubt, please send us rather too much information than too less) and the whole\r
-backtrace (if there was a core dump).</p></div>\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
+information might be necessary to completely diagnose the problem.</p></div>\r
<div class="paragraph"><p>When debugging with us in IRC, be prepared to use a so called nopaste service\r
such as <a href="http://nopaste.info">http://nopaste.info</a> or <a href="http://pastebin.com">http://pastebin.com</a> because pasting large\r
amounts of text in IRC sometimes leads to incomplete lines (servers have line\r
projects / i3 / i3.github.io / blobdiff