| OLD | NEW |
|---|
| (Empty) | |
| 1 {{+bindTo:partials.standard_nacl_article}} |
| 2 |
| 3 <section id="debugging"> |
| 4 <span id="devcycle-debugging"></span><h1 id="debugging"><span id="devcycle-debug
ging"></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 topic" id="table-of-contents"> |
| 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="id1">Diagnostic information</a></p> |
| 11 <ul class="small-gap"> |
| 12 <li><a class="reference internal" href="#viewing-process-statistics-with-the-tas
k-manager" id="id2">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="id3">Controlling the level of Native Client erro
r and warning messages</a></li> |
| 14 </ul> |
| 15 </li> |
| 16 <li><p class="first"><a class="reference internal" href="#basic-debugging" id="i
d4">Basic debugging</a></p> |
| 17 <ul class="small-gap"> |
| 18 <li><a class="reference internal" href="#writing-messages-to-the-javascript-cons
ole" id="id5">Writing messages to the JavaScript console</a></li> |
| 19 <li><p class="first"><a class="reference internal" href="#debugging-with-printf"
id="id6">Debugging with printf</a></p> |
| 20 <ul class="small-gap"> |
| 21 <li><a class="reference internal" href="#redirecting-output-to-log-files" id="id
7">Redirecting output to log files</a></li> |
| 22 <li><a class="reference internal" href="#redirecting-output-to-the-javascript-co
nsole" id="id8">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=
"id9">Logging calls to Pepper interfaces</a></li> |
| 26 <li><a class="reference internal" href="#debugging-with-visual-studio" id="id10"
>Debugging with Visual Studio</a></li> |
| 27 <li><p class="first"><a class="reference internal" href="#debugging-with-nacl-gd
b" id="id11">Debugging with nacl-gdb</a></p> |
| 28 <ul class="small-gap"> |
| 29 <li><a class="reference internal" href="#debugging-pnacl-pexes" id="id12">Debugg
ing PNaCl pexes</a></li> |
| 30 <li><a class="reference internal" href="#running-nacl-gdb" id="id13">Running nac
l-gdb</a></li> |
| 31 </ul> |
| 32 </li> |
| 33 </ul> |
| 34 </li> |
| 35 <li><p class="first"><a class="reference internal" href="#debugging-with-other-t
ools" id="id14">Debugging with other tools</a></p> |
| 36 <ul class="small-gap"> |
| 37 <li><a class="reference internal" href="#open-source-profiling-tools" id="id15">
Open source profiling tools</a></li> |
| 38 </ul> |
| 39 </li> |
| 40 </ul> |
| 41 </div> |
| 42 <section id="diagnostic-information"> |
| 43 <h2 id="diagnostic-information">Diagnostic information</h2> |
| 44 <section id="viewing-process-statistics-with-the-task-manager"> |
| 45 <h3 id="viewing-process-statistics-with-the-task-manager">Viewing process statis
tics with the task manager</h3> |
| 46 <p>You can use Chrome’s Task Manager to display information about a Native
Client |
| 47 application:</p> |
| 48 <ol class="arabic simple"> |
| 49 <li>Open the Task Manager by clicking the menu icon <img alt="menu-icon" src="/n
ative-client/images/menu-icon.png" /> and choosing |
| 50 <strong>Tools > Task manager</strong>.</li> |
| 51 <li>When the Task Manager window appears, verify that the columns displaying |
| 52 memory information are visible. If they are not, right click in the header |
| 53 row and select the memory items from the popup menu that appears.</li> |
| 54 </ol> |
| 55 <p>A browser window running a Native Client application will have at least two |
| 56 processes associated with it: a process for the app’s top level (the rende
r |
| 57 process managing the page including its HTML and any JavaScript) and one or |
| 58 more processes for each instance of a Native Client module embedded in the page |
| 59 (each process running native code from one nexe file). The top-level process |
| 60 appears with the application’s icon and begins with the text “App:&#
8221;. A Native |
| 61 Client process appears with a Chrome extension icon (a jigsaw puzzle piece |
| 62 <img alt="puzzle" src="/native-client/images/puzzle.png" />) and begins with the
text “Native Client module” followed by the URL |
| 63 of its manifest file.</p> |
| 64 <p>From the Task Manager you can view the changing memory allocations of all the |
| 65 processes associated with a Native Client application. Each process has its own |
| 66 memory footprint. You can also see the rendering rate displayed as frames per |
| 67 second (FPS). Note that the computation of render frames can be performed in |
| 68 any process, but the rendering itself is always done in the top level |
| 69 application process, so look for the rendering rate there.</p> |
| 70 </section><section id="controlling-the-level-of-native-client-error-and-warning-
messages"> |
| 71 <h3 id="controlling-the-level-of-native-client-error-and-warning-messages">Contr
olling the level of Native Client error and warning messages</h3> |
| 72 <p>Native Client prints warning and error messages to stdout and stderr. You can |
| 73 increase the amount of Native Client’s diagnostic output by setting the |
| 74 following <a class="reference external" href="http://en.wikipedia.org/wiki/Envir
onment_variable">environment variables</a>:</p> |
| 75 <ul class="small-gap"> |
| 76 <li>NACL_DEBUG_ENABLE=1</li> |
| 77 <li>PPAPI_BROWSER_DEBUG=1</li> |
| 78 <li>NACL_PLUGIN_DEBUG=1</li> |
| 79 <li>NACL_PPAPI_PROXY_DEBUG=1</li> |
| 80 <li>NACL_SRPC_DEBUG=[1-255] (use a higher number for more verbose debug output)<
/li> |
| 81 <li>NACLVERBOSITY=[1-255]</li> |
| 82 </ul> |
| 83 </section></section><section id="basic-debugging"> |
| 84 <h2 id="basic-debugging">Basic debugging</h2> |
| 85 <section id="writing-messages-to-the-javascript-console"> |
| 86 <h3 id="writing-messages-to-the-javascript-console">Writing messages to the Java
Script console</h3> |
| 87 <p>You can send messages from your C/C++ code to JavaScript using the PostMessag
e |
| 88 call in the <a class="reference internal" href="/native-client/devguide/coding/m
essage-system.html"><em>Pepper messaging system</em></a>. When the |
| 89 JavaScript code receives a message, its message event handler can call |
| 90 <a class="reference external" href="https://developer.mozilla.org/en/DOM/console
.log">console.log()</a> to write |
| 91 the message to the JavaScript <a class="reference external" href="https://develo
pers.google.com/chrome-developer-tools/docs/console">console</a> in |
| 92 Chrome’s Developer Tools.</p> |
| 93 </section><section id="debugging-with-printf"> |
| 94 <h3 id="debugging-with-printf">Debugging with printf</h3> |
| 95 <p>Your C/C++ code can perform inline printf debugging to stdout and stderr by |
| 96 calling fprintf() directly, or by using cover functions like these:</p> |
| 97 <pre class="prettyprint"> |
| 98 #include <stdio.h> |
| 99 void logmsg(const char* pMsg){ |
| 100 fprintf(stdout,"logmsg: %s\n",pMsg); |
| 101 } |
| 102 void errormsg(const char* pMsg){ |
| 103 fprintf(stderr,"logerr: %s\n",pMsg); |
| 104 } |
| 105 </pre> |
| 106 <p>By default stdout and stderr will appear in Chrome’s stdout and stderr
stream |
| 107 but they can also be redirected as described below.</p> |
| 108 <section id="redirecting-output-to-log-files"> |
| 109 <h4 id="redirecting-output-to-log-files">Redirecting output to log files</h4> |
| 110 <p>You can redirect stdout and stderr to output files by setting these environme
nt variables:</p> |
| 111 <ul class="small-gap"> |
| 112 <li><code>NACL_EXE_STDOUT=c:\nacl_stdout.log</code></li> |
| 113 <li><code>NACL_EXE_STDERR=c:\nacl_stderr.log</code></li> |
| 114 </ul> |
| 115 <p>There is another variable, <code>NACLLOG</code>, that you can use to redirect
Native |
| 116 Client’s internally-generated messages. This variable is set to stderr by |
| 117 default; you can redirect these messages to an output file by setting the |
| 118 variable as follows:</p> |
| 119 <ul class="small-gap"> |
| 120 <li><code>NACLLOG=c:\nacl.log</code></li> |
| 121 </ul> |
| 122 <aside class="note"> |
| 123 <strong>Note:</strong> If you set the NACL_EXE_STDOUT, NACL_EXE_STDERR, or NACLL
OG |
| 124 variables to redirect output to a file, you must run Chrome with the |
| 125 <code>--no-sandbox</code> flag. You must also be careful that each variable poi
nts to |
| 126 a different file. |
| 127 </aside> |
| 128 </section><section id="redirecting-output-to-the-javascript-console"> |
| 129 <h4 id="redirecting-output-to-the-javascript-console">Redirecting output to the
JavaScript console</h4> |
| 130 <p>You can also cause output from printf statements in your C/C++ code to be |
| 131 relayed to the JavaScript side of your application through the Pepper messaging |
| 132 system, where you can then write the output to the JavaScript console. Follow |
| 133 these steps:</p> |
| 134 <ol class="arabic"> |
| 135 <li><p class="first">Set the NACL_EXE_STDOUT and NACL_EXE_STDERR environment var
iables as |
| 136 follows:</p> |
| 137 <ul class="small-gap"> |
| 138 <li><p class="first">NACL_EXE_STDOUT=DEBUG_ONLY:dev://postmessage</p> |
| 139 </li> |
| 140 <li><p class="first">NACL_EXE_STDERR=DEBUG_ONLY:dev://postmessage</p> |
| 141 </li> |
| 142 </ul> |
| 143 <p>These settings tell Native Client to use PostMessage() to send output that |
| 144 your Native Client module writes to stdout and stderr to the JavaScript side |
| 145 of your application.</p> |
| 146 </li> |
| 147 <li><p class="first">Register a JavaScript handler to receive messages from your
Native Client |
| 148 module:</p> |
| 149 <pre class="prettyprint"> |
| 150 <div id="nacl_container"> |
| 151 <script type="text/javascript"> |
| 152 var container = document.getElementById('nacl_container'); |
| 153 container.addEventListener('message', handleMessage, true); |
| 154 </script> |
| 155 <embed id="nacl_module" |
| 156 src="my_application.nmf" |
| 157 type="application/x-nacl" /> |
| 158 </div> |
| 159 </pre> |
| 160 </li> |
| 161 <li><p class="first">Implement a simple JavaScript handler that logs the message
s it receives to |
| 162 the JavaScript console:</p> |
| 163 <pre class="prettyprint"> |
| 164 function handleMessage(message_event) { |
| 165 console.log(message_event.data); |
| 166 } |
| 167 </pre> |
| 168 <p>This handler works in the simple case where the only messages your Native |
| 169 Client module sends to JavaScript are messages with the output from stdout |
| 170 and stderr. If your Native Client module also sends other messages to |
| 171 JavaScript, your handler will need to be more complex.</p> |
| 172 <p>Once you’ve implemented a message handler and set up the environment |
| 173 variables as described above, you can check the JavaScript console to see |
| 174 output that your Native Client module prints to stdout and stderr. Keep in |
| 175 mind that your module makes a call to PostMessage() every time it flushes |
| 176 stdout or stderr. Your application’s performance will degrade considerabl
y |
| 177 if your module prints and flushes frequently, or if it makes frequent Pepper |
| 178 calls to begin with (e.g., to render).</p> |
| 179 </li> |
| 180 </ol> |
| 181 </section></section><section id="logging-calls-to-pepper-interfaces"> |
| 182 <h3 id="logging-calls-to-pepper-interfaces">Logging calls to Pepper interfaces</
h3> |
| 183 <p>You can log all Pepper calls your module makes by passing the following flags |
| 184 to Chrome on startup:</p> |
| 185 <pre class="prettyprint"> |
| 186 --vmodule=ppb*=4 --enable-logging=stderr |
| 187 </pre> |
| 188 <p>The <code>vmodule</code> flag tells Chrome to log all calls to C Pepper inter
faces that |
| 189 begin with “ppb” (that is, the interfaces that are implemented by th
e browser |
| 190 and that your module calls). The <code>enable-logging</code> flag tells Chrome t
o log |
| 191 the calls to stderr.</p> |
| 192 </section><section id="debugging-with-visual-studio"> |
| 193 <span id="visual-studio"></span><h3 id="debugging-with-visual-studio"><span id="
visual-studio"></span>Debugging with Visual Studio</h3> |
| 194 <p>If you develop on a Windows platform you can use the <a class="reference inte
rnal" href="/native-client/devguide/devcycle/vs-addin.html"><em>Native Client Vi
sual |
| 195 Studio add-in</em></a> to write and debug your code. The add-in defines new |
| 196 project platforms that let you run your module in two different modes: As a |
| 197 Pepper plugin and as a Native Client module. When running as a Pepper plugin |
| 198 you can use the built-in Visual Studio debugger. When running as a Native |
| 199 Client module Visual Studio will launch an instance of nacl-gdb for you and |
| 200 link it to the running code.</p> |
| 201 </section><section id="debugging-with-nacl-gdb"> |
| 202 <span id="using-gdb"></span><h3 id="debugging-with-nacl-gdb"><span id="using-gdb
"></span>Debugging with nacl-gdb</h3> |
| 203 <p>The Native Client SDK includes a command-line debugger that you can use to |
| 204 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 loc
ated at |
| 205 <code>toolchain/<platform>_x86_newlib/bin/x86_64-nacl-gdb</code> (where <e
m><platform></em> |
| 206 is the platform of your development machine: <code>win</code>, <code>mac</code>,
or |
| 207 <code>linux</code>).</p> |
| 208 <p>Note that this same copy of GDB can be used to debug any NaCl program, |
| 209 whether built using newlib or glibc for x86-32, x86-64 or ARM. In the SDK, |
| 210 <code>i686-nacl-gdb</code> is an alias for <code>x86_64-nacl-gdb</code>, and the
<code>newlib</code> |
| 211 and <code>glibc</code> toolchains both contain the same version of GDB.</p> |
| 212 <section id="debugging-pnacl-pexes"> |
| 213 <h4 id="debugging-pnacl-pexes">Debugging PNaCl pexes</h4> |
| 214 <p>If you want to use GDB to debug a program that is compiled with the PNaCl |
| 215 toolchain, you must convert the <code>pexe</code> file to a <code>nexe</code>.
(You can skip |
| 216 this step if you are using the GCC toolchain.)</p> |
| 217 <ul class="small-gap"> |
| 218 <li>Firstly, make sure you are passing the <code>-g</code> <a class="reference i
nternal" href="/native-client/devguide/devcycle/building.html#compile-flags"><em
>compile option</em></a> to <code>pnacl-clang</code> to enable generating debugg
ing info. |
| 219 You might also want to omit <code>-O2</code> from the compile-time and link-time |
| 220 options, otherwise GDB not might be able to print variables’ values when |
| 221 debugging (this is more of a problem with the PNaCl/LLVM toolchain than |
| 222 with GCC).</li> |
| 223 <li><p class="first">Secondly, use <code>pnacl-translate</code> to convert your
<code>pexe</code> to one or more |
| 224 <code>nexe</code> files. For example:</p> |
| 225 <pre> |
| 226 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-translate ^ |
| 227 --allow-llvm-bitcode-input hello_world.pexe -arch x86-32 -o hello_world_x86_32
.nexe |
| 228 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-translate ^ |
| 229 --allow-llvm-bitcode-input hello_world.pexe -arch x86-64 -o hello_world_x86_64
.nexe |
| 230 </pre> |
| 231 <p>For this, use the non-finalized <code>pexe</code> file produced by |
| 232 <code>pnacl-clang</code>, not the <code>pexe</code> file produced by <code>pnacl
-finalize</code>. |
| 233 The latter <code>pexe</code> has debugging info stripped out. The option |
| 234 <code>--allow-llvm-bitcode-input</code> tells <code>pnacl-translate</code> to ac
cept a |
| 235 non-finalized <code>pexe</code>.</p> |
| 236 </li> |
| 237 <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 |
| 238 your <code>pexe</code> file with one that points to the <code>nexe</code> files.
For the |
| 239 example <code>nexe</code> filenames above, the new <code>nmf</code> file would c
ontain:</p> |
| 240 <pre> |
| 241 { |
| 242 "program": { |
| 243 "x86-32": {"url": "hello_world_x86_32.nexe"}, |
| 244 "x86-64": {"url": "hello_world_x86_64.nexe"}, |
| 245 } |
| 246 } |
| 247 </pre> |
| 248 </li> |
| 249 <li>Change the <code><embed></code> HTML element to use |
| 250 <code>type="application/x-nacl"</code> rather than |
| 251 <code>type="application/x-pnacl"</code>.</li> |
| 252 <li>Copy the <code>nexe</code> and <code>nmf</code> files to the location that y
our local web |
| 253 server serves files from.</li> |
| 254 </ul> |
| 255 <aside class="note"> |
| 256 <strong>Note:</strong> If you know whether Chrome is using the x86-32 or x86-64 |
| 257 version of the NaCl sandbox on your system, you can translate the |
| 258 <code>pexe</code> once to a single x86-32 or x86-64 <code>nexe</code>. Otherwis
e, you |
| 259 might find it easier to translate the <code>pexe</code> to both <code>nexe</code
> |
| 260 formats as described above. |
| 261 </aside> |
| 262 </section><section id="running-nacl-gdb"> |
| 263 <h4 id="running-nacl-gdb">Running nacl-gdb</h4> |
| 264 <p>Before you start using nacl-gdb, make sure you can <a class="reference intern
al" href="/native-client/devguide/devcycle/building.html"><em>build</em></a> you
r |
| 265 module and <a class="reference internal" href="/native-client/devguide/devcycle/
running.html"><em>run</em></a> your application normally. This will verify |
| 266 that you have created all the required <a class="reference internal" href="/nati
ve-client/devguide/coding/application-structure.html"><em>application parts</em>
</a> (.html, .nmf, and .nexe files, shared |
| 267 libraries, etc.), that your server can access those resources, and that you̵
7;ve |
| 268 configured Chrome correctly to run your application. The instructions below |
| 269 assume that you are using a <a class="reference internal" href="/native-client/d
evguide/devcycle/running.html#web-server"><em>local server</em></a> to run your |
| 270 application; one benefit of doing it this way is that you can check the web |
| 271 server output to confirm that your application is loading the correct |
| 272 resources. However, some people prefer to run their application as an unpacked |
| 273 extension, as described in <a class="reference internal" href="/native-client/de
vguide/devcycle/running.html"><em>Running Native Client Applications</em></a>.</
p> |
| 274 <p>Follow the instructions below to debug your module with nacl-gdb:</p> |
| 275 <ol class="arabic"> |
| 276 <li><p class="first">Compile your module with the <code>-g</code> flag so that y
our .nexe retains symbols |
| 277 and other debugging information (see the <a class="reference internal" href="/na
tive-client/devguide/devcycle/building.html#compile-flags"><em>recommended compi
le flags</em></a>).</p> |
| 278 </li> |
| 279 <li><p class="first">Launch a local web server (e.g., the <a class="reference in
ternal" href="/native-client/devguide/devcycle/running.html#web-server"><em>web
server</em></a> included |
| 280 in the SDK).</p> |
| 281 </li> |
| 282 <li><p class="first">Launch Chrome with these three required flags: <code>--enab
le-nacl --enable-nacl-debug --no-sandbox</code>.</p> |
| 283 <p>You may also want to use some of the optional flags listed below. A typical |
| 284 command looks like this:</p> |
| 285 <pre class="prettyprint"> |
| 286 chrome --enable-nacl --enable-nacl-debug --no-sandbox --disable-hang-monitor loc
alhost:5103 |
| 287 </pre> |
| 288 <p><strong>Required flags:</strong></p> |
| 289 <dl class="docutils"> |
| 290 <dt><code>--enable-nacl</code></dt> |
| 291 <dd><p class="first last">Enables Native Client for all applications, including
those that are |
| 292 launched outside the Chrome Web Store.</p> |
| 293 </dd> |
| 294 <dt><code>--enable-nacl-debug</code></dt> |
| 295 <dd><p class="first last">Turns on the Native Client debug stub, opens TCP port
4014, and pauses |
| 296 Chrome to let the debugger connect.</p> |
| 297 </dd> |
| 298 <dt><code>--no-sandbox</code></dt> |
| 299 <dd><p class="first last">Turns off the Chrome sandbox (not the Native Client sa
ndbox). This enables |
| 300 the stdout and stderr streams, and lets the debugger connect.</p> |
| 301 </dd> |
| 302 </dl> |
| 303 <p><strong>Optional flags:</strong></p> |
| 304 <dl class="docutils"> |
| 305 <dt><code>--disable-hang-monitor</code></dt> |
| 306 <dd><p class="first last">Prevents Chrome from displaying a warning when a tab i
s unresponsive.</p> |
| 307 </dd> |
| 308 <dt><code>--user-data-dir=<directory></code></dt> |
| 309 <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 |
| 310 Chrome should load its state. You can specify a different user data |
| 311 directory so that changes you make to Chrome in your debugging session do |
| 312 not affect your personal Chrome data (history, cookies, bookmarks, themes, |
| 313 and settings).</p> |
| 314 </dd> |
| 315 <dt><code><URL></code></dt> |
| 316 <dd><p class="first last">Specifies the URL Chrome should open when it launches.
The local server |
| 317 that comes with the SDK listens on port 5103 by default, so the URL when |
| 318 you’re debugging is typically <code>localhost:5103</code> (assuming that y
our |
| 319 application’s page is called index.html and that you run the local server |
| 320 in the directory where that page is located).</p> |
| 321 </dd> |
| 322 </dl> |
| 323 </li> |
| 324 <li><p class="first">Navigate to your application’s page in Chrome. (You d
on’t need to do this if |
| 325 you specified a URL when you launched Chrome in the previous step.) Chrome |
| 326 will start loading the application, then pause and wait until you start |
| 327 nacl-gdb and run the <code>continue</code> command.</p> |
| 328 </li> |
| 329 <li><p class="first">Go to the directory with your source code, and run nacl-gdb
from there. For |
| 330 example:</p> |
| 331 <pre class="prettyprint"> |
| 332 cd <NACL_SDK_ROOT>/examples/hello_world_gles |
| 333 <NACL_SDK_ROOT>/toolchain/win_x86_newlib/bin/x86_64-nacl-gdb |
| 334 </pre> |
| 335 <p>The debugger will start and show you a gdb prompt:</p> |
| 336 <pre class="prettyprint"> |
| 337 (gdb) |
| 338 </pre> |
| 339 </li> |
| 340 <li><p class="first">Run the following three commands from the gdb command line:
</p> |
| 341 <pre class="prettyprint"> |
| 342 (gdb) nacl-manifest <path-to-your-.nmf-file> |
| 343 (gdb) nacl-irt <path-to-Chrome-NaCl-integrated-runtime> |
| 344 (gdb) target remote localhost:4014 |
| 345 </pre> |
| 346 <p>These commands are described below:</p> |
| 347 <dl class="docutils"> |
| 348 <dt><code>nacl-manifest <path></code></dt> |
| 349 <dd><p class="first last">Tells the debugger about your Native Client applicatio
n by pointing it to |
| 350 the application’s manifest (.nmf) file. The manifest file lists your |
| 351 application’s executable (.nexe) files, as well as any libraries that are |
| 352 linked with the application dynamically.</p> |
| 353 </dd> |
| 354 <dt><code>nacl-irt <path></code></dt> |
| 355 <dd><p class="first last">Tells the debugger where to find the Native Client Int
egrated Runtime |
| 356 (IRT). The IRT is located in the same directory as the Chrome executable, |
| 357 or in a subdirectory named after the Chrome version. For example, if |
| 358 you’re running Chrome canary on Windows, the path to the IRT typically |
| 359 looks something like <code>C:/Users/<username>/AppData/Local/Google/Chrome |
| 360 SxS/Application/23.0.1247.1/nacl_irt_x86_64.nexe</code>.</p> |
| 361 </dd> |
| 362 <dt><code>target remote localhost:4014</code></dt> |
| 363 <dd><p class="first last">Tells the debugger how to connect to the debug stub in
the Native Client |
| 364 application loader. This connection occurs through TCP port 4014 (note |
| 365 that this port is distinct from the port which the local web server uses |
| 366 to listen for incoming requests, typically port 5103).</p> |
| 367 </dd> |
| 368 </dl> |
| 369 <p>A couple of notes on how to specify path names in the nacl-gdb commands |
| 370 above:</p> |
| 371 <ul class="small-gap"> |
| 372 <li><p class="first">You can use a forward slash to separate directories on Linu
x, Mac, and |
| 373 Windows. If you use a backslash to separate directories on Windows, you |
| 374 must escape the backslash by using a double backslash “\” between |
| 375 directories.</p> |
| 376 </li> |
| 377 <li><p class="first">If any directories in the path have spaces in their name, y
ou must put |
| 378 quotation marks around the path.</p> |
| 379 </li> |
| 380 </ul> |
| 381 <p>As an example, here is a what these nacl-gdb commands might look like on |
| 382 Windows:</p> |
| 383 <pre class="prettyprint"> |
| 384 nacl-manifest "C:/<NACL_SDK_ROOT>/examples/hello_world_gles/newlib/De
bug/hello_world_gles.nmf" |
| 385 nacl-irt "C:/Users/<username>/AppData/Local/Google/Chrome SxS/Applica
tion/23.0.1247.1/nacl_irt_x86_64.nexe" |
| 386 target remote localhost:4014 |
| 387 </pre> |
| 388 <p>To save yourself some typing, you can put put these nacl-gdb commands in a |
| 389 script file, and execute the file when you run nacl-gdb, like so:</p> |
| 390 <pre class="prettyprint"> |
| 391 <NACL_SDK_ROOT>/toolchain/win_x86_newlib/bin/x86_64-nacl-gdb -x <nacl-s
cript-file> |
| 392 </pre> |
| 393 <p>If nacl-gdb connects successfully to Chrome, it displays a message such as |
| 394 the one below, followed by a gdb prompt:</p> |
| 395 <pre class="prettyprint"> |
| 396 0x000000000fc00200 in _start () |
| 397 (gdb) |
| 398 </pre> |
| 399 <p>If nacl-gdb can’t connect to Chrome, it displays a message such as |
| 400 “<code>localhost:4014: A connection attempt failed</code>” or “
;<code>localhost:4014: |
| 401 Connection timed out.</code>” If you see a message like that, make sure th
at you |
| 402 have launched a web server, launched Chrome, and navigated to your |
| 403 application’s page before starting nacl-gdb.</p> |
| 404 </li> |
| 405 </ol> |
| 406 <p>Once nacl-gdb connects to Chrome, you can run standard gdb commands to execut
e |
| 407 your module and inspect its state. Some commonly used commands are listed |
| 408 below.</p> |
| 409 <dl class="docutils"> |
| 410 <dt><code>break <location></code></dt> |
| 411 <dd><p class="first">set a breakpoint at <location>, e.g.:</p> |
| 412 <pre class="last prettyprint"> |
| 413 break hello_world.cc:79 |
| 414 break hello_world::HelloWorldInstance::HandleMessage |
| 415 break Render |
| 416 </pre> |
| 417 </dd> |
| 418 <dt><code>continue</code></dt> |
| 419 <dd>resume normal execution of the program</dd> |
| 420 <dt><code>next</code></dt> |
| 421 <dd>execute the next source line, stepping over functions</dd> |
| 422 <dt><code>step</code></dt> |
| 423 <dd>execute the next source line, stepping into functions</dd> |
| 424 <dt><code>print <expression></code></dt> |
| 425 <dd>print the value of <expression> (e.g., variables)</dd> |
| 426 <dt><code>backtrace</code></dt> |
| 427 <dd>print a stack backtrace</dd> |
| 428 <dt><code>info breakpoints</code></dt> |
| 429 <dd>print a table of all breakpoints</dd> |
| 430 <dt><code>delete <breakpoint></code></dt> |
| 431 <dd>delete the specified breakpoint (you can use the breakpoint number displayed |
| 432 by the info command)</dd> |
| 433 <dt><code>help <command></code></dt> |
| 434 <dd>print documentation for the specified gdb <command></dd> |
| 435 <dt><code>quit</code></dt> |
| 436 <dd>quit gdb</dd> |
| 437 </dl> |
| 438 <p>See the <a class="reference external" href="http://sourceware.org/gdb/current
/onlinedocs/gdb/#toc_Top">gdb documentation</a> for a |
| 439 comprehensive list of gdb commands. Note that you can abbreviate most commands |
| 440 to just their first letter (<code>b</code> for break, <code>c</code> for continu
e, and so on).</p> |
| 441 <p>To interrupt execution of your module, press <Ctrl-c>. When you’r
e done |
| 442 debugging, close the Chrome window and type <code>q</code> to quit gdb.</p> |
| 443 </section></section></section><section id="debugging-with-other-tools"> |
| 444 <h2 id="debugging-with-other-tools">Debugging with other tools</h2> |
| 445 <p>If you cannot use the <a class="reference internal" href="#visual-studio"><em
>Visual Studio add-in</em></a>, or you want |
| 446 to use a debugger other than nacl-gdb, you must manually build your module as a |
| 447 Pepper plugin (sometimes referred to as a “<a class="reference external" h
ref="http://www.chromium.org/nativeclient/getting-started/getting-started-backgr
ound-and-basics#TOC-Trusted-vs-Untrusted">trusted</a>” |
| 448 or “in-process” plugin). Pepper plugins (.DLL files on Windows; .so
files on |
| 449 Linux; .bundle files on Mac) are loaded directly in either the Chrome renderer |
| 450 process or a separate plugin process, rather than in Native Client. Building a |
| 451 module as a trusted Pepper plugin allows you to use standard debuggers and |
| 452 development tools on your system, but when you’re finished developing the |
| 453 plugin, you need to port it to Native Client (i.e., build the module with one |
| 454 of the toolchains in the NaCl SDK so that the module runs in Native Client). |
| 455 For details on this advanced development technique, see <a class="reference exte
rnal" href="http://www.chromium.org/nativeclient/how-tos/debugging-documentation
/debugging-a-trusted-plugin">Debugging a Trusted |
| 456 Plugin</a>. |
| 457 Note that starting with the <code>pepper_22</code> bundle, the NaCl SDK for Wind
ows |
| 458 includes pre-built libraries and library source code, making it much easier to |
| 459 build a module into a .DLL.</p> |
| 460 <section id="open-source-profiling-tools"> |
| 461 <h3 id="open-source-profiling-tools">Open source profiling tools</h3> |
| 462 <p>For the brave-hearted there are open source tools at <a class="reference exte
rnal" href="http://www.chromium.org/nativeclient">Chromium.org</a> that describe
how to do profiling on |
| 463 <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> |
| 464 and <a class="reference external" href="http://www.chromium.org/nativeclient/how
-tos/limited-profiling-with-oprofile-on-x86-64">Linux</a> |
| 465 machines.</p> |
| 466 </section></section></section> |
| 467 |
| 468 {{/partials.standard_nacl_article}} |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 140993006:
[NaCl SDK Docs] Check in the generated NaCl SDK Documentation. (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src