208 lines
11 KiB
Plaintext
208 lines
11 KiB
Plaintext
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 and Test Settings</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 fairly extensive set of tools to help you debug your programs: </p>
|
|
<ul>
|
|
<li><a href="{@docRoot}guide/developing/tools/ddms.html"><strong>DDMS</strong></a> - 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.
|
|
See the linked topic for more information. </li>
|
|
<li><strong><a href="{@docRoot}guide/developing/tools/ddms.html#logcat">logcat</a></strong> - Dumps a log of system
|
|
messages. The messages include a stack trace when the emulator throws an error,
|
|
as well as Log messages. To run logcat, see the linked topic.
|
|
|
|
<pre>...
|
|
I/MemoryDealer( 763): MemoryDealer (this=0x54bda0): Creating 2621440 bytes heap at 0x438db000
|
|
<span style="background-color:#CCCCCC; border-bottom:medium">I/Logger( 1858): getView() requesting item number 0
|
|
I/Logger( 1858): getView() requesting item number 1
|
|
I/Logger( 1858): getView() requesting item number 2</span>
|
|
D/ActivityManager( 763): Stopping: HistoryRecord{409dbb20 com.android.home.AllApps}
|
|
...</pre>
|
|
|
|
</li>
|
|
<li><p><strong>{@link android.util.Log Android Log}</strong>- A logging
|
|
class to print out messages to a log file on the emulator. You can read messages
|
|
in real time if you run logcat on DDMS (covered next). Add a few logging
|
|
method calls to your code.</p>
|
|
<p>To use the <code>Log</code> class, you just call <code>Log.v()</code>
|
|
(verbose), <code>Log.d()</code> (debug), <code>Log.i()</code> (information),
|
|
<code>Log.w()</code> (warning) or <code>Log.e</code> (error) depending
|
|
on the importance you wish to assign the log message.</p>
|
|
<code>Log.i("MyActivity", "MyClass.getView()
|
|
— Requesting item number " + position)</code>
|
|
<p>You can use logcat to read these messages</p></li>
|
|
<li><strong><a href="{@docRoot}guide/developing/tools/traceview.html">Traceview</a> </strong>- Android can save
|
|
a log of method calls and times to a logging file that you can view in a
|
|
graphical reader called Traceview. See the linked topic for more information. </li>
|
|
</ul>
|
|
<ul>
|
|
<li><a href="{@docRoot}guide/developing/eclipse-adt.html"><strong>Eclipse plugin</strong></a> - The ADT Plugin
|
|
for Eclipse integrates a number of these tools (ADB, DDMS, logcat output,
|
|
and other functionality). See the linked topic for more information. </li>
|
|
<li><strong>Debug and Test Device Settings</strong> - Android exposes several settings
|
|
that expose useful information such as CPU usage and frame rate. See <a href="#additionaldebugging">Debug
|
|
and Test Settings on the Emulator</a> below. </li>
|
|
</ul>
|
|
<p>Also, see the <a href="{@docRoot}guide/appendix/faq/troubleshooting.html">Troubleshooting</a> section
|
|
of the doc to figure out why your application isn't appearing on the emulator,
|
|
or why it's not starting. </p>
|
|
|
|
|
|
<h2 id="additionaldebugging">Debug and Test Settings</h2>
|
|
|
|
<p>With the <strong>Dev Tools</strong> application, you can turn on a number of settings that will make it easier to test
|
|
and debug your applications. To get to the development settings page on the emulator, launch the
|
|
<strong>Dev Tools</strong> application and open <strong>Development Settings</strong>.
|
|
This will open the development settings page with the following options (among
|
|
others):</p>
|
|
<ul>
|
|
<li><strong>Debug app</strong> Selects the application that
|
|
will be debugged. 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>
|
|
</li>
|
|
<li><strong>Wait for debugger </strong>
|
|
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. </li>
|
|
<li><strong>Immediately destroy activities</strong> 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.</li>
|
|
<li><strong>Show screen updates</strong>
|
|
Flashes a momentary pink rectangle on any screen sections that are being
|
|
redrawn. This is very useful for discovering unnecessary screen drawing. </li>
|
|
<li><strong>Show CPU usage</strong> 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> </li>
|
|
<li><strong>Show background</strong> Displays a background pattern
|
|
when no activity screens are visible. This typically does not happen, but
|
|
can happen during debugging. </li>
|
|
</ul>
|
|
<p>These settings will be remembered across emulator restarts. </p>
|
|
|
|
<h2 id="toptips">Top Debugging Tips</h2>
|
|
<!--
|
|
<ul>
|
|
<li><a href="#stackdump">Quick stack dump</a></li>
|
|
<li><a href="#displayinfo">Displaying useful info on the emulator screen </a></li>
|
|
<li><a href="#dumpstate">Getting system state information from the emulator (dumpstate)</a></li>
|
|
<li><a href="#dumpsys">Getting application state information from the emulator (dumpsys)</a></li>
|
|
<li><a href="#radioinfo">Getting wireless connectivity information</a></li>
|
|
<li><a href="#loggingdata">Logging Trace Data</a></li>
|
|
<li><a href="#logradio">Logging Radio Data </a></li>
|
|
<li><a href="#adb">Running adb</a></li>
|
|
<li><a href="#screencaps">Getting screen captures from the emulator</a></li>
|
|
<li><a href="#debughelpers">Using debug helper classes</a></li>
|
|
</ul>
|
|
-->
|
|
<dl>
|
|
<dt>Quick stack dump <a name="stackdump" id="stackdump"></a></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>Displaying useful info on the emulator screen<a name="displayinfo" id="displayinfo"></a></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>Getting system state information from the emulator (dumpstate)<a name="dumpstate" id="dumpstate"></a> </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>Getting application state information from the emulator (dumpsys)<a name="dumpsys" id="dumpsys"></a></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>Getting wireless connectivity information <a name="radioinfo" id="radioinfo"></a></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>Logging Trace Data<a name="loggingdata" id="loggingdata"></a></dt>
|
|
<dd>You can log method calls and other tracing data in an activity by calling
|
|
android.os.Debug.startMethodTracing(). See <a
|
|
href="{@docRoot}guide/developing/tools/traceview.html">Running the Traceview Debugging
|
|
Program</a> for details. </dd>
|
|
|
|
<dt>Logging Radio Data<a name="logradio" id="logradio"></a></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>
|
|
adb shell
|
|
logcat -b radio
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt>Running adb<a name="adb" id="adb"></a></dt>
|
|
<dd>Android ships with a tool called adb that provides various capabilities, including
|
|
moving and syncing files to the emulator, forwarding ports, and running a UNIX
|
|
shell on the emulator. See <a href="{@docRoot}guide/developing/tools/adb.html">Using adb</a> for details.</dd>
|
|
|
|
<dt>Getting screen captures from the emulator<a name="screencaps" id="screencaps"></a></dt>
|
|
<dd> Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator.</dd>
|
|
|
|
|
|
<a name="debughelpers"></a>
|
|
|
|
<dt>Using debugging helper classes</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>
|
|
|
|
<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>
|