ndk-gdb

The NDK includes a helper shell script named ndk-gdb to easily launch a native debugging session for your NDK-generated machine code.

Requirements

For native debugging to work, you must follow these requirements:

• Build your app using the ndk-build script. The ndk-gdb script does not support using the legacy make APP=<name> method to build.

• Enable app debugging in your AndroidManifest.xml file by including an <application> element that sets the android:debuggable attribute to true.
• Build your app to run on Android 2.2 (Android API level 8) or higher.
• Debug on a device or emulator running Android 2.2 or higher. For debugging purposes, the target API level that you declare in your AndroidManifest.xml file does not matter.
• Develop your app in a Unix shell. On Windows, use Cygwin or the experimental ndk-gdb-py Python implementation.
• Use GNU Make 3.81 or higher.
• If you are building your app from Eclipse, build it using version 0.9.7 or higher of the ADT plug-in.

Usage

To invoke the ndk-gdb script, change into the application directory or any directory under it. For example:

cd $PROJECT
$NDK/ndk-gdb

Here, $PROJECT points to your project's root directory, and $NDK points to your NDK installation path.

When you invoke ndk-gdb, it configures the session to look for your source files and symbol/debug versions of your generated native libraries. On successfully attaching to your application process, ndk-gdb outputs a long series of error messages, noting that it cannot find various system libraries. This is normal, because your host machine does not contain symbol/debug versions of these libraries on your target device. You can safely ignore these messages.

Next, ndk-gdb displays a normal GDB prompt.

You interact with ndk-gdb in the same way as you would with GNU GDB. For example, you can use b <location> to set breakpoints, and c (for "continue") to resume execution. For a comprehensive list of commands, see the GDB manual.

Note that when you quit the GDB prompt, the application process that you're debugging stops. This behavior is a gdb limitation.

ndk-gdb handles many error conditions, and displays an informative error message if it finds a problem. these checks include making sure that the following conditions are satisfied:

• Checks that ADB is in your path.
• Checks that your application is declared debuggable in its manifest.
• Checks that, on the device, the installed application with the same package name is also debuggable.

By default, ndk-gdb searches for an already-running application process, and displays an error if it doesn't find one. You can, however, use the --start or --launch=<name> option to automatically start your activity before the debugging session. For more information, see Options.

Options

To see a complete list of options, type ndk-gdb --help on the command line. Table 1 shows a number of the more commonly used ones, along with brief descriptions.

Table 1. Common ndk-gdb options and their descriptions.

Starting ndk-gdb with this option specified launches the first launchable activity listed in your application manifest. Use --launch=<name> to start the next launchable activity. To dump the list of launchable activities, run --launch-list from the command line.

Option	Description>
--verbose	This option tells the build system to print verbose information about the native-debugging session setup. It is necessary only for debugging problems when the debugger can't connect to the app, and the error messages that ndk-gdb displays are not enough.
--force	By default, ndk-gdb aborts if it finds that another native debugging session is already running on the same device. This option kills the other session, and replaces it with a new one. Note that this option does not kill the actual app being debugged, which you must kill separately.
--start	When you start ndk-gdb, it tries by default to attach to an existing running instance of your app on the target device. You can override this default behavior by using --start to explicitly launch the application on the target device before the debugging session.
--launch=<name>	This option is similar to --start, except that it allows you to start a specific activity from your application. This feature is only useful if your manifest defines multiple launchable activities.
--launch-list	This convenience option prints the list of all launchable activity names found in your app manifest. --start uses the first activity name.
--project=<path>	This option specifies the app project directory. It is useful if you want to launch the script without first having to change to the project directory.
--port=<port>	By default, ndk-gdb uses local TCP port 5039 to communicate with the app it is debugging on the target device. Using a different port allows you to natively debug programs running on different devices or emulators connected to the same host machine.
--adb=<file>	This option specifies the adb tool executable. It is only necessary if you have not set your path to include that executable.
-d -e -s <serial>	These flags are similar to the adb commands with the same names. Set these flags if you have several devices or emulators connected to your host machine. Their meanings are as follows: -d Connect to a single physical device. -e Connect to a single emulator device. -s <serial> Connect to a specific device or emulator. Here, <serial> is the device's name as listed by the adb devices command. Alternatively, you can define the ADB_SERIAL environment variable to list a specific device, without the need for a specific option.
--exec=<file> -x <file>	This option tells ndk-gdb to run the GDB initialization commands found in <file> after connecting to the process it is debugging. This is a useful feature if you want to do something repeatedly, such as setting up a list of breakpoints, and then resuming execution automatically.
--nowait	Disable pausing the Java code until GDB connects. Passing this option may cause the debugger to miss early breakpoints.
--tui -t	Enable Text User Interface if it is available.
--gnumake-flag=<flag>	This option is an extra flag (or flags) to pass to the ndk-build system when querying it for project information. You can use multiple instances of this option in the same command.
--stdcxx-py-pr={auto|none|gnustdcxx[-GCCVER]|stlport}	Use specified Python pretty-printers for displaying types in the Standard C++ Library. auto mode works by looking at the .so files for a libstdc++ library, and as such only works for a shared library. When linking statically to a libstdc++ library, you must specify the required printers. The default is none.

Note: The final three options in this table are only for the Python version of ndk-gdb.

Thread Support

If your app runs on a platform older than Android 2.3 (API level 9), ndk-gdb cannot debug native threads properly. The debugger can only debug the main thread, abd completely ignores the execution of other threads.

Using a version of Android prior to 2.3 causes ndk-gdb to display the following message prior to showing the GDB prompt:

Thread debugging is unsupported on this Android platform!

If you place a breakpoint on a function executed on a non-main thread, the program exits, and GDB displays the following message:

Program terminated with signal SIGTRAP, Trace/breakpoint trap.
      The program no longer exists.