1'ndk-gdb' and 'ndk-gdb-py' Overview 2=== 3 4IMPORTANT: IF YOU ARE DEBUGGING THREADED PROGRAMS, PLEASE READ THE 5 SECTION BELOW TITLED 'Thread Support'. 6 7I. Usage: 8--------- 9 10The Android NDK r4 introduced a helper shell script named 'ndk-gdb' to 11easily launch a native debugging session for your NDK-generated machine code. 12 13The script is located at the top-level directory of the NDK, and shall 14be invoked from the command-line when in your application project 15directory, or any of its sub-directories. For example: 16 17 cd $PROJECT 18 $NDK/ndk-gdb 19 20Where $NDK points to your NDK installation path. You can also create an 21alias or add $NDK to your PATH to avoid typing it every time. 22 23IMPORTANT: Native debugging can only work if *all* these conditions are met: 24 25 1. Your application is built with the 'ndk-build' script: 26 27 Building with the legacy "make APP=<name>" method is not 28 supported by ndk-gdb. 29 30 2. Your application is debuggable: 31 32 In other words, your AndroidManifest.xml has an <application> 33 element that sets the android:debuggable attribute to "true" 34 35 3. You are running your application on Android 2.2 (or higher): 36 37 ndk-gdb will not work if you try to run your application on 38 previous versions of the system. That does not mean that your 39 application should target the Android 2.2. API level, just 40 that the debugging session should happen on a 2.2+ device or 41 emulator system image. 42 43 IMPORTANT IMPORTANT IMPORTANT !! 44 45 If you are using the ADT Eclipse plug-in to build your 46 application, make sure you're using version 0.9.7 or 47 later. 48 49 If you are using the 'ant' build tool, make sure that you 50 have the latest revision of the SDK Platform components. 51 The following minimal revisions are required: 52 53 Android 1.5 r4 54 Android 1.6 r3 55 Android 2.1 r2 56 Android 2.2 r1 57 58 These should be available through the SDK updater. 59 60 If these conditions are not met, the generated .apk will 61 not contain required support files and native debugging 62 will not be possible. 63 64'ndk-gdb' handles many error conditions and will dump an informative error 65message if it finds a problem. For example, it: 66 67 - checks that adb is in your path. 68 69 - checks that your application is declared debuggable in its manifest. 70 71 - checks that, on the device, the installed application with the same 72 package name is also debuggable. 73 74 75By default, ndk-gdb will search for an already-running application process, 76and will dump an error if it doesn't find one. You can however use the --start 77or --launch=<name> option to automatically start your activity before the 78debugging session. 79 80When it successfully attaches to your application process, ndk-gdb will give 81you a normal GDB prompt, after setting up the session to properly look for 82your source files and symbol/debug versions of your generated native 83libraries. 84 85You can set breakpoints with 'b <location>' and resume execution with 'c' 86(for 'continue'). See the GDB manual for a list of commands. 87 88IMPORTANT: When quitting the GDB prompt, your debugged application process 89 will be stopped! This is a gdb limitation. 90 91IMPORTANT: The GDB prompt will be preceded by a long list of error messages, 92 where gdb complains that it cannot find various system libraries 93 (e.g. libc.so, libstdc++.so, liblog.so, libcutils.so, etc...) 94 95 This is normal, because there are no symbol/debug versions of 96 these libraries corresponding to your target device on your 97 development machine. You can safely ignore these messages. 98 99II. Options: 100------------ 101 102To see a list of options, type 'ndk-gdb --help'. Notable ones are: 103 104 `--verbose`: 105> Print verbose information about the native debugging session setup. 106 Only needed to debug problems when you can't connect and that the 107 error messages printed by ndk-gdb are not enough. 108 109 `--force`: 110> By default, ndk-gdb aborts if it finds that another native debugging 111 session is running on the same device. Using --force will kill the 112 session, and replace it with a new one. Note that the debugged program 113 is *not* killed and will be stopped again. 114 115 `--start`: 116> By default, ndk-gdb will try to attach to an existing running instance 117 of your application on the target device. You can use --start to 118 explicitly launch your application before the debugging session. 119 120> NOTE: This launches the first launchable activity listed from your 121 application manifest. Use `--launch=<name>` to start another one. 122 See `--launch-list` to dump the list of such activities. 123 124 `--launch=<name>`: 125> This is similar to --start, except that it allows you to start a specific 126 activity from your application. This is only useful if your manifest 127 defines several launchable activities. 128 129 `--launch-list`: 130> Convenience option that prints the list of all launchable activity names 131 found in your application manifest. The first one will be used by --start 132 133 `--project=<path>`: 134> Specify application project directory. Useful if you want to launch 135 the script without cd-ing to the directory before that. 136 137 `--port=<port>`: 138> By default, ndk-gdb will use local TCP port 5039 to communicate with 139 the debugged application. By using a different port, it is possible 140 to natively debug programs running on different devices/emulators 141 connected to the same development machine. 142 143 `--adb=<file>`: 144> Specify the adb tool executable, in case it is not in your path. 145 146 `-d`, `-e`, `-s <serial>`: 147> These flags are similar to the ADB ones and allow you to handle the 148 case where you have several devices/emulators connected to your 149 development machine. 150 151 -d: Connect to a single physical device 152 -e: Connect to a single emulator device 153 -s <serial>: Connect to a specific device or emulator 154 where <serial> is the device's name as listed 155 by the "adb devices" command. 156 157> Alternatively, you can define the ADB_SERIAL environment variable 158 to list a specific device, without the need for a specific option. 159 160 `--exec=<file>`: 161 `-x <file>`: 162> After connecting to the debugged process, run the GDB initialization 163 commands found in <file>. This is useful if you want to do something 164 repeatedly, e.g. setting up a list of breakpoints then resuming 165 execution automatically. 166 167 `--nowait`: 168> Disable pausing the Java code until GDB connects. Passing this option 169 may cause early breakpoints to be missed. 170 171 `--tui`: 172 `-t`: 173> Enable Text User Interface if GDB was built with it. [ndk-gdb-py only] 174 175 `--gnumake-flag=<flag>`: 176> Extra flag(s) to pass to the ndk-build system when querying it for 177 project information. Multiple instances can be used. [ndk-gdb-py only] 178 179 `--stdcxx-py-pr={auto|none|gnustdcxx[-GCCVER]|stlport}`: 180> Use specified Python pretty-printers for displaying types in the 181 Standard C++ Library. 'auto' mode works by looking at the .so files 182 for a libstdc++ library, and as such only works in the shared scenario. 183 When linking statically to a libstdc++ library, the required printers 184 must be specified. The default is 'none'. [ndk-gdb-py only] 185 186 187III. Requirements: 188------------------ 189 190'ndk-gdb' requires a Unix shell to run. This means that Cygwin is required 191to run it on Windows. An experimental Python re-implementation called 192'ndk-gdb-py' is also provided, removing this restriction and providing 193some new features. 194 195The other NDK requirements apply: e.g. GNU Make 3.81 or higher. 196 197 198IV. Thread Support: 199------------------- 200 201If your application runs on a platform older than Android 2.3, ndk-gdb will 202not be able to debug native threads properly. Instead, the debugger will only 203be able to put breakpoints on the main thread, completely ignoring the 204execution of other ones. 205 206The root of the problem is complex, but is essentially due to a very unfortunate 207bug in the platform, which was only discovered lately. 208 209The gdbserver binary that comes with this NDK has special code to detect this 210condition at runtime and adapt its behaviour automatically (in other words, 211you don't have anything special to do when building your code). 212 213What this means in practical terms are: 214 215- If you are on Android 2.3, or a prior platform release which has had the 216 platform bug-fix back-ported to it, you will be able to debug native 217 threads automatically. 218 219- If you are not, you will only be able to debug the main thread 220 (as in previous NDK releases). You will also see the following message 221 when launching ndk-gdb (just before the gdb prompt): 222 223 Thread debugging is unsupported on this Android platform! 224 225> If you place a breakpoint on a function executed on a non-main thread, the 226 program will exit with the following message in GDB: 227 228 Program terminated with signal SIGTRAP, Trace/breakpoint trap. 229 The program no longer exists. 230