1 page.title=Debugging Tasks 2 @jd:body 3 4 <div id="qv-wrapper"> 5 <div id="qv"> 6 <h2>In this document</h2> 7 <ol> 8 <li><a href="#tools">Tools</a></li> 9 <li><a href="#additionaldebugging">Debug with Dev Tools</a></li> 10 <li><a href="#DebuggingWebPages">Debugging Web Pages</a></li> 11 <li><a href="#toptips">Top Debugging Tips</a></li> 12 <li><a href="#ide-debug-port">Configuring Your IDE to Attach to the Debugging Port</a></li> 13 </ol> 14 </div> 15 </div> 16 17 <p>This document offers some helpful guidance to debugging applications on Android. 18 19 20 <h2 id="tools">Tools</h2> 21 22 <p>The Android SDK includes a set of tools to help you debug and profile 23 your applications. Here are some tools that you'll use most often:</p> 24 25 <dl> 26 <dt><strong><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge 27 (ADB)</a></strong></dt> 28 <dd>Provides various device management capabilities, including 29 moving and syncing files to the emulator, forwarding ports, and running a UNIX 30 shell on the emulator.</dd> 31 <dt><strong><a href="{@docRoot}guide/developing/tools/ddms.html">Dalvik Debug Monitor Server 32 (DDMS)</a></strong></dt> 33 <dd>A graphical program that 34 supports port forwarding (so you can set up breakpoints in your code in your 35 IDE), screen captures on the emulator, thread and stack information, 36 and many other features. You can also run logcat to retrieve your Log messages.</dd> 37 </dd> 38 <dt><strong><a href="{@docRoot}guide/developing/tools/traceview.html">Traceview</a></strong></dt> 39 <dd>A graphical viewer that displays trace file data for method calls and times saved by 40 your application, which can help you profile the performance of your application.</dd> 41 <dt><strong><a href="{@docRoot}guide/developing/tools/ddms.html#logcat">logcat</a></strong></dt> 42 <dd>Dumps a log of system 43 messages. The messages include a stack trace when the emulator throws an error, 44 as well as {@link android.util.Log} messages you've written from your application. To run 45 logcat, execute <code>adb logcat</code> or, from DDMS, select <strong>Device > Run 46 logcat</strong>. 47 <p>{@link android.util.Log} is a logging 48 class you can use to print out messages to the logcat. You can read messages 49 in real time if you run logcat on DDMS (covered next). Common logging methods include: 50 {@link android.util.Log#v(String,String)} (verbose), {@link 51 android.util.Log#d(String,String)} (debug), {@link android.util.Log#i(String,String)} 52 (information), {@link android.util.Log#w(String,String)} (warning) and {@link 53 android.util.Log#e(String,String)} (error). For example:</p> 54 <pre class="no-pretty-print"> 55 Log.i("MyActivity", "MyClass.getView() — get item number " + position); 56 </pre> 57 <p>The logcat will then output something like:</p> 58 <pre class="no-pretty-print"> 59 I/MyActivity( 1557): MyClass.getView() — get item number 1 60 </pre> 61 <p>Logcat is also the place to look when debugging a web page in the Android Browser app. See 62 <a href="#DebuggingWebPages">Debugging Web Pages</a> below.</p> 63 </dl> 64 65 <p>For more information about all the development tools provided with the Android SDK, see the <a 66 href="{@docRoot}guide/developing/tools/index.html">Tools</a> document.</p> 67 68 <p>In addition to the above tools, you may also find the following useful for debugging: 69 <dl> 70 <dt><a href="{@docRoot}guide/developing/eclipse-adt.html"><strong>Eclipse ADT 71 plugin</strong></a></dt> 72 <dd>The ADT Plugin for Eclipse integrates a number of the Android development tools (ADB, DDMS, 73 logcat output, and other functionality), so that you won't work with them directly but will utilize 74 them through the Eclipse IDE.</dd> 75 <dt><strong>Developer Settings in the Dev Tools app</strong></dt> 76 <dd>The Dev Tools application included in the emulator system image exposes several settings 77 that provide useful information such as CPU usage and frame rate. See <a 78 href="#additionaldebugging">Debugging and Testing with Dev Tools</a> below.</dd> 79 </dl> 80 81 <h2 id="additionaldebugging">Debugging and Testing with Dev Tools</h2> 82 83 <p>With the Dev Tools application, you can enable a number of settings on your device that will 84 make it easier to test and debug your applications.</p> 85 86 <p>The Dev Tools application is installed by default 87 on all system images included with the SDK, so you can use it with the Android Emulator. If you'd 88 like to install the Dev Tools application on a real development device, you can copy the 89 application from your emulator and then install it on your device using ADB. To copy the 90 application from a running emulator, execute: 91 </p> 92 <pre> 93 adb -e pull /system/app/Development.apk ./Development.apk 94 </pre> 95 <p>This copies the .apk file into the current directory. Then install it on your connected device 96 with:</p> 97 <pre> 98 adb -d install Development.apk 99 </pre> 100 101 <p>To get started, launch the Dev Tools application and 102 select Development Settings. This will open the Development Settings page with the 103 following options (among others):</p> 104 105 <dl> 106 <dt><strong>Debug app</strong></dt> 107 <dd>Lets you select the application to debug. You do not need to set this to attach a debugger, 108 but setting this value has two effects: 109 <ul> 110 <li>It will prevent Android from throwing an error if you pause on 111 a breakpoint for a long time while debugging.</li> 112 <li>It will enable you to select the <em>Wait for Debugger</em> option 113 to pause application startup until your debugger attaches (described 114 next). </li> 115 </ul> 116 </dd> 117 <dt><strong>Wait for debugger</strong></dt> 118 <dd>Blocks the selected application from loading until a debugger attaches. This 119 way you can set a breakpoint in onCreate(), which is important to debug 120 the startup process of an Activity. When you change this option, any 121 currently running instances of the selected application will be killed. 122 In order to check this box, you must have selected a debug application 123 as described in the previous option. You can do the same thing by adding 124 {@link android.os.Debug#waitForDebugger()} to your code.</dd> 125 <dt><strong>Show screen updates</strong></dt> 126 <dd>Flashes a momentary pink rectangle on any screen sections that are being 127 redrawn. This is very useful for discovering unnecessary screen drawing.</dd> 128 <dt><strong>Immediately destroy activities</strong></dt> 129 <dd>Tells the 130 system to destroy an activity as soon as it is stopped (as if Android had to 131 reclaim memory). This is very useful for testing the {@link android.app.Activity#onSaveInstanceState} 132 / {@link android.app.Activity#onCreate(android.os.Bundle)} code path, which would 133 otherwise be difficult to force. Choosing this option will probably reveal 134 a number of problems in your application due to not saving state.</dd> 135 <dt><strong>Show CPU usage</strong></dt> 136 <dd>Displays CPU meters at the 137 top of the screen, showing how much the CPU is being used. The top red bar 138 shows overall CPU usage, and the green bar underneath it shows the CPU time 139 spent in compositing the screen. <em>Note: You cannot turn this feature off 140 once it is on, without restarting the emulator.</em> </dd> 141 <dt><strong>Show background</strong></dt> 142 <dd>Displays a background pattern 143 when no activity screens are visible. This typically does not happen, but 144 can happen during debugging.</dd> 145 </dl> 146 147 <p>These settings will be remembered across emulator restarts.</p> 148 149 <h2 id="DebuggingWebPages">Debugging Web Pages</h2> 150 151 <p>If you're developing a web application for Android devices, you can debug your JavaScript in the 152 Android Browser using the Console APIs, which will output messages to logcat. If you're familiar 153 debugging web pages with Firefox's FireBug or WebKit's Web Inspector, then you're probably familiar 154 with the Console APIs. The Android Browser (and the {@link android.webkit.WebChromeClient}) supports 155 most of the same APIs.</p> 156 157 <p>When you call a function from the Console APIs (in the DOM's {@code window.console} object), 158 you will see the output in logcat as a warning. For example, if your web page 159 executes the following JavaScript:</p> 160 <pre class="no-pretty-print"> 161 console.log("Hello World"); 162 </pre> 163 <p>Then the logcat output from the Android Browser will look like this:</p> 164 <pre class="no-pretty-print"> 165 W/browser ( 202): Console: Hello World http://www.example.com/hello.html :82 166 </pre> 167 168 <p>All Console messages from the Android Browser are tagged with the name "browser" on Android 169 platforms running API Level 7 or higher. On platforms running API Level 6 or lower, Browser 170 messages are tagged with the name "WebCore". The Android Browser also formats console messages 171 with the log message 172 preceded by "Console:" and then followed by the address and line number where the 173 message occurred. (The format for the address and line number will appear different from the example 174 above on platforms running API Level 6 or lower.)</p> 175 176 <p>The Android Browser (and {@link android.webkit.WebChromeClient}) does not implement all of the 177 Console APIs provided by Firefox or other WebKit-based browsers. Primarily, you need to depend 178 on the basic text logging functions:</p> 179 <ul> 180 <li>{@code console.log(String)}</li> 181 <li>{@code console.info(String)}</li> 182 <li>{@code console.warn(String)}</li> 183 <li>{@code console.error(String)}</li> 184 </ul> 185 <p>Although the Android Browser may not fully implement other Console functions, they will not raise 186 run-time errors, but may not behave the same as they do on other desktop browsers.</p> 187 188 <p>If you've implemented a custom {@link android.webkit.WebView} in your application, then in order 189 to receive messages that are sent through the Console APIs, you must provide a {@link 190 android.webkit.WebChromeClient} that implements the {@link 191 android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback 192 method. For example, assuming that the {@code myWebView} field references the {@link 193 android.webkit.WebView} in your application, you can log debug messages like this:</p> 194 <pre> 195 myWebView.setWebChromeClient(new WebChromeClient() { 196 public void onConsoleMessage(String message, int lineNumber, String sourceID) { 197 Log.d("MyApplication", message + " -- From line " + lineNumber + " of " + sourceID); 198 } 199 }); 200 </pre> 201 <p>The {@link android.webkit.WebChromeClient#onConsoleMessage(String,int,String) 202 onConsoleMessage()} method will be called each time one of the Console methods is called from 203 within your {@link android.webkit.WebView}.</p> 204 <p>When the "Hello World" log is executed through your {@link android.webkit.WebView}, it will 205 now look like this:</p> 206 <pre class="no-pretty-print"> 207 D/MyApplication ( 430): Hello World -- From line 82 of http://www.example.com/hello.html 208 </pre> 209 210 <p class="note"><strong>Note:</strong> The {@link 211 android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback 212 method was added with API Level 7. If you are using a custom {@link 213 android.webkit.WebView} on a platform running API Level 6 or lower, then your Console messages will 214 automatically be sent to logcat with the "WebCore" logging tag.</p> 215 216 217 218 219 <h2 id="toptips">Top Debugging Tips</h2> 220 221 <dl> 222 <dt><strong>Dump the stack trace</strong></dt> 223 <dd>To obtain a stack dump from emulator, you can log 224 in with <code>adb shell</code>, use "ps" to find the process you 225 want, and then "kill -3 ". The stack trace appears in the log file. 226 </dd> 227 228 <dt><strong>Display useful info on the emulator screen</strong></dt> 229 <dd>The device can display useful information such as CPU usage or highlights 230 around redrawn areas. Turn these features on and off in the developer settings 231 window as described in <a href="#additionaldebugging">Setting debug and test 232 configurations on the emulator</a>. 233 </dd> 234 235 <dt><strong>Get system state information from the emulator (dumpstate)</strong></dt> 236 <dd>You can access dumpstate information from the Dalvik Debug Monitor Service 237 tool. See <a href="{@docRoot}guide/developing/tools/adb.html#dumpsys">dumpsys and 238 dumpstate</a> on the adb topic page.</dd> 239 240 <dt><strong>Get application state information from the emulator (dumpsys)</strong></dt> 241 <dd>You can access dumpsys information from the Dalvik Debug Monitor Service 242 tool. See <a href="{@docRoot}guide/developing/tools/adb.html#dumpsys">dumpsys and 243 dumpstate</a> on the adb topic page.</dd> 244 245 <dt><strong>Get wireless connectivity information</strong></dt> 246 <dd>You can get information about wireless connectivity using the Dalvik Debug 247 Monitor Service tool. From the <strong>Device</strong> menu, select "Dump 248 radio state".</dd> 249 250 <dt><strong>Log trace data</strong></dt> 251 <dd>You can log method calls and other tracing data in an activity by calling 252 {@link android.os.Debug#startMethodTracing(String) startMethodTracing()}. See <a 253 href="{@docRoot}guide/developing/tools/traceview.html">Running the Traceview Debugging 254 Program</a> for details. </dd> 255 256 <dt><strong>Log radio data</strong></dt> 257 <dd>By default, radio information is not logged to the system (it is a lot of 258 data). However, you can enable radio logging using the following commands: 259 260 <pre class="no-pretty-print"> 261 adb shell 262 logcat -b radio 263 </pre> 264 </dd> 265 266 <dt><strong>Capture screenshots</strong></dt> 267 <dd>The Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator. Select 268 <strong>Device > Screen capture</strong>.</dd> 269 270 <dt><strong>Use debugging helper classes</strong></dt> 271 <dd>Android provides debug helper classes such as {@link android.util.Log 272 util.Log} and {@link android.os.Debug} for your convenience. </dd> 273 </dl> 274 275 <p>Also see the <a href="{@docRoot}resources/faq/troubleshooting.html">Troubleshooting</a> document 276 for answers to some common developing and debugging issues.</p> 277 278 279 <h2 id="ide-debug-port">Configuring Your IDE to Attach to the Debugging Port</h2> 280 281 <p>DDMS will assign a specific debugging port to every virtual machine that it 282 finds on the emulator. You must either attach your IDE to that 283 port (listed on the Info tab for that VM), or you can use a default port 8700 284 to connect to whatever application is currently selected on the list of discovered 285 virtual machines.</p> 286 <p>Your IDE should attach to your application running on the emulator, showing you 287 its threads and allowing you to suspend them, inspect their state, and set breakpoints. 288 If you selected "Wait for debugger" in the Development settings panel 289 the application will run when Eclipse connects, so you will need to set any breakpoints 290 you want before connecting.</p> 291 <p>Changing either the application being debugged or the "Wait for debugger" 292 option causes the system to kill the selected application if it is currently 293 running. You can use this to kill your application if it is in a bad state 294 by simply going to the settings and toggling the checkbox.</p> 295
