documentation/debugging.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5 <title>Native Client: Debugging Tips</title>
   6 <link href="stylesheet.css" type="text/css" rel="stylesheet"></link>
   7 </head>
   8
   9 <body>
  10
  11 <div id="toplink">
  12 <a href="../README.html">Back to README</a>
  13 </div>
  14
  15 <h1>Debugging Tips</h1>
  16
  17 <p>
  18 This page describes strategies you can use to debug your modules.
  19 </p>
  20
  21 <p>
  22 Currently, you can't easily use interactive debuggers
  23 with Native Client modules.
  24 One reason is that Native Client modules' use of
  25 segmented memory protection confuses
  26 the kernel exception handler,
  27 which in turn interferes with handling breakpoints.
  28 Another is that
  29 the segmented structure of the Native Client address space
  30 interferes with symbol resolution.
  31 </p>
  32
  33 <p>
  34 We're actively working on improving the debuggability of Native Client modules.
  35 If you'd like to help, please volunteer!
  36 </p>
  37
  38
  39 <h3>
  40 Contents:
  41 </h3>
  42
  43 <ul>
  44 <li> <a href="#standalone">Design your module to run standalone</a>
  45 </li>
  46 <li> <a href="#compile">Catch errors at compile time</a>
  47 </li>
  48 <li> <a href="#printf">Use printf and assert if necessary</a>
  49      <ul>
  50      <li> <a href="#print-examples">Examples</a>
  51      <li> <a href="#launchbrowser">Launching the browser from the command line</a>
  52      </li>
  53      <li> <a href="#output">Platform-specific output locations</a>
  54      </li>
  55      </ul>
  56 </li>
  57 </ul>
  58
  59 <h2><a name="standalone" id="standalone"> </a> Design your module to run standalone </h2>
  60
  61 <p>
  62 If your module can run both as a standalone Linux or Mac application
  63 <em>and</em> within Native Client,
  64 then you can use a debugger such as GDB, KDbg, or Xcode
  65 to debug the standalone form of your application.
  66 </p>
  67
  68 <p>
  69 <strong>Note:</strong>
  70 Building standalone applications is not supported on Windows.
  71 </p>
  72
  73 <p>
  74 For examples of creating a module that also works standalone,
  75 see the <code>earth</code>, <code>life</code>, <code>tone</code>,
  76 and <code>voronoi</code> examples under <code>native_client/tests</code>.
  77 </p>
  78
  79 <h2><a name="compile"> </a> Catch errors at compile time </h2>
  80
  81 <p>
  82 It's easier to fix bugs you find at compile time
  83 than those you find at runtime.
  84 When you compile your module,
  85 use <code>gcc</code> flags such as
  86 <code>-Werror</code> and <code>-Wall</code>
  87 to help ensure that your code is as clean as possible.
  88 For example:
  89 </p>
  90
  91 <pre>
  92 <kbd>nacl-g++ earth.cc <b>-Wall -Werror</b> -O3 -mfpmath=sse -msse -fomit-frame-pointer -lpthread -lm -o earth_release.nexe</kbd>
  93 </pre>
  94
  95 <h2> <a name="printf"> </a> Use printf and assert if necessary</h2>
  96
  97 <p>
  98 If a bug doesn't appear in the standalone app version of a module,
  99 you might have to use
 100 <code>printf</code> and <code>assert</code>
 101 to debug your module when it runs in Native Client.
 102 </p>
 103
 104 <p>
 105 <b>Note:</b>
 106 Using <code>printf</code> can be useful on Linux and Mac,
 107 but it's more difficult on Windows.
 108 For the latest Windows testing tips, see the wiki page
 109 <a href="http://code.google.com/p/nativeclient/wiki/DebuggingModulesOnWindows">DebuggingModulesOnWindows</a>.
 110 </p>
 111
 112 <p>
 113 Some notes on using
 114 <code>printf</code> and <code>assert</code>:
 115 </p>
 116
 117 <ul>
 118 <li> On Linux and Mac, if you
 119      <a href="#launchbrowser">launch the browser from the command line</a>,
 120      you can see the output in the window where you entered the command.
 121      Otherwise, the output goes to a
 122      <a href="#output">platform-specific location</a>.
 123      </li>
 124 <li> We recommend that you call <code>printf</code> from only one thread.
 125      </li>
 126 <li> <code>assert</code> does not generate core dumps.
 127      </li>
 128 <li> Alongside your <code>printf</code> and <code>assert</code> output,
 129      you might see debugging output from other processes &mdash;
 130      the plug-in and <code>sel_ldr</code>.
 131 </ul>
 132
 133
 134 <h3> <a name="print-examples"></a> Examples </h3>
 135
 136 <p>
 137 Here's an example of using <code>printf</code>:
 138 </p>
 139
 140 <pre>
 141 #include &lt;stdio.h>
 142   ...
 143   printf("Multimedia system failed to initialize!  errno: %d\n", errno);
 144 </pre>
 145
 146 <p>
 147 Here's an example of using <code>assert</code>:
 148 </p>
 149
 150 <pre>
 151 #include &lt;assert.h>
 152
 153 int foo(int x) {
 154   assert(x != 0);
 155   ...
 156 }
 157 </pre>
 158
 159 <h3> <a name="launchbrowser"></a>Launching the browser from the command line</h3>
 160
 161 <p>
 162 On Linux and Mac, if you launch your browser from the command line,
 163 the output of <code>printf</code> and <code>assert</code> goes
 164 to the window you used to enter the command.
 165 Make sure the window has a large scroll buffer,
 166 so you don't lose output.
 167 Better yet, use the GNU Screen program
 168 or an Emacs shell,
 169 so you can easily search the output.
 170 </p>
 171
 172 <blockquote>
 173 <table summary="platform-specific instructions for launching Firefox from the command line">
 174 <tr align="left">
 175 <th>Platform</th> <th>How to launch Firefox from the command line</th>
 176 </tr>
 177 <tr>
 178   <td valign="top">Linux</td>
 179   <td> <code>/usr/bin/firefox2</code> </td>
 180 </tr>
 181 <tr>
 182   <td valign="top">Mac</td>
 183   <td> <code>/Applications/Firefox.app/Contents/MacOS/firefox-bin </code></td>
 184 </tr>
 185 <!--
 186 <tr>
 187   <td valign="top">Windows</td>
 188   <td>
 189   From Cygwin:
 190   <code>/cygdrive/c/Program\ Files/Mozilla\ Firefox/firefox.exe</code>
 191   <br>
 192   From cmd:
 193   <code>"C:\Program Files\Mozilla Firefox\firefox.exe"</code>
 194   </td>
 195 </tr>
 196 -->
 197 </table>
 198 </blockquote>
 199
 200
 201 <h3> <a name="output"></a>Platform-specific output locations</h3>
 202
 203 <p>
 204 If you launch the browser using a menu, button, or icon
 205 (rather than from the
 206 <a href="#launchbrowser">command line</a>)
 207 the output of <code>printf</code> or <code>assert</code> goes to a
 208 location that depends on the platform you're using.
 209 </p>
 210
 211 <blockquote>
 212 <table summary="platform-specific browser output locations">
 213 <tr align="left">
 214 <th>Platform</th> <th>Default output location</th>
 215 </tr>
 216 <tr>
 217 <td>Linux</td> <td> <code>$HOME/.xsession-errors</code> </td>
 218 </tr>
 219 <tr>
 220 <td>Mac</td> <td><code>/var/log/system.log</code></td>
 221 </tr>
 222 <!--
 223 <tr>
 224 <td>Windows</td> <td> <span class="comment">[PENDING: ?]</span> </td>
 225 </tr>
 226 -->
 227 </table>
 228 </blockquote>
 229
 230
 231 <p id="license">
 232 Except as otherwise
 233 <a href="http://code.google.com/policies.html#restrictions">noted</a>,
 234 the content of this page is licensed under a
 235 <a href="http://creativecommons.org/licenses/by/2.5/">Creative Commons
 236 Attribution 2.5 license</a>.
 237 </p>
 238
 239 </body>
 240 </html>