diff options
Diffstat (limited to 'docs/html/guide/developing/debug-tasks.jd')
| -rw-r--r-- | docs/html/guide/developing/debug-tasks.jd | 207 |
1 files changed, 207 insertions, 0 deletions
diff --git a/docs/html/guide/developing/debug-tasks.jd b/docs/html/guide/developing/debug-tasks.jd new file mode 100644 index 0000000..6b7c27a --- /dev/null +++ b/docs/html/guide/developing/debug-tasks.jd @@ -0,0 +1,207 @@ +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> |