1page.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
118applications:</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
123in with <code>adb shell</code>, use <code>ps</code> to find the process you
124want, 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
129around redrawn areas. Turn these features on and off in the developer settings
130window as described in <a href="{@docRoot}tools/debugging/debugging-devtools.html">
131Debugging 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
137dumpstate</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.
141From the <strong>Device</strong> menu, select <strong>Dump
142radio 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
147href="{@docRoot}tools/debugging/debugging-tracing.html">Profiling with Traceview and
148dmtracedump</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
152data). However, you can enable radio logging using the following commands:
153
154<pre class="no-pretty-print">
155adb shell
156logcat -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>
170The debugger and garbage collector are currently loosely integrated. The VM guarantees that any
171object the debugger is aware of is not garbage collected until after the debugger disconnects.
172This can result in a buildup of objects over time while the debugger is connected. For example,
173if the debugger sees a running thread, the associated {@link java.lang.Thread} object is not
174garbage collected even after the thread terminates.
175</dd>
176
177</dl>
178
179
180
181
182
183
184
185
186