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