diff options
Diffstat (limited to 'docs/html/guide/developing/debug-tasks.jd')
| -rw-r--r-- | docs/html/guide/developing/debug-tasks.jd | 180 |
1 files changed, 180 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 000000000000..bd63dcf4ad5e --- /dev/null +++ b/docs/html/guide/developing/debug-tasks.jd @@ -0,0 +1,180 @@ +page.title=Debugging +@jd:body + +<p>Android has a fairly extensive set of tools to help you debug your programs: </p> +<ul> + <li><a href="{@docRoot}reference/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}reference/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}reference/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="#developingwitheclipse"><strong>Eclipse plugin</strong></a> - The Eclipse + Android plugin incorporates 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}kb/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> + +<a name="additionaldebugging" id="additionaldebugging"></a> + +<h2>Debug and Test Settings on the Device</h2> + +<p>Android lets you set 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, + go to <strong>Dev Tools </strong>> <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> + +<a name="toptips" id="toptips"></a> + +<div class="sidebox"> +<h2>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}reference/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}reference/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}reference/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}reference/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> +<a name="building"></a> +</div>
\ No newline at end of file |