docs/html/guide/developing/debug-tasks.jd - LeafOS-Project/android_frameworks_base - Gitiles

 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}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(&quot;MyActivity&quot;, &quot;MyClass.getView()
                 &mdash; Requesting item number &quot; + 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="#developingwitheclipse"><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>

 <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>&gt; <strong>Development Settings</strong>.
     This will open the development settings page with the following options (among
     others):</p>
 <ul>
     <li><strong>Debug app</strong>&nbsp;&nbsp;&nbsp;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> &nbsp;&nbsp;
         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>&nbsp;&nbsp;&nbsp;Tells the
         system to destroy an activity as soon as it is stopped (as if Android had to
         reclaim memory).&nbsp; 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>&nbsp;&nbsp;&nbsp;
         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>&nbsp;&nbsp;&nbsp;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>&nbsp;&nbsp;&nbsp;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>


 <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 &quot;ps&quot; to find the process you
 want, and then &quot;kill -3 &quot;. 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 &quot;Dump
 radio state&quot;.</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 &quot;Wait for debugger&quot; 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 &quot;Wait for debugger&quot;
     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>
	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}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="#developingwitheclipse"><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>

	<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>


	<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}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>