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