"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/png" href="/favicon.png">\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.4" />\r
+<meta name="generator" content="AsciiDoc 8.6.9" />\r
<title>i3: Debugging i3: How To</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
-window.onload = function(){asciidoc.footnotes();}\r
+document.addEventListener("DOMContentLoaded", function(){asciidoc.footnotes();}, false);\r
/*]]>*/\r
</script>\r
<script type="text/javascript" src="/js/asciidoc-xhtml11.js"></script>\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="http://bugs.i3wm.org/">Bugs</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</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">March 2010</span>\r
+<span id="email"><tt><<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>></tt></span><br />\r
+<span id="revdate">January 2014</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
-<h2 id="_enabling_logging">1. Enabling logging</h2>\r
+<h2 id="_verify_you_are_using_i3_4_13">1. Verify you are using i3 ≥ 4.13</h2>\r
<div class="sectionbody">\r
-<div class="paragraph"><p>i3 spits out much information onto stdout, if told so. To have a clearly\r
-defined place where log files will be saved, you should redirect stdout and\r
-stderr in xsession. While you’re at it, putting each run of i3 in a separate\r
-log file with date/time in it is a good idea to not get confused about the\r
-different log files later on.</p></div>\r
+<div class="paragraph"><p>Only the latest major version of i3 is supported. To verify which version\r
+you are running, use:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>exec /usr/bin/i3 -V -d all >/home/michael/i3/i3log-$(date +'%F-%k-%M-%S') 2>&1</tt></pre>\r
+<pre><tt>$ i3 --moreversion 2>&- || i3 --version\r
+Binary i3 version: 4.7 (2013-12-22, branch "tags/4.7")\r
+Running i3 version: 4.7-84-gac74a63 (2014-01-01, branch "next") (pid 1995)</tt></pre>\r
</div></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.7 (release version)\r
+</dt>\r
+<dd>\r
+<p>\r
+You are using a release version. In many cases, bugs are already\r
+fixed in the development version of i3. Even if the bug is not a known fixed\r
+one, we will still ask you to reproduce your error with the most recent\r
+development version of i3. Therefore, please upgrade to a development version\r
+if you can.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+4.7-85-g9c15b95 (development version)\r
+</dt>\r
+<dd>\r
+<p>\r
+Your version is 85 commits newer than 4.7, and the git revision of your\r
+version is <tt>9c15b95</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 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_core_dumps">2. Enabling core dumps</h2>\r
+<h2 id="_enabling_logging">2. Enabling logging</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 .xsession, before starting i3):</p></div>\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>ulimit -c unlimited</tt></pre>\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>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="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>sudo sysctl -w kernel.core_pattern=core.%e.%p</tt></pre>\r
+<pre><tt>Exec=i3 --shmlog-size=26214400</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>If you cannot restart i3 for some reason, you can enable debug logging on the\r
+fly:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>i3-msg 'debuglog on; shmlog on; reload'</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">3. Compiling with debug symbols</h2>\r
+<h2 id="_reproducing_the_problem">3. Reproducing the problem</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 they are not stripped during the\r
-build process. You can check whether your executable contains symbols by\r
-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 class="paragraph"><p>Before submitting an issue, please make sure to close down on the problem as\r
+much as you can yourself. Here are some steps you should consider:</p></div>\r
+<div class="ulist"><ul>\r
+<li>\r
+<p>\r
+Find a deterministic, reliable way to reproduce the problem and provide it\r
+ with your bug report.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Try using the default i3 config to reproduce the problem. If the issue does\r
+ not appear with the default config, gradually adapt it to track down what\r
+ change(s) to the config introduce the problem.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Reproduce the problem with a minimal setup, i.e., only use as few applications,\r
+ windows and steps as necessary.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+In addition, try to stick to applications that are common and, even more\r
+ importantly, free / open source.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Before obtaining the log file, restart i3 in-place, execute the steps to\r
+ reproduce the problem and then save the logs. This keeps the log file as\r
+ small as possible and necessary.\r
+</p>\r
+</li>\r
+</ul></div>\r
+<div class="paragraph"><p>Please be aware that we cannot support compatibility issues with closed-source\r
+software, as digging into compatibility problems without having access to the\r
+source code is too time-consuming. Additionally, experience has shown that\r
+often, the software in question is responsible for the issue. Please raise an\r
+issue with the software in question, not i3.</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_the_debug_logfile">4. Obtaining the debug logfile</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="admonitionblock">\r
+<table><tr>\r
+<td class="icon">\r
+<div class="title">Caution</div>\r
+</td>\r
+<td class="content">\r
+<div class="paragraph"><p>Logs may contain sensitive information, so please inspect the log before\r
+submitting it. Logs may be viewed by anyone, once posted. If you choose to\r
+redact the log, make an effort not to discard information which may be relevant\r
+to the issue you are reporting.</p></div>\r
+<div class="paragraph"><p>The best way to avoid submitting such information is to only run the necessary\r
+steps to reproduce the behavior when saving the log file. This will also make\r
+analyzing the log file easier.</p></div>\r
+</td>\r
+</tr></table>\r
+</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 upload a compressed version of the logfile (for a bugreport), use:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>gdb $(which i3) core.i3.3849</tt></pre>\r
+<pre><tt>DISPLAY=:0 i3-dump-log | bzip2 -c | curl --data-binary @- http://logs.i3wm.org</tt></pre>\r
</div></div>\r
-<div class="paragraph"><p>Then, generate a backtrace using:</p></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 class="paragraph"><p>After running it, you will get a URL to the logfile. Please include that URL in\r
+your bug report.</p></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_on_crashes_obtaining_a_backtrace">5. On crashes: Obtaining a backtrace</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>When i3 crashes, it will display a dialog stating “i3 just crashed”, offering\r
+you to save a backtrace to a text file.</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>backtrace full</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 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">5. 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 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
length limitations) or flood kicks.</p></div>\r
</div>\r
</div>\r
+<div class="sect1">\r
+<h2 id="_debugging_i3bar">7. Debugging i3bar</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>To debug i3bar problems, add <tt>verbose yes</tt> to all <tt>bar {}</tt> blocks in your i3\r
+config, reload your config and then restart all i3bar instances like this:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ i3 reload\r
+$ killall i3bar\r
+$ for c in $(i3-msg -t get_bar_config | python -c \\r
+ 'import json,sys;print("\n".join(json.load(sys.stdin)))'); do \\r
+ (i3bar --bar_id=$c >i3bar.$c.log 2>&1) & \\r
+ done;</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>There will now be <tt>i3bar.*.log</tt> files in your current directory that you can provide\r
+in your bug report.</p></div>\r
+</div>\r
+</div>\r
</div>\r
<div id="footnotes"><hr /></div>\r
<div id="footer" lang="de">\r
projects / i3 / i3.github.io / blobdiff