The NDK includes a shell script named
ndk-gdb to start a
command-line native debugging session. Users who prefer to use a GUI should
read the documentation for debugging in
Android Studio instead.
For command-line native debugging to work, these requirements must be met:
- Build your app using the
ndk-gdbscript does not support using the legacy
make APP=<name>method to build.
- Enable app debugging in your
AndroidManifest.xmlfile by including an
<application>element that sets the
- 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.xmlfile does not matter.
- Develop your app in a Unix shell. On Windows, use Cygwin
or the experimental
- Use GNU Make 3.81 or higher.
To invoke the
ndk-gdb script, change into the application directory or any directory under
it. For example:
cd $PROJECT $NDK/ndk-gdb
$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
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
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
b <location> to set breakpoints, and
c (for "continue") to
resume execution. For a comprehensive list of commands, see the
GDB manual. If you prefer using
the LLDB Debugger, use the
option when invoking the
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.
ndk-gdb searches for an already-running application process, and displays an
error if it doesn't find one. You can, however, use the
--launch=<name> option to automatically start your activity before the debugging
session. For more information, see 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.
If set, the script will use the LLDB Debugger for the session instead of gdb.
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 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
When you start
This option is similar to
This convenience option prints the list of all launchable activity names found in your
|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.
This option specifies the adb tool executable. It is only necessary if you have not set your path to include that executable.
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:
Alternatively, you can define the
This option tells
Disable pausing the Java code until GDB connects. Passing this option may cause the debugger to miss early breakpoints.
Enable Text User Interface if it is available.
This option is an extra flag (or flags) to pass to the
Note: The final three options in this table are only for the
Python version of
If your app runs on a platform older than Android 2.3 (API level 9),
cannot debug native threads properly. The debugger can only debug the main thread, abd completely
ignores the execution of other threads.
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.