1 page.title=Debugging 2 @jd:body 3 4 5 <div id="qv-wrapper"> 6 <div id="qv"> 7 <h2>In this document</h2> 8 9 <ol> 10 <li><a href="#stack">Debugging Environment</a></li> 11 12 <li><a href="#addltools">Additional Debugging Tools</a></li> 13 14 <li><a href="#tips">Debugging Tips</a></li> 15 </ol> 16 </div> 17 </div> 18 19 <p>The Android SDK provides most of the tools that you need to debug your applications. You need 20 a JDWP-compliant debugger if you want to be able to do things such as step through code, 21 view variable values, and pause execution of an application. If you are using Eclipse, a 22 JDWP-compliant debugger is already included and there is no setup required. If you are using 23 another IDE, you can use the debugger that comes with it and attach the debugger to a special 24 port so it can communicate with the application VMs on your devices. The main components that 25 comprise a typical Android debugging environment are:</p> 26 27 <dl> 28 <dt><a href="{@docRoot}guide/developing/tools/adb.html"><strong>adb</strong></a></dt> 29 30 <dd><code>adb</code> acts as a middleman between a device and your development system. It provides various 31 device management capabilities, including moving and syncing files to the emulator, running a 32 UNIX shell on the device or emulator, and providing a general means to communicate with 33 connected emulators and devices.</dd> 34 35 <dt><a href="{@docRoot}guide/developing/debugging/ddms.html"><strong>Dalvik Debug Monitor 36 Server</strong></a></dt> 37 38 <dd>DDMS is a graphical program that communicates with your devices through <code>adb</code>. DDMS can 39 capture screenshots, gather thread and stack information, spoof incoming calls and SMS 40 messages, and has many other features.</dd> 41 42 <dt><strong><a href="{@docRoot}guide/developing/device.html">Device</a> or 43 <a href="{@docRoot}guide/developing/devices/index.html">Android Virtual Device</a></strong></dt> 44 45 <dd>Your application must run in a device or in an AVD so that it can be debugged. An <code>adb</code> device 46 daemon runs on the device or emulator and provides a means for the <code>adb</code> host daemon to 47 communicate with the device or emulator.</dd> 48 49 <dt><strong>JDWP debugger</strong></dt> 50 51 <dd>The Dalvik VM (Virtual Machine) supports the JDWP protocol to allow debuggers to attach to 52 a VM. Each application runs in a VM and exposes a unique port that you can attach a debugger to 53 via DDMS. If you want to debug multiple applications, attaching to each port might become 54 tedious, so DDMS provides a port forwarding feature that can forward a specific VM's debugging 55 port to port 8700. You can switch freely from application to application by highlighting it in the 56 Devices tab of DDMS. DDMS forwards the appropriate port to port 8700. Most modern Java IDEs include a JDWP debugger, 57 or you can use a command line debugger such as <a href="http://download.oracle.com/javase/6/docs/technotes/tools/"> 58 <code>jdb</code></a>.</dd> 59 </dl> 60 61 <h2>Debugging Environment</h2> 62 63 <p>Figure 1 shows how the various debugging tools work together in a typical 64 debugging environment.</p> 65 <img src="{@docRoot}images/debugging.png" 66 alt="Debugging workflow" /> 67 <p class="img-caption><strong>Figure 1. </strong> Debugging Workflow</p> 68 69 <p>On your emulator or device, each application runs in its own instance of a Dalvik VM. The <code>adb</code> 70 device daemon allows communication with the VMs from an outside party.</p> 71 72 <p>On your development machine, the <code>adb</code> host daemon communicates with the <code>adb</code> device daemon and 73 allows tools such as DDMS to communicate with the device or emulator. The <code>adb</code> host daemon also 74 allows you to access shell commands on the device as well as providing capabilities such as 75 application installation and file transferring.</p> 76 77 <p>Each application VM on the device or emulator exposes a debugging port that you can attach to 78 via DDMS. DDMS can forward any of these ports to a static debugging port (typically port 8700) by 79 selecting the application that you want to debug in the DDMS user interface. A JDWP debugger can 80 attach to this static debugging port and debug all the applications that are running on the 81 device or emulator without having to attach to multiple ports.</p> 82 83 <p>If you are using Eclipse, much of these interconnections are hidden from you. DDMS, <code>adb</code>, and a 84 JDWP debugger are all setup for you and you can access them through the Debug and DDMS 85 perspectives in Eclipse. If you are developing in a non-Eclipse environment, you have to invoke 86 these tools manually.</p> 87 88 <h2 id="addltools">Additional Debugging Tools</h2> 89 90 <p>In addition to the main debugging tools, the Android SDK provides additional tools to help you 91 debug and profile your applications:</p> 92 93 <dl> 94 <dt><strong><a href="{@docRoot}guide/developing/debugging/debugging-ui.html">Heirarchy Viewer 95 and layoutopt</a></strong></dt> 96 97 <dd>Graphical programs that let you debug and profile user interfaces.</dd> 98 99 <dt><strong><a href= 100 "{@docRoot}guide/developing/debugging/debugging-tracing.html">Traceview</a></strong></dt> 101 102 <dd>A graphical viewer that displays trace file data for method calls and times saved by your 103 application, which can help you profile the performance of your application.</dd> 104 105 <dt><strong><a href="{@docRoot}guide/developing/debugging/debugging-devtools.html">Dev Tools 106 Android application</a></strong></dt> 107 108 <dd>The Dev Tools application included in the emulator system image exposes several settings 109 that provide useful information such as CPU usage and frame rate. You can also transfer the 110 application to a hardware device.</dd> 111 </dl> 112 113 114 <h2 id="tips">Debugging Tips</h2> 115 116 <p>While debugging, keep these helpful tips in mind to help you figure out common problems with your 117 applications:</p> 118 119 <dl> 120 <dt><strong>Dump the stack trace</strong></dt> 121 <dd>To obtain a stack dump from emulator, you can log 122 in with <code>adb shell</code>, use <code>ps</code> to find the process you 123 want, and then <code>kill -3</code>. The stack trace appears in the log file. 124 </dd> 125 126 <dt><strong>Display useful info on the emulator screen</strong></dt> 127 <dd>The device can display useful information such as CPU usage or highlights 128 around redrawn areas. Turn these features on and off in the developer settings 129 window as described in <a href="{@docRoot}guide/developing/debugging/debugging-devtools.html"> 130 Debugging with the Dev Tools App</a>. 131 </dd> 132 133 <dt><strong>Get application and system state information from the emulator</strong></dt> 134 <dd>You can access dumpstate information from the <code>adb shell</code> commands. See 135 <a href="{@docRoot}guide/developing/tools/adb.html#dumpsys">dumpsys and 136 dumpstate</a> on the adb topic page.</dd> 137 138 139 140 <dt><strong>Get wireless connectivity information</strong></dt> 141 <dd>You can get information about wireless connectivity using DDMS. 142 From the <strong>Device</strong> menu, select <strong>Dump 143 radio state</strong>.</dd> 144 145 <dt><strong>Log trace data</strong></dt> 146 <dd>You can log method calls and other tracing data in an activity by calling 147 {@link android.os.Debug#startMethodTracing(String) startMethodTracing()}. See <a 148 href="{@docRoot}guide/developing/debugging/debugging-tracing.html">Profiling with Traceview and 149 dmtracedump</a> for details. </dd> 150 151 <dt><strong>Log radio data</strong></dt> 152 <dd>By default, radio information is not logged to the system (it is a lot of 153 data). However, you can enable radio logging using the following commands: 154 155 <pre class="no-pretty-print"> 156 adb shell 157 logcat -b radio 158 </pre> 159 </dd> 160 161 <dt><strong>Capture screenshots</strong></dt> 162 <dd>The Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator. Select 163 <strong>Device > Screen capture</strong>.</dd> 164 165 <dt><strong>Use debugging helper classes</strong></dt> 166 <dd>Android provides debug helper classes such as {@link android.util.Log 167 util.Log} and {@link android.os.Debug} for your convenience. </dd> 168 169 <dt><strong>Garbage collection</strong></dt> 170 <dd> 171 The debugger and garbage collector are currently loosely integrated. The VM guarantees that any 172 object the debugger is aware of is not garbage collected until after the debugger disconnects. 173 This can result in a buildup of objects over time while the debugger is connected. For example, 174 if the debugger sees a running thread, the associated {@link java.lang.Thread} object is not 175 garbage collected even after the thread terminates. 176 </dd> 177 178 </dl> 179 180 <p>See the <a href="{@docRoot}resources/faq/troubleshooting.html">Troubleshooting</a> document 181 for answers to some common developing and debugging issues.</p> 182 183 184 185 186 187 188 189
