| 'ndk-gdb' and 'ndk-gdb-py' Overview |
| === |
| |
| IMPORTANT: IF YOU ARE DEBUGGING THREADED PROGRAMS, PLEASE READ THE |
| SECTION BELOW TITLED 'Thread Support'. |
| |
| I. Usage: |
| --------- |
| |
| The Android NDK r4 introduced a helper shell script named 'ndk-gdb' to |
| easily launch a native debugging session for your NDK-generated machine code. |
| |
| The script is located at the top-level directory of the NDK, and shall |
| be invoked from the command-line when in your application project |
| directory, or any of its sub-directories. For example: |
| |
| cd $PROJECT |
| $NDK/ndk-gdb |
| |
| Where $NDK points to your NDK installation path. You can also create an |
| alias or add $NDK to your PATH to avoid typing it every time. |
| |
| IMPORTANT: Native debugging can only work if *all* these conditions are met: |
| |
| 1. Your application is built with the 'ndk-build' script: |
| |
| Building with the legacy "make APP=<name>" method is not |
| supported by ndk-gdb. |
| |
| 2. Your application is debuggable: |
| |
| In other words, your AndroidManifest.xml has an <application> |
| element that sets the android:debuggable attribute to "true" |
| |
| 3. You are running your application on Android 2.2 (or higher): |
| |
| ndk-gdb will not work if you try to run your application on |
| previous versions of the system. That does not mean that your |
| application should target the Android 2.2. API level, just |
| that the debugging session should happen on a 2.2+ device or |
| emulator system image. |
| |
| IMPORTANT IMPORTANT IMPORTANT !! |
| |
| If you are using the ADT Eclipse plug-in to build your |
| application, make sure you're using version 0.9.7 or |
| later. |
| |
| If you are using the 'ant' build tool, make sure that you |
| have the latest revision of the SDK Platform components. |
| The following minimal revisions are required: |
| |
| Android 1.5 r4 |
| Android 1.6 r3 |
| Android 2.1 r2 |
| Android 2.2 r1 |
| |
| These should be available through the SDK updater. |
| |
| If these conditions are not met, the generated .apk will |
| not contain required support files and native debugging |
| will not be possible. |
| |
| 'ndk-gdb' handles many error conditions and will dump an informative error |
| message if it finds a problem. For example, it: |
| |
| - 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 will search for an already-running application process, |
| and will dump 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. |
| |
| When it successfully attaches to your application process, ndk-gdb will give |
| you a normal GDB prompt, after setting up the session to properly look for |
| your source files and symbol/debug versions of your generated native |
| libraries. |
| |
| You can set breakpoints with 'b <location>' and resume execution with 'c' |
| (for 'continue'). See the GDB manual for a list of commands. |
| |
| IMPORTANT: When quitting the GDB prompt, your debugged application process |
| will be stopped! This is a gdb limitation. |
| |
| IMPORTANT: The GDB prompt will be preceded by a long list of error messages, |
| where gdb complains that it cannot find various system libraries |
| (e.g. libc.so, libstdc++.so, liblog.so, libcutils.so, etc...) |
| |
| This is normal, because there are no symbol/debug versions of |
| these libraries corresponding to your target device on your |
| development machine. You can safely ignore these messages. |
| |
| II. Options: |
| ------------ |
| |
| To see a list of options, type 'ndk-gdb --help'. Notable ones are: |
| |
| `--verbose`: |
| > Print verbose information about the native debugging session setup. |
| Only needed to debug problems when you can't connect and that the |
| error messages printed by ndk-gdb are not enough. |
| |
| `--force`: |
| > By default, ndk-gdb aborts if it finds that another native debugging |
| session is running on the same device. Using --force will kill the |
| session, and replace it with a new one. Note that the debugged program |
| is *not* killed and will be stopped again. |
| |
| `--start`: |
| > By default, ndk-gdb will try to attach to an existing running instance |
| of your application on the target device. You can use --start to |
| explicitly launch your application before the debugging session. |
| |
| > NOTE: This launches the first launchable activity listed from your |
| application manifest. Use `--launch=<name>` to start another one. |
| See `--launch-list` to dump the list of such activities. |
| |
| `--launch=<name>`: |
| > This is similar to --start, except that it allows you to start a specific |
| activity from your application. This is only useful if your manifest |
| defines several launchable activities. |
| |
| `--launch-list`: |
| > Convenience option that prints the list of all launchable activity names |
| found in your application manifest. The first one will be used by --start |
| |
| `--project=<path>`: |
| > Specify application project directory. Useful if you want to launch |
| the script without cd-ing to the directory before that. |
| |
| `--port=<port>`: |
| > By default, ndk-gdb will use local TCP port 5039 to communicate with |
| the debugged application. By using a different port, it is possible |
| to natively debug programs running on different devices/emulators |
| connected to the same development machine. |
| |
| `--adb=<file>`: |
| > Specify the adb tool executable, in case it is not in your path. |
| |
| `-d`, `-e`, `-s <serial>`: |
| > These flags are similar to the ADB ones and allow you to handle the |
| case where you have several devices/emulators connected to your |
| development machine. |
| |
| -d: Connect to a single physical device |
| -e: Connect to a single emulator device |
| -s <serial>: Connect to a specific device or emulator |
| where <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>`: |
| > After connecting to the debugged process, run the GDB initialization |
| commands found in <file>. This is useful if you want to do something |
| repeatedly, e.g. setting up a list of breakpoints then resuming |
| execution automatically. |
| |
| `--nowait`: |
| > Disable pausing the Java code until GDB connects. Passing this option |
| may cause early breakpoints to be missed. |
| |
| `--tui`: |
| `-t`: |
| > Enable Text User Interface if GDB was built with it. [ndk-gdb-py only] |
| |
| `--gnumake-flag=<flag>`: |
| > Extra flag(s) to pass to the ndk-build system when querying it for |
| project information. Multiple instances can be used. [ndk-gdb-py only] |
| |
| `--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 in the shared scenario. |
| When linking statically to a libstdc++ library, the required printers |
| must be specified. The default is 'none'. [ndk-gdb-py only] |
| |
| |
| III. Requirements: |
| ------------------ |
| |
| 'ndk-gdb' requires a Unix shell to run. This means that Cygwin is required |
| to run it on Windows. An experimental Python re-implementation called |
| 'ndk-gdb-py' is also provided, removing this restriction and providing |
| some new features. |
| |
| The other NDK requirements apply: e.g. GNU Make 3.81 or higher. |
| |
| |
| IV. Thread Support: |
| ------------------- |
| |
| If your application runs on a platform older than Android 2.3, ndk-gdb will |
| not be able to debug native threads properly. Instead, the debugger will only |
| be able to put breakpoints on the main thread, completely ignoring the |
| execution of other ones. |
| |
| The root of the problem is complex, but is essentially due to a very unfortunate |
| bug in the platform, which was only discovered lately. |
| |
| The gdbserver binary that comes with this NDK has special code to detect this |
| condition at runtime and adapt its behaviour automatically (in other words, |
| you don't have anything special to do when building your code). |
| |
| What this means in practical terms are: |
| |
| - If you are on Android 2.3, or a prior platform release which has had the |
| platform bug-fix back-ported to it, you will be able to debug native |
| threads automatically. |
| |
| - If you are not, you will only be able to debug the main thread |
| (as in previous NDK releases). You will also see the following message |
| when launching ndk-gdb (just before 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 will exit with the following message in GDB: |
| |
| Program terminated with signal SIGTRAP, Trace/breakpoint trap. |
| The program no longer exists. |