233 lines
12 KiB
Plaintext
233 lines
12 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 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>
|