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