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.
Requirements
For command-line native debugging to work, these requirements must be met:
- Build your app using the
ndk-build
script. Thendk-gdb
script does not support using the legacymake APP=<name>
method to build. - Enable app debugging in your
AndroidManifest.xml
file by including an<application>
element that sets theandroid:debuggable
attribute totrue
. - 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.
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. If you prefer using
the LLDB Debugger, use the --lldb
option when invoking the ndk-gdb
script.
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.
Option | Description> |
---|---|
--lldb |
If set, the script will use the LLDB Debugger for the session instead of gdb. |
--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 |
--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 |
--launch=<name> |
This option is similar to |
--launch-list |
This convenience option prints the list of all launchable activity names found in your
app manifest. |
--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, |
--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:
Alternatively, you can define the |
--exec=<file> -x <file> |
This option tells |
--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
|
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.
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.