git.sur5r.net Git - i3/i3.github.io/blob - docs/debugging.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\r
   2     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
   4 <head>\r
   5 <link rel="icon" type="image/png" href="/favicon.png">\r
   6 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
   7 <meta name="generator" content="AsciiDoc 8.6.9" />\r
   8 <title>i3: Debugging i3: How To</title>\r
   9 <link rel="stylesheet" href="/css/style.css" type="text/css" />\r
  10 <link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
  11 <script type="text/javascript">\r
  12 /*<![CDATA[*/\r
  13 document.addEventListener("DOMContentLoaded", function(){asciidoc.footnotes();}, false);\r
  14 /*]]>*/\r
  15 </script>\r
  16 <script type="text/javascript" src="/js/asciidoc-xhtml11.js"></script>\r
  17 </head>\r
  18 <body class="article">\r
  19 \r
  20         <div id="main">\r
  21             <a href="/"><h1 id="title">i3 - improved tiling WM</h1></a>\r
  22                         <ul id="nav">\r
  23                                 <li><a style="border-bottom: 2px solid #fff" href="/docs">Docs</a></li>\r
  24                                 <li><a href="/screenshots">Screens</a></li>\r
  25                                 <li><a href="/contact">Contact</a></li>\r
  26                                 <li><a href="http://bugs.i3wm.org/">Bugs</a></li>\r
  27                         </ul>\r
  28         <br style="clear: both">\r
  29 <div id="content">\r
  30 <div id="header">\r
  31 <h1>Debugging i3: How To</h1>\r
  32 <span id="author">Michael Stapelberg</span><br />\r
  33 <span id="email"><tt>&lt;<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>&gt;</tt></span><br />\r
  34 <span id="revdate">January 2014</span>\r
  35 </div>\r
  36 <div id="preamble">\r
  37 <div class="sectionbody">\r
  38 <div class="paragraph"><p>This document describes how to debug i3 to send us useful bug\r
  39 reports, even if you have no knowledge of C programming.</p></div>\r
  40 <div class="paragraph"><p>Thank you for being interested in debugging i3. It really means\r
  41 something to us to get your bug fixed. If you have any questions about the\r
  42 process and/or need further help, do not hesitate to contact us!</p></div>\r
  43 </div>\r
  44 </div>\r
  45 <div class="sect1">\r
  46 <h2 id="_verify_you_are_using_i3_4_7">1. Verify you are using i3 ≥ 4.7</h2>\r
  47 <div class="sectionbody">\r
  48 <div class="paragraph"><p>Only the latest major version of i3 is supported, i.e. version 4.7 currently.\r
  49 To verify which version you are running, use:</p></div>\r
  50 <div class="listingblock">\r
  51 <div class="content">\r
  52 <pre><tt>$ i3 --moreversion 2&gt;&amp;- || i3 --version\r
  53 Binary i3 version:  4.7 (2013-12-22, branch "tags/4.7")\r
  54 Running i3 version: 4.7-84-gac74a63 (2014-01-01, branch "next") (pid 1995)</tt></pre>\r
  55 </div></div>\r
  56 <div class="paragraph"><p>Your version can look like this:</p></div>\r
  57 <div class="dlist"><dl>\r
  58 <dt class="hdlist1">\r
  59 4.7 (release version)\r
  60 </dt>\r
  61 <dd>\r
  62 <p>\r
  63 You are using a release version. In many cases, bugs are already\r
  64 fixed in the development version of i3. Even if the bug is not a known fixed\r
  65 one, we will still ask you to reproduce your error with the most recent\r
  66 development version of i3. Therefore, please upgrade to a development version\r
  67 if you can.\r
  68 </p>\r
  69 </dd>\r
  70 <dt class="hdlist1">\r
  71 4.7-85-g9c15b95 (development version)\r
  72 </dt>\r
  73 <dd>\r
  74 <p>\r
  75 Your version is 85 commits newer than 4.7, and the git revision of your\r
  76 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
  77 the line "commit" starts with the same revision. If so, you are using the\r
  78 latest version.\r
  79 </p>\r
  80 </dd>\r
  81 </dl></div>\r
  82 <div class="paragraph"><p>Development versions of i3 have logging enabled by default and are compiled\r
  83 with debug symbols.</p></div>\r
  84 </div>\r
  85 </div>\r
  86 <div class="sect1">\r
  87 <h2 id="_enabling_logging">2. Enabling logging</h2>\r
  88 <div class="sectionbody">\r
  89 <div class="paragraph"><p>If you are using a development version (see previous section), you don’t need\r
  90 to do anything&#8201;&#8212;&#8201;skip to section 3.</p></div>\r
  91 <div class="paragraph"><p>If you are using a release version with a custom <tt>~/.xsession</tt> (or xinitrc)\r
  92 file, execute i3 with a line like this:</p></div>\r
  93 <div class="listingblock">\r
  94 <div class="content">\r
  95 <pre><tt># Use 25 MiB of RAM for debug logs\r
  96 exec i3 --shmlog-size=26214400</tt></pre>\r
  97 </div></div>\r
  98 <div class="paragraph"><p>If you are <strong>NOT</strong> using an <tt>~/.xsession</tt> file but you just chose "i3" from the\r
  99 list of sessions in your desktop manager (gdm, lxdm, …), edit\r
 100 <tt>/usr/share/xsessions/i3.desktop</tt> and replace the <tt>Exec=i3</tt> line with:</p></div>\r
 101 <div class="listingblock">\r
 102 <div class="content">\r
 103 <pre><tt>Exec=i3 --shmlog-size=26214400</tt></pre>\r
 104 </div></div>\r
 105 <div class="paragraph"><p>If you cannot restart i3 for some reason, you can enable debug logging on the\r
 106 fly:</p></div>\r
 107 <div class="listingblock">\r
 108 <div class="content">\r
 109 <pre><tt>i3-msg 'debuglog on; shmlog on; reload'</tt></pre>\r
 110 </div></div>\r
 111 </div>\r
 112 </div>\r
 113 <div class="sect1">\r
 114 <h2 id="_obtaining_the_debug_logfile">3. Obtaining the debug logfile</h2>\r
 115 <div class="sectionbody">\r
 116 <div class="paragraph"><p>No matter whether i3 misbehaved in some way without crashing or whether it just\r
 117 crashed, the logfile provides all information necessary to debug the problem.</p></div>\r
 118 <div class="paragraph"><p>To save a compressed version of the logfile (suitable for attaching it to a\r
 119 bugreport), use:</p></div>\r
 120 <div class="listingblock">\r
 121 <div class="content">\r
 122 <pre><tt>DISPLAY=:0 i3-dump-log | bzip2 -c &gt; /tmp/i3.log.bz2</tt></pre>\r
 123 </div></div>\r
 124 <div class="paragraph"><p>This command does not depend on i3 (it also works while i3 displays\r
 125 the crash dialog), but it requires a working X11 connection.</p></div>\r
 126 </div>\r
 127 </div>\r
 128 <div class="sect1">\r
 129 <h2 id="_on_crashes_obtaining_a_backtrace">4. On crashes: Obtaining a backtrace</h2>\r
 130 <div class="sectionbody">\r
 131 <div class="paragraph"><p>When i3 crashes, it will display a dialog stating “i3 just crashed”, offering\r
 132 you to save a backtrace to a text file.</p></div>\r
 133 <div class="paragraph"><p>To actually get useful backtraces, you should make sure that your version of i3\r
 134 is compiled with debug symbols:</p></div>\r
 135 <div class="listingblock">\r
 136 <div class="content">\r
 137 <pre><tt>$ file `which i3`\r
 138 /usr/bin/i3: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically\r
 139 linked (uses shared libs), for GNU/Linux 2.6.18, not stripped</tt></pre>\r
 140 </div></div>\r
 141 <div class="paragraph"><p>Notice the <tt>not stripped</tt>, which is the important part. If you have a version\r
 142 which is stripped, please check whether your distribution provides debug\r
 143 symbols (package <tt>i3-wm-dbg</tt> on Debian for example) or if you can turn off\r
 144 stripping. If nothing helps, please build i3 from source.</p></div>\r
 145 <div class="paragraph"><p>Once you have made sure that your i3 is compiled with debug symbols and the C\r
 146 debugger <tt>gdb</tt> is installed on your machine, you can let i3 generate a\r
 147 backtrace in the crash dialog.</p></div>\r
 148 <div class="paragraph"><p>After pressing "b" in the crash dialog, you will get a file called\r
 149 <tt>/tmp/i3-backtrace.%d.%d.txt</tt> where the first <tt>%d</tt> is replaced by i3’s process\r
 150 id (PID) and the second one is incremented each time you generate a backtrace,\r
 151 starting at 0.</p></div>\r
 152 </div>\r
 153 </div>\r
 154 <div class="sect1">\r
 155 <h2 id="_sending_bug_reports_debugging_on_irc">5. Sending bug reports/debugging on IRC</h2>\r
 156 <div class="sectionbody">\r
 157 <div class="paragraph"><p>When sending bug reports, please attach the <strong>whole</strong> log file. Even if you think\r
 158 you found the section which clearly highlights the problem, additional\r
 159 information might be necessary to completely diagnose the problem.</p></div>\r
 160 <div class="paragraph"><p>When debugging with us in IRC, be prepared to use a so called nopaste service\r
 161 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
 162 amounts of text in IRC sometimes leads to incomplete lines (servers have line\r
 163 length limitations) or flood kicks.</p></div>\r
 164 </div>\r
 165 </div>\r
 166 </div>\r
 167 <div id="footnotes"><hr /></div>\r
 168 <div id="footer" lang="de">\r
 169 © 2009-2011 Michael Stapelberg, <a href="/impress.html">Impressum</a>\r
 170 </div>\r
 171 </body>\r
 172 </html>\r