Debugging Tips

This page describes strategies you can use to debug your modules, concentrating on techniques that don't use a debugger. Although a debugger exists for Linux (as of the April 23 release), no Native Client debugger is available for Mac or Windows.

Note: We're actively working on improving the debuggability of Native Client modules. If you'd like to help — by porting a debugger to Mac or Windows, for example — please volunteer! You can contact us on the Native Client Discuss group.


Design your module to run standalone

If your module can run both as a standalone Linux or Mac application and within Native Client, then you can use a debugger such as GDB, KDbg, or Xcode to debug the standalone form of your application.

Note: Building standalone applications is not supported on Windows.

For examples of creating a module that also works standalone, see the earth, life, tone, and voronoi examples under native_client/tests.

Catch errors at compile time

It's easier to fix bugs you find at compile time than those you find at runtime. When you compile your module, use gcc flags such as -Werror and -Wall to help ensure that your code is as clean as possible. For example:

nacl-g++ -Wall -Werror -O3 -mfpmath=sse -msse -fomit-frame-pointer -lpthread -lm -o earth_release.nexe

Use printf and assert if necessary

If a bug doesn't appear in the standalone app version of a module, you might have to use printf and assert to debug your module when it runs in Native Client.

Note: Using printf can be useful on Linux and Mac, but it's more difficult on Windows. For the latest Windows testing tips, see the wiki page DebuggingModulesOnWindows.

Some notes on using printf and assert:


Here's an example of using printf:

#include <stdio.h>
  printf("Multimedia system failed to initialize!  errno: %d\n", errno);

Here's an example of using assert:

#include <assert.h>

int foo(int x) {
  assert(x != 0);

Launching the browser from the command line

On Linux and Mac, if you launch your browser from the command line, the output of printf and assert goes to the window you used to enter the command. Make sure the window has a large scroll buffer, so you don't lose output. Better yet, use the GNU Screen program or an Emacs shell, so you can easily search the output.

Platform How to launch Firefox from the command line
Linux /usr/bin/firefox2
Mac /Applications/

Platform-specific output locations

If you launch the browser using a menu, button, or icon (rather than from the command line) the output of printf or assert goes to a location that depends on the platform you're using.

Platform Default output location
Linux $HOME/.xsession-errors
Mac /var/log/system.log

Use nacl-gdb (Linux only)

The Linux nacl-gdb tool is a version of GDB that can deal with Native Client's memory and address space conventions. For details, see the nacl-gdb page.

Mac and Windows don't have Native Client ports of GDB or any other debuggers. Debuggers need to be ported to Native Client because Native Client modules' use of segmented memory protection confuses the kernel exception handler, which in turn interferes with handling breakpoints. Also, the segmented structure of the Native Client address space interferes with symbol resolution.

Except as otherwise noted, the content of this page is licensed under a Creative Commons Attribution 2.5 license.