--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\r
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
+<head>\r
+<link rel="icon" type="image/x-icon" href="/favicon.ico">\r
+<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
+<meta name="generator" content="AsciiDoc 8.6.9" />\r
+<title>i3: Debugging i3: How To (release version)</title>\r
+<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
+<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
+<script type="text/javascript">\r
+/*<![CDATA[*/\r
+document.addEventListener("DOMContentLoaded", function(){asciidoc.footnotes();}, false);\r
+/*]]>*/\r
+</script>\r
+<script type="text/javascript" src="/js/asciidoc-xhtml11.js"></script>\r
+</head>\r
+<body class="article">\r
+\r
+ <div id="main">\r
+ <a href="/"><h1 id="title">i3 - improved tiling WM</h1></a>\r
+ <ul id="nav">\r
+ <li><a style="border-bottom: 2px solid #fff" href="/docs">Docs</a></li>\r
+ <li><a href="/screenshots">Screens</a></li>\r
+ <li><a href="https://www.reddit.com/r/i3wm/">FAQ</a></li>\r
+ <li><a href="/contact">Contact</a></li>\r
+ <li><a href="https://github.com/i3/i3/issues">Bugs</a></li>\r
+ </ul>\r
+ <br style="clear: both">\r
+<div id="content">\r
+<div id="header">\r
+<h1>Debugging i3: How To (release version)</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
+</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
+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
+<div class="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Note</div>\r
+</td>\r
+<td class="content">This document is for the release version of i3. If you are using a\r
+development version, please see <a href="debugging.html">Debugging i3: How To</a>\r
+instead.</td>\r
+</tr></table>\r
+</div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_consider_using_the_development_version">1. Consider using the development version</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>This document is for the release version of i3. 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 and continue reading at\r
+<a href="debugging.html">Debugging i3: How To</a>.</p></div>\r
+<div class="paragraph"><p>If you absolutely cannot upgrade to a development version of i3, you may\r
+continue reading this document.</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>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="listingblock">\r
+<div class="content">\r
+<pre><tt>exec /usr/bin/i3 >~/i3log-$(date +'%F-%k-%M-%S') 2>&1</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">3. 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>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_compiling_with_debug_symbols">4. Compiling with debug symbols</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="listingblock">\r
+<div class="content">\r
+<pre><tt>file $(which i3)</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>You should get an output like this:</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
+</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">5. Generating 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="listingblock">\r
+<div class="content">\r
+<pre><tt>backtrace full</tt></pre>\r
+</div></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\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 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 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
+length limitations) or flood kicks.</p></div>\r
+</div>\r
+</div>\r
+</div>\r
+<div id="footnotes"><hr /></div>\r
+<div id="footer" lang="de">\r
+© 2009-2011 Michael Stapelberg, <a href="/impress.html">Impressum</a>\r
+</div>\r
+</body>\r
+</html>\r
projects / i3 / i3.github.io / blobdiff