| page.title=Debugging Tasks |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#tools">Tools</a></li> |
| <li><a href="#additionaldebugging">Debug with Dev Tools</a></li> |
| <li><a href="#DebuggingWebPages">Debugging Web Pages</a></li> |
| <li><a href="#toptips">Top Debugging Tips</a></li> |
| <li><a href="#ide-debug-port">Configuring Your IDE to Attach to the Debugging Port</a></li> |
| </ol> |
| </div> |
| </div> |
| |
| <p>This document offers some helpful guidance to debugging applications on Android. |
| |
| |
| <h2 id="tools">Tools</h2> |
| |
| <p>The Android SDK includes a set of tools to help you debug and profile |
| your applications. Here are some tools that you'll use most often:</p> |
| |
| <dl> |
| <dt><strong><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge |
| (ADB)</a></strong></dt> |
| <dd>Provides various device management capabilities, including |
| moving and syncing files to the emulator, forwarding ports, and running a UNIX |
| shell on the emulator.</dd> |
| <dt><strong><a href="{@docRoot}guide/developing/tools/ddms.html">Dalvik Debug Monitor Server |
| (DDMS)</a></strong></dt> |
| <dd>A graphical program that |
| supports port forwarding (so you can set up breakpoints in your code in your |
| IDE), screen captures on the emulator, thread and stack information, |
| and many other features. You can also run logcat to retrieve your Log messages.</dd> |
| </dd> |
| <dt><strong><a href="{@docRoot}guide/developing/tools/traceview.html">Traceview</a></strong></dt> |
| <dd>A graphical viewer that displays trace file data for method calls and times saved by |
| your application, which can help you profile the performance of your application.</dd> |
| <dt><strong><a href="{@docRoot}guide/developing/tools/ddms.html#logcat">logcat</a></strong></dt> |
| <dd>Dumps a log of system |
| messages. The messages include a stack trace when the device throws an error, |
| as well as {@link android.util.Log} messages you've written from your application. To run |
| logcat, execute <code>adb logcat</code> from your Android SDK {@code platform-tools/} |
| directory or, from DDMS, select <strong>Device > Run |
| logcat</strong>. When using the <a href="{@docRoot}sdk/eclipse-adt.html">ADT plugin for |
| Eclipse</a>, you can also view logcat messages by opening the Logcat view, available from |
| <strong>Window > Show View > Other > Android > Logcat</strong>. |
| <p>{@link android.util.Log} is a logging |
| class you can use to print out messages to the logcat. You can read messages |
| in real time if you run logcat on DDMS (covered next). Common logging methods include: |
| {@link android.util.Log#v(String,String)} (verbose), {@link |
| android.util.Log#d(String,String)} (debug), {@link android.util.Log#i(String,String)} |
| (information), {@link android.util.Log#w(String,String)} (warning) and {@link |
| android.util.Log#e(String,String)} (error). For example:</p> |
| <pre class="no-pretty-print"> |
| Log.i("MyActivity", "MyClass.getView() — get item number " + position); |
| </pre> |
| <p>The logcat will then output something like:</p> |
| <pre class="no-pretty-print"> |
| I/MyActivity( 1557): MyClass.getView() — get item number 1 |
| </pre> |
| <p>Logcat is also the place to look when debugging a web page in the Android Browser app. See |
| <a href="#DebuggingWebPages">Debugging Web Pages</a> below.</p> |
| </dl> |
| |
| <p>For more information about all the development tools provided with the Android SDK, see the <a |
| href="{@docRoot}guide/developing/tools/index.html">Tools</a> document.</p> |
| |
| <p>In addition to the above tools, you may also find the following useful for debugging: |
| <dl> |
| <dt><a href="{@docRoot}guide/developing/eclipse-adt.html"><strong>Eclipse ADT |
| plugin</strong></a></dt> |
| <dd>The ADT Plugin for Eclipse integrates a number of the Android development tools (ADB, DDMS, |
| logcat output, and other functionality), so that you won't work with them directly but will utilize |
| them through the Eclipse IDE.</dd> |
| <dt><strong>Developer Settings in the Dev Tools app</strong></dt> |
| <dd>The Dev Tools application included in the emulator system image exposes several settings |
| that provide useful information such as CPU usage and frame rate. See <a |
| href="#additionaldebugging">Debugging and Testing with Dev Tools</a> below.</dd> |
| </dl> |
| |
| <h2 id="additionaldebugging">Debugging and Testing with Dev Tools</h2> |
| |
| <p>With the Dev Tools application, you can enable a number of settings on your device that will |
| make it easier to test and debug your applications.</p> |
| |
| <p>The Dev Tools application is installed by default |
| on all system images included with the SDK, so you can use it with the Android Emulator. If you'd |
| like to install the Dev Tools application on a real development device, you can copy the |
| application from your emulator and then install it on your device using ADB. To copy the |
| application from a running emulator, execute: |
| </p> |
| <pre> |
| adb -e pull /system/app/Development.apk ./Development.apk |
| </pre> |
| <p>This copies the .apk file into the current directory. Then install it on your connected device |
| with:</p> |
| <pre> |
| adb -d install Development.apk |
| </pre> |
| |
| <p>To get started, launch the Dev Tools application and |
| select Development Settings. This will open the Development Settings page with the |
| following options (among others):</p> |
| |
| <dl> |
| <dt><strong>Debug app</strong></dt> |
| <dd>Lets you select the application to debug. You do not need to set this to attach a debugger, |
| but setting this value has two effects: |
| <ul> |
| <li>It will prevent Android from throwing an error if you pause on |
| a breakpoint for a long time while debugging.</li> |
| <li>It will enable you to select the <em>Wait for Debugger</em> option |
| to pause application startup until your debugger attaches (described |
| next). </li> |
| </ul> |
| </dd> |
| <dt><strong>Wait for debugger</strong></dt> |
| <dd>Blocks the selected application from loading until a debugger attaches. This |
| way you can set a breakpoint in onCreate(), which is important to debug |
| the startup process of an Activity. When you change this option, any |
| currently running instances of the selected application will be killed. |
| In order to check this box, you must have selected a debug application |
| as described in the previous option. You can do the same thing by adding |
| {@link android.os.Debug#waitForDebugger()} to your code.</dd> |
| <dt><strong>Show screen updates</strong></dt> |
| <dd>Flashes a momentary pink rectangle on any screen sections that are being |
| redrawn. This is very useful for discovering unnecessary screen drawing.</dd> |
| <dt><strong>Immediately destroy activities</strong></dt> |
| <dd>Tells the |
| system to destroy an activity as soon as it is stopped (as if Android had to |
| reclaim memory). This is very useful for testing the {@link android.app.Activity#onSaveInstanceState} |
| / {@link android.app.Activity#onCreate(android.os.Bundle)} code path, which would |
| otherwise be difficult to force. Choosing this option will probably reveal |
| a number of problems in your application due to not saving state.</dd> |
| <dt><strong>Show CPU usage</strong></dt> |
| <dd>Displays CPU meters at the |
| top of the screen, showing how much the CPU is being used. The top red bar |
| shows overall CPU usage, and the green bar underneath it shows the CPU time |
| spent in compositing the screen. <em>Note: You cannot turn this feature off |
| once it is on, without restarting the emulator.</em> </dd> |
| <dt><strong>Show background</strong></dt> |
| <dd>Displays a background pattern |
| when no activity screens are visible. This typically does not happen, but |
| can happen during debugging.</dd> |
| </dl> |
| |
| <p>These settings will be remembered across emulator restarts.</p> |
| |
| <h2 id="DebuggingWebPages">Debugging Web Pages</h2> |
| |
| <p>See the <a href="{@docRoot}guide/webapps/debugging.html">Debugging Web Apps</a> document.</p> |
| |
| |
| <h2 id="toptips">Top Debugging Tips</h2> |
| |
| <dl> |
| <dt><strong>Dump the stack trace</strong></dt> |
| <dd>To obtain a stack dump from emulator, you can log |
| in with <code>adb shell</code>, use "ps" to find the process you |
| want, and then "kill -3 ". The stack trace appears in the log file. |
| </dd> |
| |
| <dt><strong>Display useful info on the emulator screen</strong></dt> |
| <dd>The device can display useful information such as CPU usage or highlights |
| around redrawn areas. Turn these features on and off in the developer settings |
| window as described in <a href="#additionaldebugging">Setting debug and test |
| configurations on the emulator</a>. |
| </dd> |
| |
| <dt><strong>Get system state information from the emulator (dumpstate)</strong></dt> |
| <dd>You can access dumpstate information from the Dalvik Debug Monitor Service |
| tool. See <a href="{@docRoot}guide/developing/tools/adb.html#dumpsys">dumpsys and |
| dumpstate</a> on the adb topic page.</dd> |
| |
| <dt><strong>Get application state information from the emulator (dumpsys)</strong></dt> |
| <dd>You can access dumpsys information from the Dalvik Debug Monitor Service |
| tool. See <a href="{@docRoot}guide/developing/tools/adb.html#dumpsys">dumpsys and |
| dumpstate</a> on the adb topic page.</dd> |
| |
| <dt><strong>Get wireless connectivity information</strong></dt> |
| <dd>You can get information about wireless connectivity using the Dalvik Debug |
| Monitor Service tool. From the <strong>Device</strong> menu, select "Dump |
| radio state".</dd> |
| |
| <dt><strong>Log trace data</strong></dt> |
| <dd>You can log method calls and other tracing data in an activity by calling |
| {@link android.os.Debug#startMethodTracing(String) startMethodTracing()}. See <a |
| href="{@docRoot}guide/developing/tools/traceview.html">Running the Traceview Debugging |
| Program</a> for details. </dd> |
| |
| <dt><strong>Log radio data</strong></dt> |
| <dd>By default, radio information is not logged to the system (it is a lot of |
| data). However, you can enable radio logging using the following commands: |
| |
| <pre class="no-pretty-print"> |
| adb shell |
| logcat -b radio |
| </pre> |
| </dd> |
| |
| <dt><strong>Capture screenshots</strong></dt> |
| <dd>The Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator. Select |
| <strong>Device > Screen capture</strong>.</dd> |
| |
| <dt><strong>Use debugging helper classes</strong></dt> |
| <dd>Android provides debug helper classes such as {@link android.util.Log |
| util.Log} and {@link android.os.Debug} for your convenience. </dd> |
| </dl> |
| |
| <p>Also see the <a href="{@docRoot}resources/faq/troubleshooting.html">Troubleshooting</a> document |
| for answers to some common developing and debugging issues.</p> |
| |
| |
| <h2 id="ide-debug-port">Configuring Your IDE to Attach to the Debugging Port</h2> |
| |
| <p>DDMS will assign a specific debugging port to every virtual machine that it |
| finds on the emulator. You must either attach your IDE to that |
| port (listed on the Info tab for that VM), or you can use a default port 8700 |
| to connect to whatever application is currently selected on the list of discovered |
| virtual machines.</p> |
| <p>Your IDE should attach to your application running on the emulator, showing you |
| its threads and allowing you to suspend them, inspect their state, and set breakpoints. |
| If you selected "Wait for debugger" in the Development settings panel |
| the application will run when Eclipse connects, so you will need to set any breakpoints |
| you want before connecting.</p> |
| <p>Changing either the application being debugged or the "Wait for debugger" |
| option causes the system to kill the selected application if it is currently |
| running. You can use this to kill your application if it is in a bad state |
| by simply going to the settings and toggling the checkbox.</p> |