1 {{+bindTo:partials.standard_nacl_article}} 2 3 <section id="debugging"> 4 <span id="devcycle-debugging"></span><h1 id="debugging"><span id="devcycle-debugging"></span>Debugging</h1> 5 <p>This document describes tools and techniques you can use to debug, monitor, 6 and measure your application’s performance.</p> 7 <div class="contents local" id="table-of-contents" style="display: none"> 8 <p class="topic-title first">Table Of Contents</p> 9 <ul class="small-gap"> 10 <li><p class="first"><a class="reference internal" href="#diagnostic-information" id="id2">Diagnostic information</a></p> 11 <ul class="small-gap"> 12 <li><a class="reference internal" href="#viewing-process-statistics-with-the-task-manager" id="id3">Viewing process statistics with the task manager</a></li> 13 <li><a class="reference internal" href="#controlling-the-level-of-native-client-error-and-warning-messages" id="id4">Controlling the level of Native Client error and warning messages</a></li> 14 </ul> 15 </li> 16 <li><p class="first"><a class="reference internal" href="#basic-debugging" id="id5">Basic debugging</a></p> 17 <ul class="small-gap"> 18 <li><a class="reference internal" href="#writing-messages-to-the-javascript-console" id="id6">Writing messages to the JavaScript console</a></li> 19 <li><p class="first"><a class="reference internal" href="#debugging-with-printf" id="id7">Debugging with printf</a></p> 20 <ul class="small-gap"> 21 <li><a class="reference internal" href="#redirecting-output-to-log-files" id="id8">Redirecting output to log files</a></li> 22 <li><a class="reference internal" href="#redirecting-output-to-the-javascript-console" id="id9">Redirecting output to the JavaScript console</a></li> 23 </ul> 24 </li> 25 <li><a class="reference internal" href="#logging-calls-to-pepper-interfaces" id="id10">Logging calls to Pepper interfaces</a></li> 26 <li><a class="reference internal" href="#debugging-with-visual-studio" id="id11">Debugging with Visual Studio</a></li> 27 <li><p class="first"><a class="reference internal" href="#debugging-with-nacl-gdb" id="id12">Debugging with nacl-gdb</a></p> 28 <ul class="small-gap"> 29 <li><a class="reference internal" href="#debugging-pnacl-pexes-with-pepper-35" id="id13">Debugging PNaCl pexes (with Pepper 35+)</a></li> 30 <li><a class="reference internal" href="#debugging-pnacl-pexes-with-older-pepper-toolchains" id="id14">Debugging PNaCl pexes (with older Pepper toolchains)</a></li> 31 <li><a class="reference internal" href="#running-nacl-gdb" id="id15">Running nacl-gdb</a></li> 32 </ul> 33 </li> 34 </ul> 35 </li> 36 <li><p class="first"><a class="reference internal" href="#debugging-with-other-tools" id="id16">Debugging with other tools</a></p> 37 <ul class="small-gap"> 38 <li><a class="reference internal" href="#open-source-profiling-tools" id="id17">Open source profiling tools</a></li> 39 </ul> 40 </li> 41 </ul> 42 43 </div><section id="diagnostic-information"> 44 <h2 id="diagnostic-information">Diagnostic information</h2> 45 <section id="viewing-process-statistics-with-the-task-manager"> 46 <h3 id="viewing-process-statistics-with-the-task-manager">Viewing process statistics with the task manager</h3> 47 <p>You can use Chrome’s Task Manager to display information about a Native Client 48 application:</p> 49 <ol class="arabic simple"> 50 <li>Open the Task Manager by clicking the menu icon <img alt="menu-icon" src="/native-client/images/menu-icon.png" /> and choosing 51 <strong>Tools > Task manager</strong>.</li> 52 <li>When the Task Manager window appears, verify that the columns displaying 53 memory information are visible. If they are not, right click in the header 54 row and select the memory items from the popup menu that appears.</li> 55 </ol> 56 <p>A browser window running a Native Client application will have at least two 57 processes associated with it: a process for the app’s top level (the render 58 process managing the page including its HTML and any JavaScript) and one or 59 more processes for each instance of a Native Client module embedded in the page 60 (each process running native code from one nexe file). The top-level process 61 appears with the application’s icon and begins with the text “App:”. A Native 62 Client process appears with a Chrome extension icon (a jigsaw puzzle piece 63 <img alt="puzzle" src="/native-client/images/puzzle.png" />) and begins with the text “Native Client module” followed by the URL 64 of its manifest file.</p> 65 <p>From the Task Manager you can view the changing memory allocations of all the 66 processes associated with a Native Client application. Each process has its own 67 memory footprint. You can also see the rendering rate displayed as frames per 68 second (FPS). Note that the computation of render frames can be performed in 69 any process, but the rendering itself is always done in the top level 70 application process, so look for the rendering rate there.</p> 71 </section><section id="controlling-the-level-of-native-client-error-and-warning-messages"> 72 <h3 id="controlling-the-level-of-native-client-error-and-warning-messages">Controlling the level of Native Client error and warning messages</h3> 73 <p>Native Client prints warning and error messages to stdout and stderr. You can 74 increase the amount of Native Client’s diagnostic output by setting the 75 following <a class="reference external" href="http://en.wikipedia.org/wiki/Environment_variable">environment variables</a>:</p> 76 <ul class="small-gap"> 77 <li>NACL_DEBUG_ENABLE=1</li> 78 <li>PPAPI_BROWSER_DEBUG=1</li> 79 <li>NACL_PLUGIN_DEBUG=1</li> 80 <li>NACL_PPAPI_PROXY_DEBUG=1</li> 81 <li>NACL_SRPC_DEBUG=[1-255] (use a higher number for more verbose debug output)</li> 82 <li>NACLVERBOSITY=[1-255]</li> 83 </ul> 84 </section></section><section id="basic-debugging"> 85 <h2 id="basic-debugging">Basic debugging</h2> 86 <section id="writing-messages-to-the-javascript-console"> 87 <h3 id="writing-messages-to-the-javascript-console">Writing messages to the JavaScript console</h3> 88 <p>You can send messages from your C/C++ code to JavaScript using the PostMessage 89 call in the <a class="reference internal" href="/native-client/devguide/coding/message-system.html"><em>Pepper messaging system</em></a>. When the 90 JavaScript code receives a message, its message event handler can call 91 <a class="reference external" href="https://developer.mozilla.org/en/DOM/console.log">console.log()</a> to write 92 the message to the JavaScript <a class="reference external" href="/devtools/docs/console-api">console</a> in 93 Chrome’s Developer Tools.</p> 94 </section><section id="debugging-with-printf"> 95 <h3 id="debugging-with-printf">Debugging with printf</h3> 96 <p>Your C/C++ code can perform inline printf debugging to stdout and stderr by 97 calling fprintf() directly, or by using cover functions like these:</p> 98 <pre class="prettyprint"> 99 #include <stdio.h> 100 void logmsg(const char* pMsg){ 101 fprintf(stdout,"logmsg: %s\n",pMsg); 102 } 103 void errormsg(const char* pMsg){ 104 fprintf(stderr,"logerr: %s\n",pMsg); 105 } 106 </pre> 107 <p>By default stdout and stderr will appear in Chrome’s stdout and stderr stream 108 but they can also be redirected as described below.</p> 109 <section id="redirecting-output-to-log-files"> 110 <h4 id="redirecting-output-to-log-files">Redirecting output to log files</h4> 111 <p>You can redirect stdout and stderr to output files by setting these environment variables:</p> 112 <ul class="small-gap"> 113 <li><code>NACL_EXE_STDOUT=c:\nacl_stdout.log</code></li> 114 <li><code>NACL_EXE_STDERR=c:\nacl_stderr.log</code></li> 115 </ul> 116 <p>There is another variable, <code>NACLLOG</code>, that you can use to redirect Native 117 Client’s internally-generated messages. This variable is set to stderr by 118 default; you can redirect these messages to an output file by setting the 119 variable as follows:</p> 120 <ul class="small-gap"> 121 <li><code>NACLLOG=c:\nacl.log</code></li> 122 </ul> 123 <aside class="note"> 124 <strong>Note:</strong> If you set the NACL_EXE_STDOUT, NACL_EXE_STDERR, or NACLLOG 125 variables to redirect output to a file, you must run Chrome with the 126 <code>--no-sandbox</code> flag. You must also be careful that each variable points to 127 a different file. 128 </aside> 129 </section><section id="redirecting-output-to-the-javascript-console"> 130 <h4 id="redirecting-output-to-the-javascript-console">Redirecting output to the JavaScript console</h4> 131 <p>You can also cause output from printf statements in your C/C++ code to be 132 relayed to the JavaScript side of your application through the Pepper messaging 133 system, where you can then write the output to the JavaScript console. Follow 134 these steps:</p> 135 <ol class="arabic"> 136 <li><p class="first">Set the NACL_EXE_STDOUT and NACL_EXE_STDERR environment variables as 137 follows:</p> 138 <ul class="small-gap"> 139 <li><p class="first">NACL_EXE_STDOUT=DEBUG_ONLY:dev://postmessage</p> 140 </li> 141 <li><p class="first">NACL_EXE_STDERR=DEBUG_ONLY:dev://postmessage</p> 142 </li> 143 </ul> 144 <p>These settings tell Native Client to use PostMessage() to send output that 145 your Native Client module writes to stdout and stderr to the JavaScript side 146 of your application.</p> 147 </li> 148 <li><p class="first">Register a JavaScript handler to receive messages from your Native Client 149 module:</p> 150 <pre class="prettyprint"> 151 <div id="nacl_container"> 152 <script type="text/javascript"> 153 var container = document.getElementById('nacl_container'); 154 container.addEventListener('message', handleMessage, true); 155 </script> 156 <embed id="nacl_module" 157 src="my_application.nmf" 158 type="application/x-nacl" /> 159 </div> 160 </pre> 161 </li> 162 <li><p class="first">Implement a simple JavaScript handler that logs the messages it receives to 163 the JavaScript console:</p> 164 <pre class="prettyprint"> 165 function handleMessage(message_event) { 166 console.log(message_event.data); 167 } 168 </pre> 169 <p>This handler works in the simple case where the only messages your Native 170 Client module sends to JavaScript are messages with the output from stdout 171 and stderr. If your Native Client module also sends other messages to 172 JavaScript, your handler will need to be more complex.</p> 173 <p>Once you’ve implemented a message handler and set up the environment 174 variables as described above, you can check the JavaScript console to see 175 output that your Native Client module prints to stdout and stderr. Keep in 176 mind that your module makes a call to PostMessage() every time it flushes 177 stdout or stderr. Your application’s performance will degrade considerably 178 if your module prints and flushes frequently, or if it makes frequent Pepper 179 calls to begin with (e.g., to render).</p> 180 </li> 181 </ol> 182 </section></section><section id="logging-calls-to-pepper-interfaces"> 183 <h3 id="logging-calls-to-pepper-interfaces">Logging calls to Pepper interfaces</h3> 184 <p>You can log all Pepper calls your module makes by passing the following flags 185 to Chrome on startup:</p> 186 <pre class="prettyprint"> 187 --vmodule=ppb*=4 --enable-logging=stderr 188 </pre> 189 <p>The <code>vmodule</code> flag tells Chrome to log all calls to C Pepper interfaces that 190 begin with “ppb” (that is, the interfaces that are implemented by the browser 191 and that your module calls). The <code>enable-logging</code> flag tells Chrome to log 192 the calls to stderr.</p> 193 </section><section id="debugging-with-visual-studio"> 194 <span id="visual-studio"></span><h3 id="debugging-with-visual-studio"><span id="visual-studio"></span>Debugging with Visual Studio</h3> 195 <p>If you develop on a Windows platform you can use the <a class="reference internal" href="/native-client/devguide/devcycle/vs-addin.html"><em>Native Client Visual 196 Studio add-in</em></a> to write and debug your code. The add-in defines new 197 project platforms that let you run your module in two different modes: As a 198 Pepper plugin and as a Native Client module. When running as a Pepper plugin 199 you can use the built-in Visual Studio debugger. When running as a Native 200 Client module Visual Studio will launch an instance of nacl-gdb for you and 201 link it to the running code.</p> 202 </section><section id="debugging-with-nacl-gdb"> 203 <span id="using-gdb"></span><h3 id="debugging-with-nacl-gdb"><span id="using-gdb"></span>Debugging with nacl-gdb</h3> 204 <p>The Native Client SDK includes a command-line debugger that you can use to 205 debug Native Client modules. The debugger is based on the GNU debugger <a class="reference external" href="http://www.gnu.org/software/gdb/">gdb</a>, and is located at 206 <code>toolchain/<platform>_x86_newlib/bin/x86_64-nacl-gdb</code> (where <em><platform></em> 207 is the platform of your development machine: <code>win</code>, <code>mac</code>, or 208 <code>linux</code>).</p> 209 <p>Note that this same copy of GDB can be used to debug any NaCl program, 210 whether built using newlib or glibc for x86-32, x86-64 or ARM. In the SDK, 211 <code>i686-nacl-gdb</code> is an alias for <code>x86_64-nacl-gdb</code>, and the <code>newlib</code> 212 and <code>glibc</code> toolchains both contain the same version of GDB.</p> 213 <section id="debugging-pnacl-pexes-with-pepper-35"> 214 <span id="debugging-pnacl-pexes"></span><h4 id="debugging-pnacl-pexes-with-pepper-35"><span id="debugging-pnacl-pexes"></span>Debugging PNaCl pexes (with Pepper 35+)</h4> 215 <p>If you want to use GDB to debug a program that is compiled with the PNaCl 216 toolchain, you must have a copy of the pexe from <strong>before</strong> running 217 <code>pnacl-finalize</code>. The <code>pnacl-finalize</code> tool converts LLVM bitcode 218 to the stable PNaCl bitcode format, but it also strips out debug 219 metadata, which we need for debugging. In this section we’ll give the 220 LLVM bitcode file a <code>.bc</code> file extension, and the PNaCl bitcode file 221 a <code>.pexe</code> file extension. The actual extension should not matter, but 222 it helps distinguish between the two types of files.</p> 223 <p><strong>Note</strong> unlike the finalized copy of the pexe, the non-finalized debug copy 224 is not considered stable. This means that a debug copy of the PNaCl 225 application created by a Pepper N SDK is only guaranteed to run 226 with a matching Chrome version N. If the version of the debug bitcode pexe 227 does not match that of Chrome then the translation process may fail, and 228 you will see and error message in the JavaScript console.</p> 229 <p>Also, make sure you are passing the <code>-g</code> <a class="reference internal" href="/native-client/devguide/devcycle/building.html#compile-flags"><em>compile option</em></a> to <code>pnacl-clang</code> to enable generating debugging info. 230 You might also want to omit <code>-O2</code> from the compile-time and link-time 231 options, otherwise GDB not might be able to print variables’ values when 232 debugging (this is more of a problem with the PNaCl/LLVM toolchain than 233 with GCC).</p> 234 <p>Once you have built a non-stable debug copy of the pexe, list the URL of 235 that copy in your application’s manifest file:</p> 236 <pre class="prettyprint"> 237 { 238 "program": { 239 "pnacl-translate": { 240 "url": "release_version.pexe", 241 "optlevel": 2 242 }, 243 "pnacl-debug": { 244 "url": "debug_version.bc", 245 "optlevel": 0 246 } 247 } 248 } 249 </pre> 250 <p>Copy the <code>debug_version.bc</code> and <code>nmf</code> files to the location that 251 your local web server serves files from.</p> 252 <p>When you run Chrome with <code>--enable-nacl-debug</code>, Chrome will translate 253 and run the <code>debug_version.bc</code> instead of <code>release_version.pexe</code>. 254 Once the debug version is loaded, you are ready to <a class="reference internal" href="#running-nacl-gdb"><em>run nacl-gdb</em></a></p> 255 <p>Whether you publish the NMF file containing the debug URL to the release 256 web server, is up to you. One reason to avoid publishing the debug URL 257 is that it is only guaranteed to work for the Chrome version that matches 258 the SDK version. Developers who may have left the <code>--enable-nacl-debug</code> 259 flag turned on may end up loading the debug copy of your application 260 (which may or may not work, depending on their version of Chrome).</p> 261 </section><section id="debugging-pnacl-pexes-with-older-pepper-toolchains"> 262 <h4 id="debugging-pnacl-pexes-with-older-pepper-toolchains">Debugging PNaCl pexes (with older Pepper toolchains)</h4> 263 <p>If you want to use GDB to debug a program that is compiled with the PNaCl 264 toolchain, you must convert the <code>pexe</code> file to a <code>nexe</code>. (You can skip 265 this step if you are using the GCC toolchain, or if you are using 266 pepper 35 or later.)</p> 267 <ul class="small-gap"> 268 <li>Firstly, make sure you are passing the <code>-g</code> <a class="reference internal" href="/native-client/devguide/devcycle/building.html#compile-flags"><em>compile option</em></a> to <code>pnacl-clang</code> to enable generating debugging info. 269 You might also want to omit <code>-O2</code> from the compile-time and link-time 270 options.</li> 271 <li><p class="first">Secondly, use <code>pnacl-translate</code> to convert your <code>pexe</code> to one or more 272 <code>nexe</code> files. For example:</p> 273 <pre> 274 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-translate ^ 275 --allow-llvm-bitcode-input hello_world.pexe -arch x86-32 -o hello_world_x86_32.nexe 276 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-translate ^ 277 --allow-llvm-bitcode-input hello_world.pexe -arch x86-64 -o hello_world_x86_64.nexe 278 </pre> 279 <p>For this, use the non-finalized <code>pexe</code> file produced by 280 <code>pnacl-clang</code>, not the <code>pexe</code> file produced by <code>pnacl-finalize</code>. 281 The latter <code>pexe</code> has debugging info stripped out. The option 282 <code>--allow-llvm-bitcode-input</code> tells <code>pnacl-translate</code> to accept a 283 non-finalized <code>pexe</code>.</p> 284 </li> 285 <li><p class="first">Replace the <code>nmf</code> <a class="reference internal" href="/native-client/devguide/coding/application-structure.html#manifest-file"><em>manifest file</em></a> that points to 286 your <code>pexe</code> file with one that points to the <code>nexe</code> files. For the 287 example <code>nexe</code> filenames above, the new <code>nmf</code> file would contain:</p> 288 <pre> 289 { 290 "program": { 291 "x86-32": {"url": "hello_world_x86_32.nexe"}, 292 "x86-64": {"url": "hello_world_x86_64.nexe"}, 293 } 294 } 295 </pre> 296 </li> 297 <li>Change the <code><embed></code> HTML element to use 298 <code>type="application/x-nacl"</code> rather than 299 <code>type="application/x-pnacl"</code>.</li> 300 <li>Copy the <code>nexe</code> and <code>nmf</code> files to the location that your local web 301 server serves files from.</li> 302 </ul> 303 <aside class="note"> 304 <strong>Note:</strong> If you know whether Chrome is using the x86-32 or x86-64 305 version of the NaCl sandbox on your system, you can translate the 306 <code>pexe</code> once to a single x86-32 or x86-64 <code>nexe</code>. Otherwise, you 307 might find it easier to translate the <code>pexe</code> to both <code>nexe</code> 308 formats as described above. 309 </aside> 310 </section><section id="running-nacl-gdb"> 311 <span id="id1"></span><h4 id="running-nacl-gdb"><span id="id1"></span>Running nacl-gdb</h4> 312 <p>Before you start using nacl-gdb, make sure you can <a class="reference internal" href="/native-client/devguide/devcycle/building.html"><em>build</em></a> your 313 module and <a class="reference internal" href="/native-client/devguide/devcycle/running.html"><em>run</em></a> your application normally. This will verify 314 that you have created all the required <a class="reference internal" href="/native-client/devguide/coding/application-structure.html"><em>application parts</em></a> (.html, .nmf, and .nexe files, shared 315 libraries, etc.), that your server can access those resources, and that you’ve 316 configured Chrome correctly to run your application. The instructions below 317 assume that you are using a <a class="reference internal" href="/native-client/devguide/devcycle/running.html#web-server"><em>local server</em></a> to run your 318 application; one benefit of doing it this way is that you can check the web 319 server output to confirm that your application is loading the correct 320 resources. However, some people prefer to run their application as an unpacked 321 extension, as described in <a class="reference internal" href="/native-client/devguide/devcycle/running.html"><em>Running Native Client Applications</em></a>.</p> 322 <p>Follow the instructions below to debug your module with nacl-gdb:</p> 323 <ol class="arabic"> 324 <li><p class="first">Compile your module with the <code>-g</code> flag so that your .nexe retains symbols 325 and other debugging information (see the <a class="reference internal" href="/native-client/devguide/devcycle/building.html#compile-flags"><em>recommended compile flags</em></a>).</p> 326 </li> 327 <li><p class="first">Launch a local web server (e.g., the <a class="reference internal" href="/native-client/devguide/devcycle/running.html#web-server"><em>web server</em></a> included 328 in the SDK).</p> 329 </li> 330 <li><p class="first">Launch Chrome with these three required flags: <code>--enable-nacl --enable-nacl-debug --no-sandbox</code>.</p> 331 <p>You may also want to use some of the optional flags listed below. A typical 332 command looks like this:</p> 333 <pre class="prettyprint"> 334 chrome --enable-nacl --enable-nacl-debug --no-sandbox --disable-hang-monitor localhost:5103 335 </pre> 336 <p><strong>Required flags:</strong></p> 337 <dl class="docutils"> 338 <dt><code>--enable-nacl</code></dt> 339 <dd><p class="first last">Enables Native Client for all applications, including those that are 340 launched outside the Chrome Web Store.</p> 341 </dd> 342 <dt><code>--enable-nacl-debug</code></dt> 343 <dd><p class="first last">Turns on the Native Client debug stub, opens TCP port 4014, and pauses 344 Chrome to let the debugger connect.</p> 345 </dd> 346 <dt><code>--no-sandbox</code></dt> 347 <dd><p class="first last">Turns off the Chrome sandbox (not the Native Client sandbox). This enables 348 the stdout and stderr streams, and lets the debugger connect.</p> 349 </dd> 350 </dl> 351 <p><strong>Optional flags:</strong></p> 352 <dl class="docutils"> 353 <dt><code>--disable-hang-monitor</code></dt> 354 <dd><p class="first last">Prevents Chrome from displaying a warning when a tab is unresponsive.</p> 355 </dd> 356 <dt><code>--user-data-dir=<directory></code></dt> 357 <dd><p class="first last">Specifies the <a class="reference external" href="http://www.chromium.org/user-experience/user-data-directory">user data directory</a> from which 358 Chrome should load its state. You can specify a different user data 359 directory so that changes you make to Chrome in your debugging session do 360 not affect your personal Chrome data (history, cookies, bookmarks, themes, 361 and settings).</p> 362 </dd> 363 <dt><code>--nacl-debug-mask=<nmf_url_mask1,nmf_url_mask2,...></code></dt> 364 <dd><p class="first last">Specifies a set of debug mask patterns. This allows you to selectively 365 choose to debug certain applications and not debug others. For example, if 366 you only want to debug the NMF files for your applications at 367 <code>https://example.com/app</code>, and no other NaCl applications found on the 368 web, specify <code>--nacl-debug-mask=https://example.com/app/*.nmf</code>. This 369 helps prevent accidentally debugging other NaCl applications if you like 370 to leave the <code>--enable-nacl-debug</code> flag turned on. The pattern language 371 for the mask follows <a class="reference external" href="/extensions/match_patterns">chrome extension match patterns</a>. The pattern set can be inverted by 372 prefixing the pattern set with the <code>!</code> character.</p> 373 </dd> 374 <dt><code><URL></code></dt> 375 <dd><p class="first last">Specifies the URL Chrome should open when it launches. The local server 376 that comes with the SDK listens on port 5103 by default, so the URL when 377 you’re debugging is typically <code>localhost:5103</code> (assuming that your 378 application’s page is called index.html and that you run the local server 379 in the directory where that page is located).</p> 380 </dd> 381 </dl> 382 </li> 383 <li><p class="first">Navigate to your application’s page in Chrome. (You don’t need to do this if 384 you specified a URL when you launched Chrome in the previous step.) Chrome 385 will start loading the application, then pause and wait until you start 386 nacl-gdb and run the <code>continue</code> command.</p> 387 </li> 388 <li><p class="first">Go to the directory with your source code, and run nacl-gdb from there. For 389 example:</p> 390 <pre class="prettyprint"> 391 cd <NACL_SDK_ROOT>/examples/hello_world_gles 392 <NACL_SDK_ROOT>/toolchain/win_x86_newlib/bin/x86_64-nacl-gdb 393 </pre> 394 <p>The debugger will start and show you a gdb prompt:</p> 395 <pre class="prettyprint"> 396 (gdb) 397 </pre> 398 </li> 399 <li><p class="first">For debugging PNaCl pexes run the following gdb command lines 400 (skip to the next item if you are using NaCl instead of PNaCl):</p> 401 <pre class="prettyprint"> 402 (gdb) target remote localhost:4014 403 (gdb) remote get nexe <path-to-save-translated-nexe-with-debug-info> 404 (gdb) file <path-to-save-translated-nexe-with-debug-info> 405 (gdb) remote get irt <path-to-save-NaCl-integrated-runtime> 406 (gdb) nacl-irt <path-to-saved-NaCl-integrated-runtime> 407 </pre> 408 </li> 409 <li><p class="first">For NaCl nexes, run the following commands from the gdb command line:</p> 410 <pre class="prettyprint"> 411 (gdb) target remote localhost:4014 412 (gdb) nacl-manifest <path-to-your-.nmf-file> 413 (gdb) remote get irt <path-to-save-NaCl-integrated-runtime> 414 (gdb) nacl-irt <path-to-saved-NaCl-integrated-runtime> 415 </pre> 416 </li> 417 <li><p class="first">The command used for PNaCl and NaCl are described below:</p> 418 <dl class="docutils"> 419 <dt><code>target remote localhost:4014</code></dt> 420 <dd><p class="first last">Tells the debugger how to connect to the debug stub in the Native Client 421 application loader. This connection occurs through TCP port 4014 (note 422 that this port is distinct from the port which the local web server uses 423 to listen for incoming requests, typically port 5103). If you are 424 debugging multiple applications at the same time, the loader may choose 425 a port that is different from the default 4014 port. See the Chrome 426 task manager for the debug port.</p> 427 </dd> 428 <dt><code>remote get nexe <path></code></dt> 429 <dd><p class="first last">This saves the application’s main executable (nexe) to <code><path></code>. 430 For PNaCl, this provides a convenient way to access the nexe that is 431 a <strong>result</strong> of translating your pexe. This can then be loaded with 432 the <code>file <path></code> command.</p> 433 </dd> 434 <dt><code>nacl-manifest <path></code></dt> 435 <dd><p class="first last">For NaCl (not PNaCl), this tells the debugger where to find your 436 application’s executable (.nexe) files. The application’s manifest 437 (.nmf) file lists your application’s executable files, as well as any 438 libraries that are linked with the application dynamically.</p> 439 </dd> 440 <dt><code>remote get irt <path></code></dt> 441 <dd><p class="first last">This saves the Native Client Integrated Runtime (IRT). Normally, 442 the IRT is located in the same directory as the Chrome executable, 443 or in a subdirectory named after the Chrome version. For example, if 444 you’re running Chrome canary on Windows, the path to the IRT typically 445 looks something like <code>C:/Users/<username>/AppData/Local/Google/Chrome 446 SxS/Application/23.0.1247.1/nacl_irt_x86_64.nexe</code>. 447 The <code>remote get irt <path></code> saves that to the current working 448 directory so that you do not need to find where exactly the IRT 449 is stored alongside Chrome.</p> 450 </dd> 451 <dt><code>nacl-irt <path></code></dt> 452 <dd><p class="first last">Tells the debugger where to find the Native Client Integrated Runtime 453 (IRT). <code><path></code> can either be the location of the copy saved by 454 <code>remote get irt <path></code> or the copy that is installed alongside Chrome.</p> 455 </dd> 456 </dl> 457 <p>A couple of notes on how to specify path names in the nacl-gdb commands 458 above:</p> 459 <ul class="small-gap"> 460 <li><p class="first">You can use a forward slash to separate directories on Linux, Mac, and 461 Windows. If you use a backslash to separate directories on Windows, you 462 must escape the backslash by using a double backslash “\” between 463 directories.</p> 464 </li> 465 <li><p class="first">If any directories in the path have spaces in their name, you must put 466 quotation marks around the path.</p> 467 </li> 468 </ul> 469 <p>As an example, here is a what these nacl-gdb commands might look like on 470 Windows:</p> 471 <pre class="prettyprint"> 472 target remote localhost:4014 473 nacl-manifest "C:/<NACL_SDK_ROOT>/examples/hello_world_gles/newlib/Debug/hello_world_gles.nmf" 474 nacl-irt "C:/Users/<username>/AppData/Local/Google/Chrome SxS/Application/23.0.1247.1/nacl_irt_x86_64.nexe" 475 </pre> 476 <p>To save yourself some typing, you can put put these nacl-gdb commands in a 477 script file, and execute the file when you run nacl-gdb, like so:</p> 478 <pre class="prettyprint"> 479 <NACL_SDK_ROOT>/toolchain/win_x86_newlib/bin/x86_64-nacl-gdb -x <nacl-script-file> 480 </pre> 481 <p>If nacl-gdb connects successfully to Chrome, it displays a message such as 482 the one below, followed by a gdb prompt:</p> 483 <pre class="prettyprint"> 484 0x000000000fc00200 in _start () 485 (gdb) 486 </pre> 487 <p>If nacl-gdb can’t connect to Chrome, it displays a message such as 488 “<code>localhost:4014: A connection attempt failed</code>” or “<code>localhost:4014: 489 Connection timed out.</code>” If you see a message like that, make sure that you 490 have launched a web server, launched Chrome, and navigated to your 491 application’s page before starting nacl-gdb.</p> 492 </li> 493 </ol> 494 <p>Once nacl-gdb connects to Chrome, you can run standard gdb commands to execute 495 your module and inspect its state. Some commonly used commands are listed 496 below.</p> 497 <dl class="docutils"> 498 <dt><code>break <location></code></dt> 499 <dd><p class="first">set a breakpoint at <location>, e.g.:</p> 500 <pre class="last prettyprint"> 501 break hello_world.cc:79 502 break hello_world::HelloWorldInstance::HandleMessage 503 break Render 504 </pre> 505 </dd> 506 <dt><code>continue</code></dt> 507 <dd>resume normal execution of the program</dd> 508 <dt><code>next</code></dt> 509 <dd>execute the next source line, stepping over functions</dd> 510 <dt><code>step</code></dt> 511 <dd>execute the next source line, stepping into functions</dd> 512 <dt><code>print <expression></code></dt> 513 <dd>print the value of <expression> (e.g., variables)</dd> 514 <dt><code>backtrace</code></dt> 515 <dd>print a stack backtrace</dd> 516 <dt><code>info breakpoints</code></dt> 517 <dd>print a table of all breakpoints</dd> 518 <dt><code>delete <breakpoint></code></dt> 519 <dd>delete the specified breakpoint (you can use the breakpoint number displayed 520 by the info command)</dd> 521 <dt><code>help <command></code></dt> 522 <dd>print documentation for the specified gdb <command></dd> 523 <dt><code>quit</code></dt> 524 <dd>quit gdb</dd> 525 </dl> 526 <p>See the <a class="reference external" href="http://sourceware.org/gdb/current/onlinedocs/gdb/#toc_Top">gdb documentation</a> for a 527 comprehensive list of gdb commands. Note that you can abbreviate most commands 528 to just their first letter (<code>b</code> for break, <code>c</code> for continue, and so on).</p> 529 <p>To interrupt execution of your module, press <Ctrl-c>. When you’re done 530 debugging, close the Chrome window and type <code>q</code> to quit gdb.</p> 531 </section></section></section><section id="debugging-with-other-tools"> 532 <h2 id="debugging-with-other-tools">Debugging with other tools</h2> 533 <p>If you cannot use the <a class="reference internal" href="#visual-studio"><em>Visual Studio add-in</em></a>, or you want 534 to use a debugger other than nacl-gdb, you must manually build your module as a 535 Pepper plugin (sometimes referred to as a “<a class="reference external" href="http://www.chromium.org/nativeclient/getting-started/getting-started-background-and-basics#TOC-Trusted-vs-Untrusted">trusted</a>” 536 or “in-process” plugin). Pepper plugins (.DLL files on Windows; .so files on 537 Linux; .bundle files on Mac) are loaded directly in either the Chrome renderer 538 process or a separate plugin process, rather than in Native Client. Building a 539 module as a trusted Pepper plugin allows you to use standard debuggers and 540 development tools on your system, but when you’re finished developing the 541 plugin, you need to port it to Native Client (i.e., build the module with one 542 of the toolchains in the NaCl SDK so that the module runs in Native Client). 543 For details on this advanced development technique, see <a class="reference external" href="http://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin">Debugging a Trusted 544 Plugin</a>. 545 Note that starting with the <code>pepper_22</code> bundle, the NaCl SDK for Windows 546 includes pre-built libraries and library source code, making it much easier to 547 build a module into a .DLL.</p> 548 <section id="open-source-profiling-tools"> 549 <h3 id="open-source-profiling-tools">Open source profiling tools</h3> 550 <p>For the brave-hearted there are open source tools at <a class="reference external" href="http://www.chromium.org/nativeclient">Chromium.org</a> that describe how to do profiling on 551 <a class="reference external" href="https://sites.google.com/a/chromium.org/dev/nativeclient/how-tos/profiling-nacl-apps-on-64-bit-windows">64-bit Windows</a> 552 and <a class="reference external" href="http://www.chromium.org/nativeclient/how-tos/limited-profiling-with-oprofile-on-x86-64">Linux</a> 553 machines.</p> 554 </section></section></section> 555 556 {{/partials.standard_nacl_article}} 557
