1 .. _devcycle-debugging:
7 This document describes tools and techniques you can use to debug, monitor,
8 and measure your application's performance.
10 .. contents:: Table Of Contents
15 Diagnostic information
16 ======================
18 Viewing process statistics with the task manager
19 ------------------------------------------------
21 You can use Chrome's Task Manager to display information about a Native Client
24 #. Open the Task Manager by clicking the menu icon |menu-icon| and choosing
25 **Tools > Task manager**.
26 #. When the Task Manager window appears, verify that the columns displaying
27 memory information are visible. If they are not, right click in the header
28 row and select the memory items from the popup menu that appears.
30 A browser window running a Native Client application has at least two processes
31 associated with it: a process for the app's top level (the render process
32 managing the page including its HTML and JavaScript) and one or more
33 processes for each instance of a Native Client module embedded in the page
34 (each process running native code from one nexe or pexe file). The top-level
35 process appears with the application's icon and begins with the text "Tab:".
36 A Native Client process appears with a Chrome extension icon (a jigsaw puzzle
37 piece |puzzle|) and begins with the text "Native Client module:" followed by the
38 URL of its manifest file.
40 From the Task Manager you can view the changing memory allocations of all the
41 processes associated with a Native Client application. Each process has its own
42 memory footprint. You can also see the rendering rate displayed as frames per
43 second (FPS). Note that the computation of render frames can be performed in
44 any process, but the rendering itself is always done in the top level
45 application process, so look for the rendering rate there.
47 Controlling the level of Native Client error and warning messages
48 -----------------------------------------------------------------
50 Native Client prints warning and error messages to stdout and stderr. You can
51 increase the amount of Native Client's diagnostic output by setting the
52 following `environment variables
53 <http://en.wikipedia.org/wiki/Environment_variable>`_:
55 * ``NACL_PLUGIN_DEBUG=1``
56 * ``NACL_SRPC_DEBUG=[1-255]`` (use a higher number for more verbose debug
58 * ``NACLVERBOSITY=[1-255]``
63 Writing messages to the JavaScript console
64 ------------------------------------------
66 You can send messages from your C/C++ code to JavaScript using the
67 ``PostMessage()`` call in the :doc:`Pepper messaging system
68 <../coding/message-system>`. When the JavaScript code receives a message, its
69 message event handler can call `console.log()
70 <https://developer.mozilla.org/en/DOM/console.log>`_ to write the message to the
71 JavaScript `console </devtools/docs/console-api>`_ in Chrome's Developer Tools.
76 Your C/C++ code can perform inline printf debugging to stdout and stderr by
77 calling fprintf() directly, or by using cover functions like these:
82 void logmsg(const char* pMsg){
83 fprintf(stdout,"logmsg: %s\n",pMsg);
85 void errormsg(const char* pMsg){
86 fprintf(stderr,"logerr: %s\n",pMsg);
89 By default stdout and stderr will appear in Chrome's stdout and stderr stream
90 but they can also be redirected as described below.
93 Redirecting output to log files
94 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
96 You can redirect stdout and stderr to output files by setting these environment
99 * ``NACL_EXE_STDOUT=c:\nacl_stdout.log``
100 * ``NACL_EXE_STDERR=c:\nacl_stderr.log``
102 There is another variable, ``NACLLOG``, that you can use to redirect Native
103 Client's internally-generated messages. This variable is set to stderr by
104 default; you can redirect these messages to an output file by setting the
107 * ``NACLLOG=c:\nacl.log``
112 **Note:** If you set the ``NACL_EXE_STDOUT``, ``NACL_EXE_STDERR``, or
113 ``NACLLOG`` variables to redirect output to a file, you must run Chrome with
114 the ``--no-sandbox`` flag. You must also be careful that each variable points
117 Logging calls to Pepper interfaces
118 ----------------------------------
120 You can log all Pepper calls your module makes by passing the following flags
121 to Chrome on startup::
123 --vmodule=ppb*=4 --enable-logging=stderr
126 The ``vmodule`` flag tells Chrome to log all calls to C Pepper interfaces that
127 begin with "ppb" (that is, the interfaces that are implemented by the browser
128 and that your module calls). The ``enable-logging`` flag tells Chrome to log
133 Debugging with Visual Studio
134 ----------------------------
136 If you develop on a Windows platform you can use the :doc:`Native Client Visual
137 Studio add-in <vs-addin>` to write and debug your code. The add-in defines new
138 project platforms that let you run your module in two different modes: As a
139 Pepper plugin and as a Native Client module. When running as a Pepper plugin
140 you can use the built-in Visual Studio debugger. When running as a Native
141 Client module Visual Studio will launch an instance of nacl-gdb for you and
142 link it to the running code.
146 Debugging with nacl-gdb
147 -----------------------
149 The Native Client SDK includes a command-line debugger that you can use to
150 debug Native Client modules. The debugger is based on the GNU debugger `gdb
151 <http://www.gnu.org/software/gdb/>`_, and is located at
152 ``pepper_<version>/toolchain/<platform>_x86_newlib/bin/x86_64-nacl-gdb`` (where
153 *<platform>* is the platform of your development machine: ``win``, ``mac``, or
156 Note that this same copy of GDB can be used to debug any NaCl program,
157 whether built using newlib or glibc for x86-32, x86-64 or ARM. In the SDK,
158 ``i686-nacl-gdb`` is an alias for ``x86_64-nacl-gdb``, and the ``newlib``
159 and ``glibc`` toolchains both contain the same version of GDB.
161 .. _debugging_pnacl_pexes:
163 Debugging PNaCl pexes (Pepper 35 or later)
164 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
166 If you want to use GDB to debug a program that is compiled with the PNaCl
167 toolchain, you must have a copy of the pexe from **before** running
168 ``pnacl-finalize``. The ``pnacl-finalize`` tool converts LLVM bitcode
169 to the stable PNaCl bitcode format, but it also strips out debug
170 metadata, which we need for debugging. In this section we'll give the
171 LLVM bitcode file a ``.bc`` file extension, and the PNaCl bitcode file
172 a ``.pexe`` file extension. The actual extension should not matter, but
173 it helps distinguish between the two types of files.
175 **Note** unlike the finalized copy of the pexe, the non-finalized debug copy
176 is not considered stable. This means that a debug copy of the PNaCl
177 application created by a Pepper N SDK is only guaranteed to run
178 with a matching Chrome version N. If the version of the debug bitcode pexe
179 does not match that of Chrome then the translation process may fail, and
180 you will see an error message in the JavaScript console.
182 Also, make sure you are passing the ``-g`` :ref:`compile option
183 <compile_flags>` to ``pnacl-clang`` to enable generating debugging info.
184 You might also want to omit ``-O2`` from the compile-time and link-time
185 options, otherwise GDB not might be able to print variables' values when
186 debugging (this is more of a problem with the PNaCl/LLVM toolchain than
189 Once you have built a non-stable debug copy of the pexe, list the URL of
190 that copy in your application's manifest file:
198 "url": "release_version.pexe",
202 "url": "debug_version.bc",
209 Copy the ``debug_version.bc`` and ``nmf`` files to the location that
210 your local web server serves files from.
212 When you run Chrome with ``--enable-nacl-debug``, Chrome will translate
213 and run the ``debug_version.bc`` instead of ``release_version.pexe``.
214 Once the debug version is loaded, you are ready to :ref:`run nacl-gdb
217 Whether you publish the NMF file containing the debug URL to the release
218 web server, is up to you. One reason to avoid publishing the debug URL
219 is that it is only guaranteed to work for the Chrome version that matches
220 the SDK version. Developers who may have left the ``--enable-nacl-debug``
221 flag turned on may end up loading the debug copy of your application
222 (which may or may not work, depending on their version of Chrome).
225 Debugging PNaCl pexes (with older Pepper toolchains)
226 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
228 If you want to use GDB to debug a program that is compiled with the PNaCl
229 toolchain, you must convert the ``pexe`` file to a ``nexe``. (You can skip
230 this step if you are using the GCC toolchain, or if you are using
233 * Firstly, make sure you are passing the ``-g`` :ref:`compile option
234 <compile_flags>` to ``pnacl-clang`` to enable generating debugging info.
235 You might also want to omit ``-O2`` from the compile-time and link-time
238 * Secondly, use ``pnacl-translate`` to convert your ``pexe`` to one or more
239 ``nexe`` files. For example:
244 nacl_sdk/pepper_<version>/toolchain/win_pnacl/bin/pnacl-translate \
245 --allow-llvm-bitcode-input hello_world.pexe -arch x86-32 \
246 -o hello_world_x86_32.nexe
247 nacl_sdk/pepper_<version>/toolchain/win_pnacl/bin/pnacl-translate \
248 --allow-llvm-bitcode-input hello_world.pexe -arch x86-64 \
249 -o hello_world_x86_64.nexe
251 For this, use the non-finalized ``pexe`` file produced by
252 ``pnacl-clang``, not the ``pexe`` file produced by ``pnacl-finalize``.
253 The latter ``pexe`` has debugging info stripped out. The option
254 ``--allow-llvm-bitcode-input`` tells ``pnacl-translate`` to accept a
255 non-finalized ``pexe``.
257 * Replace the ``nmf`` :ref:`manifest file <manifest_file>` that points to
258 your ``pexe`` file with one that points to the ``nexe`` files. For the
259 example ``nexe`` filenames above, the new ``nmf`` file would contain:
266 "x86-32": {"url": "hello_world_x86_32.nexe"},
267 "x86-64": {"url": "hello_world_x86_64.nexe"},
271 * Change the ``<embed>`` HTML element to use
272 ``type="application/x-nacl"`` rather than
273 ``type="application/x-pnacl"``.
275 * Copy the ``nexe`` and ``nmf`` files to the location that your local web
276 server serves files from.
281 **Note:** If you know whether Chrome is using the x86-32 or x86-64
282 version of the NaCl sandbox on your system, you can translate the
283 ``pexe`` once to a single x86-32 or x86-64 ``nexe``. Otherwise, you
284 might find it easier to translate the ``pexe`` to both ``nexe``
285 formats as described above.
287 .. _running_nacl_gdb:
292 Before you start using nacl-gdb, make sure you can :doc:`build <building>` your
293 module and :doc:`run <running>` your application normally. This will verify
294 that you have created all the required :doc:`application parts
295 <../coding/application-structure>` (.html, .nmf, and .nexe files, shared
296 libraries, etc.), that your server can access those resources, and that you've
297 configured Chrome correctly to run your application. The instructions below
298 assume that you are using a :ref:`local server <web_server>` to run your
299 application; one benefit of doing it this way is that you can check the web
300 server output to confirm that your application is loading the correct
301 resources. However, some people prefer to run their application as an unpacked
302 extension, as described in :doc:`Running Native Client Applications <running>`.
304 Follow the instructions below to debug your module with nacl-gdb:
306 #. Compile your module with the ``-g`` flag so that your .nexe retains symbols
307 and other debugging information (see the :ref:`recommended compile flags
309 #. Launch a local web server (e.g., the :ref:`web server <web_server>` included
311 #. Launch Chrome with these three required flags: ``--enable-nacl --enable-nacl-debug --no-sandbox``.
313 You may also want to use some of the optional flags listed below. A typical
314 command looks like this::
316 chrome --enable-nacl --enable-nacl-debug --no-sandbox --disable-hang-monitor localhost:5103
321 Enables Native Client for all applications, including those that are
322 launched outside the Chrome Web Store.
324 ``--enable-nacl-debug``
325 Turns on the Native Client debug stub, opens TCP port 4014, and pauses
326 Chrome to let the debugger connect.
329 Turns off the Chrome sandbox (not the Native Client sandbox). This enables
330 the stdout and stderr streams, and lets the debugger connect.
334 ``--disable-hang-monitor``
335 Prevents Chrome from displaying a warning when a tab is unresponsive.
337 ``--user-data-dir=<directory>``
338 Specifies the `user data directory
339 <http://www.chromium.org/user-experience/user-data-directory>`_ from which
340 Chrome should load its state. You can specify a different user data
341 directory so that changes you make to Chrome in your debugging session do
342 not affect your personal Chrome data (history, cookies, bookmarks, themes,
345 ``--nacl-debug-mask=<nmf_url_mask1,nmf_url_mask2,...>``
346 Specifies a set of debug mask patterns. This allows you to selectively
347 choose to debug certain applications and not debug others. For example, if
348 you only want to debug the NMF files for your applications at
349 ``https://example.com/app``, and no other NaCl applications found on the
350 web, specify ``--nacl-debug-mask=https://example.com/app/*.nmf``. This
351 helps prevent accidentally debugging other NaCl applications if you like
352 to leave the ``--enable-nacl-debug`` flag turned on. The pattern language
353 for the mask follows `chrome extension match patterns
354 </extensions/match_patterns>`_. The pattern set can be inverted by
355 prefixing the pattern set with the ``!`` character.
358 Specifies the URL Chrome should open when it launches. The local server
359 that comes with the SDK listens on port 5103 by default, so the URL when
360 you're debugging is typically ``localhost:5103`` (assuming that your
361 application's page is called index.html and that you run the local server
362 in the directory where that page is located).
364 #. Navigate to your application's page in Chrome. (You don't need to do this if
365 you specified a URL when you launched Chrome in the previous step.) Chrome
366 will start loading the application, then pause and wait until you start
367 nacl-gdb and run the ``continue`` command.
369 #. Go to the directory with your source code, and run nacl-gdb from there. For
372 cd nacl_sdk/pepper_<version>/examples/demo/drive
373 nacl_sdk/pepper_<version>/toolchain/win_x86_newlib/bin/x86_64-nacl-gdb
375 The debugger will start and show you a gdb prompt::
379 #. Run the debugging command lines.
383 (gdb) target remote localhost:4014
384 (gdb) remote get nexe <path-to-save-translated-nexe-with-debug-info>
385 (gdb) file <path-to-save-translated-nexe-with-debug-info>
386 (gdb) remote get irt <path-to-save-NaCl-integrated-runtime>
387 (gdb) nacl-irt <path-to-saved-NaCl-integrated-runtime>
391 (gdb) target remote localhost:4014
392 (gdb) nacl-manifest <path-to-your-.nmf-file>
393 (gdb) remote get irt <path-to-save-NaCl-integrated-runtime>
394 (gdb) nacl-irt <path-to-saved-NaCl-integrated-runtime>
396 #. The command used for PNaCl and NaCl are described below:
398 ``target remote localhost:4014``
399 Tells the debugger how to connect to the debug stub in the Native Client
400 application loader. This connection occurs through TCP port 4014 (note
401 that this port is distinct from the port which the local web server uses
402 to listen for incoming requests, typically port 5103). If you are
403 debugging multiple applications at the same time, the loader may choose
404 a port that is different from the default 4014 port. See the Chrome
405 task manager for the debug port.
407 ``remote get nexe <path>``
408 This saves the application's main executable (nexe) to ``<path>``.
409 For PNaCl, this provides a convenient way to access the nexe that is
410 a **result** of translating your pexe. This can then be loaded with
411 the ``file <path>`` command.
413 ``nacl-manifest <path>``
414 For NaCl (not PNaCl), this tells the debugger where to find your
415 application's executable (.nexe) files. The application's manifest
416 (.nmf) file lists your application's executable files, as well as any
417 libraries that are linked with the application dynamically.
419 ``remote get irt <path>``
420 This saves the Native Client Integrated Runtime (IRT). Normally,
421 the IRT is located in the same directory as the Chrome executable,
422 or in a subdirectory named after the Chrome version. For example, if
423 you're running Chrome canary on Windows, the path to the IRT typically
424 looks something like ``C:/Users/<username>/AppData/Local/Google/Chrome
425 SxS/Application/23.0.1247.1/nacl_irt_x86_64.nexe``.
426 The ``remote get irt <path>`` saves that to the current working
427 directory so that you do not need to find where exactly the IRT
431 Tells the debugger where to find the Native Client Integrated Runtime
432 (IRT). ``<path>`` can either be the location of the copy saved by
433 ``remote get irt <path>`` or the copy that is installed alongside Chrome.
435 A couple of notes on how to specify path names in the nacl-gdb commands
438 * You can use a forward slash to separate directories on Linux, Mac, and
439 Windows. If you use a backslash to separate directories on Windows, you
440 must escape the backslash by using a double backslash "\\" between
442 * If any directories in the path have spaces in their name, you must put
443 quotation marks around the path.
445 As an example, here is a what these nacl-gdb commands might look like on
448 target remote localhost:4014
449 nacl-manifest "C:/nacl_sdk/pepper_<version>/examples/hello_world_gles/newlib/Debug/hello_world_gles.nmf"
450 nacl-irt "C:/Users/<username>/AppData/Local/Google/Chrome SxS/Application/23.0.1247.1/nacl_irt_x86_64.nexe"
452 To save yourself some typing, you can put put these nacl-gdb commands in a
453 script file, and execute the file when you run nacl-gdb, like so::
455 nacl_sdk/pepper_<version>/toolchain/win_x86_newlib/bin/x86_64-nacl-gdb -x <nacl-script-file>
457 If nacl-gdb connects successfully to Chrome, it displays a message such as
458 the one below, followed by a gdb prompt::
460 0x000000000fc00200 in _start ()
463 If nacl-gdb can't connect to Chrome, it displays a message such as
464 "``localhost:4014: A connection attempt failed``" or "``localhost:4014:
465 Connection timed out.``" If you see a message like that, make sure that you
466 have launched a web server, launched Chrome, and navigated to your
467 application's page before starting nacl-gdb.
469 Once nacl-gdb connects to Chrome, you can run standard gdb commands to execute
470 your module and inspect its state. Some commonly used commands are listed
474 set a breakpoint at <location>, e.g.::
476 break hello_world.cc:79
477 break hello_world::HelloWorldInstance::HandleMessage
481 resume normal execution of the program
484 execute the next source line, stepping over functions
487 execute the next source line, stepping into functions
489 ``print <expression>``
490 print the value of <expression> (e.g., variables)
493 print a stack backtrace
496 print a table of all breakpoints
498 ``delete <breakpoint>``
499 delete the specified breakpoint (you can use the breakpoint number displayed
503 print documentation for the specified gdb <command>
508 See the `gdb documentation
509 <http://sourceware.org/gdb/current/onlinedocs/gdb/#toc_Top>`_ for a
510 comprehensive list of gdb commands. Note that you can abbreviate most commands
511 to just their first letter (``b`` for break, ``c`` for continue, and so on).
513 To interrupt execution of your module, press <Ctrl-c>. When you're done
514 debugging, close the Chrome window and type ``q`` to quit gdb.
516 Debugging with other tools
517 ==========================
519 If you cannot use the :ref:`Visual Studio add-in <visual_studio>`, or you want
520 to use a debugger other than nacl-gdb, you must manually build your module as a
521 Pepper plugin (sometimes referred to as a "`trusted
522 <http://www.chromium.org/nativeclient/getting-started/getting-started-background-and-basics#TOC-Trusted-vs-Untrusted>`_"
523 or "in-process" plugin). Pepper plugins (.DLL files on Windows; .so files on
524 Linux; .bundle files on Mac) are loaded directly in either the Chrome renderer
525 process or a separate plugin process, rather than in Native Client. Building a
526 module as a trusted Pepper plugin allows you to use standard debuggers and
527 development tools on your system, but when you're finished developing the
528 plugin, you need to port it to Native Client (i.e., build the module with one
529 of the toolchains in the NaCl SDK so that the module runs in Native Client).
530 For details on this advanced development technique, see `Debugging a Trusted
532 <http://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin>`_.
533 Note that starting with the ``pepper_22`` bundle, the NaCl SDK for Windows
534 includes pre-built libraries and library source code, making it much easier to
535 build a module into a .DLL.
538 .. |menu-icon| image:: /images/menu-icon.png
539 .. |puzzle| image:: /images/puzzle.png