Native Client

Debugging

This chapter describes tools and techniques you can use to debug, monitor, and measure your application's performance.

Native Client does not currently support debugging from within an IDE such as Visual Studio or Xcode. In the near future we plan to release utilities and instructions to enable you to debug a Native Client application as a Pepper plugin using a gdb command line interface in a terminal window and also from your favorite development environment. Stay tuned.

Viewing process statistics with the task manager

You can use Chrome's Task Manager to display information about a Native Client application:

  1. Open the Task Manager by clicking the wrench icon wrench icon and choosing Tools > Task Manager.
  2. When the Task Manager window appears, verify that the columns displaying memory information are visible. If they are not, right click in the header row and select the memory items from the popup menu that appears.

A browser window running a Native Client application will have at least two processes associated with it: a process for the app's top level (the render process managing the page including its HTML and any JavaScript) and one or more processes for each instance of a Native Client module embedded in the page (each process running native code from one nexe file). The top-level process appears with the application's icon and begins with the text "App:". A Native Client process appears with a Chrome extension icon (a jigsaw puzzle piece puzzle icon) and begins with the text "Native Client module" followed by the URL of its manifest file.

From the Task Manager you can view the changing memory allocations of all the processes associated with a Native Client application. Each process has its own memory footprint. You can also see the rendering rate displayed as frames per second (FPS). Note that the computation of render frames can be performed in any process, but the rendering itself is always done in the top level application process, so look for the rendering rate there.

Controlling the level of Native Client error and warning messages

Native Client prints warning and error messages to stdout and stderr. You can increase the amount of Native Client's diagnostic output by setting these environment variables:

  • NACL_DEBUG_ENABLE=1
  • PPAPI_BROWSER_DEBUG=1
  • NACL_PLUGIN_DEBUG=1
  • NACL_PPAPI_PROXY_DEBUG=1
  • NACL_SRPC_DEBUG=[1-255] (# pick higher number for increased verbosity)
  • NACLVERBOSITY=[1-255]

Writing messages to the JavaScript console

You can send messages from your C/C++ code to JavaScript using the PostMessage call in the Pepper messaging system. When the message is received its handler can call the console.log() function to write the message to the JavaScript console in Chrome's Developer Tools.

Debugging with printf

Your C/C++ code can perform inline printf debugging to stderr and stdout by calling fprintf directly or using cover functions like these:

#include <stdio.h>
void logmsg(const char* pMsg){
  fprintf(stdout,"logmsg: %s\n",pMsg);
}
void errormsg(const char* pMsg){
  fprintf(stderr,"logerr: %s\n",pMsg);
}

Redirecting messages to log files

You can redirect stdout and stderr to a file by setting these environment variables:

  • NACL_EXE_STDOUT=c:\nacl_stdout.log
  • NACL_EXE_STDERR=c:\nacl_stderr.log

There is another variable, NACLLOG, that can be used to redirect the output of of Native Client's internally-generated messages. It is set to stderr by default, you can direct these messages to another file:

  • NACLLOG=c:\nacl.log

Note: If you set the NACL_EXE_STDOUT, NACL_EXE_STDERR, or NACLLOG variables to redirect to a file you must run Chrome with the --no-sandbox flag. You must also be careful that each variable points to a different file.

Redirecting messages to the JavaScript console

You can use redirection to cause printf messages from your native code to be relayed to your web page via a PostMessage call, where they can then be written to the the JavaScript console as described above. Follow these steps:

  1. Set the NACL_EXE_STDOUT and NACL_EXE_STDERR environment variables as follows:
    • NACL_EXE_STDOUT=DEBUG_ONLY:dev://postmessage
    • NACL_EXE_STDERR=DEBUG_ONLY:dev://postmessage

    These settings tell Native Client to use the Pepper messaging system to send output that your Native Client module writes to stdout and stderr to the JavaScript side of your application.

  2. Register a JavaScript handler to receive messages from your Native Client module:
    <div id="nacl_container">
      <script type="text/javascript">
        var container = document.getElementById('nacl_container');
        container.addEventListener('message', handleMessage, true);
      </script>
      <embed id="nacl_module"
             src="my_application.nmf"
             type="application/x-nacl" />
    </div>
  3. Implement a simple JavaScript handler that logs messages it receives to the JavaScript console:
    function handleMessage(message_event) {
      console.log(message_event.data);
    }

    This handler works in the simple case where the only messages your Native Client module passes to JavaScript are messages with the output from stdout and stderr. If your Native Client module also passes other messages to JavaScript, your handler will need to be more complex.

    Once you've implemented a message handler and set up the environment variables as described above, you can check the JavaScript console to see the output that your Native Client module prints to stdout and stderr. Keep in mind that your module makes a call to PostMessage() every time it flushes stdout or stderr, so your application's performance will degrade if you print and flush frequently.

Advanced debugging

As mentioned above, Native Client does not currently have debugging support integrated into IDEs. Until then, you can use some open source tools to debug your modules on Windows, Mac, and Linux:

  • Debug with nacl64-gdb (64-bit Windows and 64-bit Linux only)
    • Use nacl64-gdb to debug your Native Client application from the command line.
  • Debug in Visual Studio with WinGDB (64-bit Windows only)
    • Use the WinGDB plug-in to debug your Native Client application in Visual Studio. WinGDB connects to nacl64-gdb (follow the instructions in Debug with nacl64-gdb to install the nacl64-gdb package).

      Note: If you use nacl64-gdb or WinGDB, you can develop your application using the pepper_20 SDK bundle, but you must use a recent version of Chrome for nacl64-gdb to work. Follow the instructions in the linked documents above to get and configure the required version of Chrome.
  • Debug your Native Client application as a trusted Pepper plug-in (Windows, Mac, and Linux)
    • Trusted Pepper plug-ins are loaded directly in either the Chrome renderer process or a separate plug-in process, rather than in Native Client. Developing your application as a trusted Pepper plug-in allows you to use standard debuggers and development tools, but when you're finished developing the application, you need to port it to Native Client (i.e., build the application with the toolchain in the NaCl SDK so that it runs in Native Client).

Open source profiling tools

For the brave-hearted there are open source tools at Chromium.org that describe how to do profiling on 64-bit Windows and Linux machines.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.