diff options
| author | Scott Main <smain@google.com> | 2012-06-21 17:14:39 -0700 |
|---|---|---|
| committer | Scott Main <smain@google.com> | 2012-06-21 21:27:30 -0700 |
| commit | 50e990c64fa23ce94efa76b9e72df7f8ec3cee6a (patch) | |
| tree | 52605cd25e01763596477956963fabcd087054b0 /docs/html/guide/developing/debugging | |
| parent | a2860267cad115659018d636bf9203a644c680a7 (diff) | |
| download | frameworks_base-50e990c64fa23ce94efa76b9e72df7f8ec3cee6a.zip frameworks_base-50e990c64fa23ce94efa76b9e72df7f8ec3cee6a.tar.gz frameworks_base-50e990c64fa23ce94efa76b9e72df7f8ec3cee6a.tar.bz2 | |
Massive clobber of all HTML files in developer docs for new site design
Change-Id: Idc55a0b368c1d2c1e7d4999601b739dd57f08eb3
Diffstat (limited to 'docs/html/guide/developing/debugging')
8 files changed, 0 insertions, 2032 deletions
diff --git a/docs/html/guide/developing/debugging/ddms.jd b/docs/html/guide/developing/debugging/ddms.jd deleted file mode 100644 index 9892e49..0000000 --- a/docs/html/guide/developing/debugging/ddms.jd +++ /dev/null @@ -1,357 +0,0 @@ -page.title=Using DDMS -parent.title=Debugging -parent.link=index.html -@jd:body - - <div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - - <ol> - <li><a href="#running">Running DDMS</a></li> - <li><a href="#how-ddms-works">How DDMS Interacts with a Debugger</a></li> - - <li><a href="#using-ddms">Using DDMS</a> - <ol> - <li><a href="#heap">Viewing heap usage for a process</a></li> - <li><a href="#alloc">Tracking memory allocation of objects</a></li> - <li><a href="#emulator">Working with an emulator or device's file system</a></li> - <li><a href="#thread">Examining thread information</a></li> - <li><a href="#profiling">Starting method profiling</a></li> - <li><a href="#network">Using the Network Traffic tool</a></li> - <li><a href="#logcat">Using LogCat</a></li> - <li><a href="#ops-location">Emulating phone operations and location</a></li> - </ol> - - </li> - </ol> - </div> - </div> - - <p>Android ships with a debugging tool called the Dalvik Debug Monitor Server (DDMS), which - provides port-forwarding services, screen capture on the device, thread and heap information on - the device, logcat, process, and radio state information, incoming call and SMS spoofing, - location data spoofing, and more. This page provides a modest discussion of DDMS features; it is - not an exhaustive exploration of all the features and capabilities.</p> - - <h2 id="running">Running DDMS</h2> - <p>DDMS is integrated into Eclipse and is also shipped in the <code>tools/</code> directory of the - SDK. DDMS works with both the emulator and a connected device. If both are connected and running simultaneously, - DDMS defaults to the emulator.</p> - - <ul> - <li>From Eclipse: Click <strong>Window > Open Perspective > Other... > DDMS</strong>.</li> - <li>From the command line: Type <code>ddms</code> (or <code>./ddms</code> on Mac/Linux) from the <code>tools/</code> - directory. </li> - </ul> - - - <h2 id="how-ddms-works">How DDMS Interacts with a Debugger</h2> - - <p>On Android, every application runs in its own process, each of which runs in its own virtual machine - (VM). Each VM exposes a unique port that a debugger can attach to.</p> - - <p>When DDMS starts, it connects to <a href="{@docRoot}guide/developing/tools/adb.html">adb</a>. - When a device is connected, a VM monitoring service is created between - <code>adb</code> and DDMS, which notifies DDMS when a VM on the device is started or terminated. Once a VM - is running, DDMS retrieves the the VM's process ID (pid), via <code>adb</code>, and opens a connection to the - VM's debugger, through the adb daemon (adbd) on the device. DDMS can now talk to the VM using a - custom wire protocol.</p> - - <p>DDMS assigns a debugging port to each VM on the device. Typically, - DDMS assigns port 8600 for the first debuggable VM, the next on 8601, and so on. When a debugger - connects to one of these ports, all traffic is forwarded to the debugger from the associated - VM. You can only attach a single debugger to a single port, but DDMS can handle multiple, attached - debuggers.</p> - - <p>By default, DDMS also listens on another debugging port, the DDMS "base port" (8700, by default). - The base port is a port forwarder, which can accept VM traffic from any debugging port and forward - it to the debugger on port 8700. This allows you to attach one debugger to port 8700, and debug - all the VMs on a device. The traffic that is forwarded is determined by the currently selected process - in the DDMS Devices view.</p> - - <p>The following screenshot shows a typical DDMS screen in Eclipse. If you are starting DDMS from - the command line, the screen is slightly different, but much of the functionality is identical. - Notice that the highlighted process, <code>com.android.email</code>, that is running in the emulator - has the debugging port 8700 assigned to it as well as 8606. This signifies that DDMS is currently - forwarding port 8606 to the static debugging port of 8700.</p> - - <img src="{@docRoot}images/debug-ddms.png" - width="1024" /> - <p class="img-caption"><strong>Figure 1.</strong> - Screenshot of DDMS</p> - - <p>If you are not using Eclipse and ADT, read <a href= - "{@docRoot}guide/developing/debugging/debugging-projects-cmdline.html#debuggingPort">Configuring - your IDE to attach to the debugging port</a>, for more information on attaching your - debugger.</p> - - <p class="note"><strong>Tip:</strong> You can set a number of DDMS preferences in - <strong>File</strong> > <strong>Preferences</strong>. Preferences are saved to - <code>$HOME/.android/ddms.cfg</code>.</p> - - <p class="warning"><strong>Known debugging issues with Dalvik</strong><br /> - Debugging an application in the Dalvik VM should work the same as it does in other VMs. However, - when single-stepping out of synchronized code, the "current line" cursor may jump to the last - line in the method for one step.</p> - - <h2 id="using-ddms">Using DDMS</h2> - The following sections describe how to use DDMS and the various tabs and panes that are part of the - DDMS GUI. The Eclipse version and the command line version have minor UI differences, but the - same functionality. For information on running DDMS, see the previous section in this document, - <a href="#running">Running DDMS</a>. - - - <h3 id="heap">Viewing heap usage for a process</h3> - - <p>DDMS allows you to view how much heap memory a process is using. This information is useful in - tracking heap usage at a certain point of time during the execution of your application.</p> - <p>To view heap usage for a process:</p> - <ol> - <li>In the Devices tab, select the process that you want to see the heap information for.</li> - - <li>Click the <strong>Update Heap</strong> button to enable heap information for the - process.</li> - - <li>In the Heap tab, click <strong>Cause GC</strong> to invoke garbage collection, which - enables the collection of heap data. When the operation completes, you will see a group of - object types and the memory that has been allocated for each type. You can click <strong>Cause - GC</strong> again to refresh the data.</li> - - <li>Click on an object type in the list to see a bar graph that shows the number of objects - allocated for a particular memory size in bytes.</li> - </ol> - - <h3 id="alloc">Tracking memory allocation of objects</h3> - - <p>DDMS provides a feature to track objects that are being allocated to memory and to see which - classes and threads are allocating the objects. This allows you to track, in real time, where - objects are being allocated when you perform certain actions in your application. This - information is valuable for assessing memory usage that can affect application performance. - </p> - - <p>To track memory allocation of objects:</p> - <ol> - <li>In the Devices tab, select the process that you want to enable allocation tracking - for.</li> - - <li>In the Allocation Tracker tab, click the <strong>Start Tracking</strong> button to begin - allocation tracking. At this point, anything you do in your application will be tracked.</li> - - <li>Click <strong>Get Allocations</strong> to see a list of objects that have been allocated - since you clicked on the <strong>Start Tracking</strong> button. You can click on <strong>Get - Allocations</strong> again to append to the list new objects that that have been - allocated.</li> - - <li>To stop tracking or to clear the data and start over, click the <strong>Stop Tracking - button</strong>.</li> - - <li>Click on a specific row in the list to see more detailed information such as the method and - line number of the code that allocated the object.</li> - </ol> - - <h3 id="emulator">Working with an emulator or device's file system</h3> - - <p>DDMS provides a File Explorer tab that allows you to view, copy, and delete files on the - device. This feature is useful in examining files that are created by your application or if you - want to transfer files to and from the device.</p> - - <p>To work with an emulator or device's file system:</p> - <ol> - <li>In the Devices tab, select the emulator that you want to view the file system for.</li> - - <li>To copy a file from the device, locate the file in the File Explorer and click the - <strong>Pull file</strong> button.</li> - - <li>To copy a file to the device, click the <strong>Push file</strong> button on the File - Explorer tab.</li> - </ol> - - <!-- Need to elaborate more on where things are stored in the file system, - databases, apks, user info, files that are important to look at --> - - <h3 id="thread">Examining thread information</h3> - - <p>The Threads tab in DDMS shows you the currently running threads for a selected process.</p> - - <ol> - <li>In the Devices tab, select the process that you want to examine the threads for.</li> - - <li>Click the <strong>Update Threads</strong> button.</li> - - <li>In the Threads tab, you can view the thread information for the selected process.</li> - </ol> - - <h3 id="profiling">Starting method profiling</h3> - - <p>Method profiling is a means to track certain metrics about a method, such as number of calls, - execution time, and time spent executing the method. If you want more granular control over - where profiling data is collected, use the {@link android.os.Debug#startMethodTracing()} and - {@link android.os.Debug#stopMethodTracing()} methods. For more information about generating trace logs, see - <a href="debugging-tracing.html">Profiling and Debugging UIs</a>.</p> - - <p>Before you start method profiling in DDMS, be aware of the following restrictions:</p> - <ul> - <li>Android 1.5 devices are not supported.</li> - <li>Android 2.1 and earlier devices must - have an SD card present and your application must have permission to write to the SD card. - <li>Android 2.2 and later devices do not need an SD card. The trace log files are - streamed directly to your development machine.</li> - </ul> - - <p>To start method profiling:</p> - <ol> - <li>On the Devices tab, select the process that you want to enable method profiling for.</li> - - <li>Click the <strong>Start Method Profiling</strong> button.</li> - - <li>Interact with your application to start the methods that you want to profile.</li> - - <li>Click the <strong>Stop Method Profiling</strong> button. DDMS stops profiling your - application and opens <a href="{@docRoot}guide/developing/debugging/debugging-ui.html">Traceview</a> - with the method profiling information that was collected - between the time you clicked on <strong>Start Method Profiling</strong> and <strong>Stop Method - Profiling</strong>.</li> - </ol> - - <h3 id="network">Using the Network Traffic tool</h3> - - <p>In Android 4.0, the DDMS (Dalvik Debug Monitor Server) includes a Detailed -Network Usage tab that makes it possible to track when your application is -making network requests. Using this tool, you can monitor how and when your app -transfers data and optimize the underlying code appropriately. You can also -distinguish between different traffic types by applying a “tag” to network -sockets before use.</p> - -<p>These tags are shown in a stack area chart in DDMS, as shown in figure 2:</p> - -<img src="{@docRoot}images/developing/ddms-network.png" /> -<p class="img-caption"><strong>Figure 2.</strong> Network Usage tab.</p> - -<p>By monitoring the frequency of your data transfers, and the amount of data -transferred during each connection, you can identify areas of your application -that can be made more battery-efficient. Generally, you should look for -short spikes that can be delayed, or that should cause a later transfer to be -pre-empted. </p> - -<p>To better identify the cause of transfer spikes, the -{@link android.net.TrafficStats} API allows you -to tag the data transfers occurring within a thread using {@link -android.net.TrafficStats#setThreadStatsTag setThreadStatsTag()}, followed -by manually tagging (and untagging) individual sockets using {@link -android.net.TrafficStats#tagSocket tagSocket()} and {@link -android.net.TrafficStats#untagSocket untagSocket()}. For example:</p> - -<pre>TrafficStats.setThreadStatsTag(0xF00D); -TrafficStats.tagSocket(outputSocket); -// Transfer data using socket -TrafficStats.untagSocket(outputSocket);</pre> - -<p>Alternatively, the Apache {@link org.apache.http.client.HttpClient} and -{@link java.net.URLConnection} APIs included in the platform -automatically tag sockets internally based on the active tag (as -identified by -{@link android.net.TrafficStats#getThreadStatsTag getThreadStatsTag()}). -These APIs correctly tag/untag sockets when recycled through -keep-alive pools. In the following example, -{@link android.net.TrafficStats#setThreadStatsTag setThreadStatsTag()} -sets the active tag to be {@code 0xF00D}. -There can only be one active tag per thread. -That is the value that will -be returned by {@link android.net.TrafficStats#getThreadStatsTag getThreadStatsTag()} -and thus used by {@link org.apache.http.client.HttpClient} - to tag sockets. The {@code finally} statement -invokes -{@link android.net.TrafficStats#clearThreadStatsTag clearThreadStatsTag()} -to clear the tag.</p> - -<pre>TrafficStats.setThreadStatsTag(0xF00D); - try { - // Make network request using HttpClient.execute() - } finally { - TrafficStats.clearThreadStatsTag(); -}</pre> - -<p>Socket tagging is supported in Android 4.0, but real-time stats will only be -displayed on devices running Android 4.0.3 or higher.</p> - - <h3 id="logcat">Using LogCat</h3> - - <p>LogCat is integrated into DDMS, and outputs the messages that you print out using the {@link android.util.Log} - class along with other system messages such as stack traces when exceptions are thrown. View the - <a href="{@docRoot}guide/developing/debugging/debugging-log.html">Reading and - Writing Log Messages.</a> topic for more information on how to log messages to the LogCat.</p> - - <p>When you have set up your logging, you can use the LogCat feature of DDMS to filter certain - messages with the following buttons:</p> - - <ul> - <li>Verbose</li> - - <li>Debug</li> - - <li>Info</li> - - <li>Warn</li> - - <li>Error</li> - </ul> - - <p>You can also setup your own custom filter to specify more details such as filtering messages - with the log tags or with the process id that generated the log message. The add filter, - edit filter, and delete filter buttons let you manage your custom filters.</p> - - <h3 id="ops-location">Emulating phone operations and location</h3> - <p>The Emulator control tab lets you simulate a - phone's voice and data network status. This is useful when you want to test your application's - robustness in differing network environments.</p> - - <h4>Changing network state, speed, and latency</h4> - <p>The Telephony Status section of the Emulator - controls tab lets you change different aspects of the phone's networks status, speed and latency. - The following options are available to you and are effective immediately after you set them:</p> - - <ul> - <li>Voice - unregistered, home, roaming, searching, denied</li> - - <li>Data - unregistered, home, roaming, searching, denied</li> - - <li>Speed - Full, GSM, HSCSD, GPRS, EDGE, UMTS, HSDPA</li> - - <li>Latency - GPRS, EDGE, UMTS</li> - </ul> - - <h4>Spoofing calls or SMS text messages</h4> - <p>The Telephony Actions section of the Emulator - controls tab lets you spoof calls and messages. This is useful when you want to to test your - application's robustness in responding to incoming calls and messages that are sent to the phone. - The following actions are available to you:</p> - - <ul> - <li>Voice - Enter a number in the <strong>Incoming number</strong> field and click - <strong>Call</strong> to send a simulated call to the emulator or phone. Click the - <strong>Hang up</strong> button to terminate the call.</li> - - <li>SMS - Enter a number in the <strong>Incoming number</strong> field and a message in the - <strong>Message:</strong> field and click the <strong>Send</strong> button to send the - message.</li> - </ul> - - <h4>Setting the location of the phone</h4> - <p>If your application depends on the location of the phone, you can have DDMS send your - device or AVD a mock location. This is useful if you - want to test different aspects of your application's location specific features without - physically moving. The following geolocation data types are available to you:</p> - - <ul> - <li>Manual - set the location by manually specifying decimal or sexagesimal longitude and - latitude values.</li> - - <li>GPX - GPS eXchange file</li> - - <li>KML - Keyhole Markup Language file</li> - </ul> - - For more information about providing mock location data, see - <a href="{@docRoot}guide/topics/location/obtaining-user-location.html#MockData">Obtaining User Location</a>. - diff --git a/docs/html/guide/developing/debugging/debugging-devtools.jd b/docs/html/guide/developing/debugging/debugging-devtools.jd deleted file mode 100644 index 157d62e..0000000 --- a/docs/html/guide/developing/debugging/debugging-devtools.jd +++ /dev/null @@ -1,85 +0,0 @@ -page.title=Using the Dev Tools App -parent.title=Debugging -parent.link=index.html -@jd:body - -<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. 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> 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 <strong>Development Settings</strong>. 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 {@link android.app.Activity#onCreate 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. For more information about saving an activity's state, see the - <a href="{@docRoot}guide/topics/fundamentals/activities.html#SavingActivityState">Activities</a> -document.</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. - <p class="note">Note: You cannot turn this feature off once it is on, without - restarting the emulator.</p></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> - - - diff --git a/docs/html/guide/developing/debugging/debugging-log.jd b/docs/html/guide/developing/debugging/debugging-log.jd deleted file mode 100644 index b5b626e..0000000 --- a/docs/html/guide/developing/debugging/debugging-log.jd +++ /dev/null @@ -1,308 +0,0 @@ -page.title=Reading and Writing Logs -parent.title=Debugging -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - - <ol> - <li><a href="#logClass">The Log class</a></li> - - <li><a href="#startingLogcat">Starting LogCat</a></li> - - <li><a href="#filteringOutput">Filtering Log Output</a></li> - - <li><a href="#outputFormat">Controlling Log Output Format</a></li> - - <li><a href="#alternativeBuffers">Viewing Alternative Log Output Buffers</a></li> - - <li><a href="#viewingStd">Viewing stdout and stderr</a></li> - - <li><a href="#DebuggingWebPages">Debugging Web Pages</a></li> - </ol> - </div> - </div> - - <p>The Android logging system provides a mechanism for collecting and viewing system debug - output. Logcat dumps a log of system messages, which include things such as stack traces when the - emulator throws an error and messages that you have written from your application by using the - {@link android.util.Log} class. You can run LogCat through ADB or from DDMS, which allows you to - read the messages in real time.</p> - - <h2 id="logClass">The <code>Log</code> class</h2> - - <p>{@link android.util.Log} is a logging class that you can utilize in your code to print out - messages to the LogCat. Common logging methods include:</p> - - <ul> - <li>{@link android.util.Log#v(String,String)} (verbose)</li> - - <li>{@link android.util.Log#d(String,String)} (debug)</li> - - <li>{@link android.util.Log#i(String,String)} (information)</li> - - <li>{@link android.util.Log#w(String,String)} (warning)</li> - - <li>{@link android.util.Log#e(String,String)} (error)</li> - </ul>For example: - <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> - - <h2 id="startingLogcat">Using LogCat</h2> - - <p>You can use LogCat from within DDMS or call it on an ADB shell. For more information on how to - use LogCat within DDMS, see <a href="{@docRoot}guide/developing/debugging/ddms.html#logcat">Using - DDMS</a>. To run LogCat, through the ADB shell, the general usage is:</p> - <pre> -[adb] logcat [<option>] ... [<filter-spec>] ... -</pre> - - <p>You can use the <code>logcat</code> command from your development computer or from a remote - adb shell in an emulator/device instance. To view log output in your development computer, you - use</p> - <pre> -$ adb logcat -</pre> - - <p>and from a remote adb shell you use</p> - <pre> -# logcat -</pre> - - <p>The following table describes the <code>logcat</code> command line options:</p> - - <table> - <tr> - <td><code>-c</code></td> - - <td>Clears (flushes) the entire log and exits.</td> - </tr> - - <tr> - <td><code>-d</code></td> - - <td>Dumps the log to the screen and exits.</td> - </tr> - - <tr> - <td><code>-f <filename></code></td> - - <td>Writes log message output to <code><filename></code>. The default is - <code>stdout</code>.</td> - </tr> - - <tr> - <td><code>-g</code></td> - <td>Prints the size of the specified log buffer and exits.</td> - </tr> - - <tr> - <td><code>-n <count></code></td> - - <td>Sets the maximum number of rotated logs to <code><count></code>. The default value - is 4. Requires the <code>-r</code> option.</td> - </tr> - - <tr> - <td><code>-r <kbytes></code></td> - - <td>Rotates the log file every <code><kbytes></code> of output. The default value is - 16. Requires the <code>-f</code> option.</td> - </tr> - - <tr> - <td><code>-s</code></td> - - <td>Sets the default filter spec to silent.</td> - </tr> - - <tr> - <td><code>-v <format></code></td> - - <td>Sets the output format for log messages. The default is <code>brief</code> format. For a - list of supported formats, see <a href="#outputFormat">Controlling Log Output - Format</a>.</td> - </tr> - </table> - - <h3 id="filteringOutput">Filtering Log Output</h3> - - <p>Every Android log message has a <em>tag</em> and a <em>priority</em> associated with it.</p> - - <ul> - <li>The tag of a log message is a short string indicating the system component from which the - message originates (for example, "View" for the view system).</li> - - <li>The priority is one of the following character values, ordered from lowest to highest - priority:</li> - - <li style="list-style: none; display: inline"> - <ul> - <li><code>V</code> — Verbose (lowest priority)</li> - - <li><code>D</code> — Debug</li> - - <li><code>I</code> — Info</li> - - <li><code>W</code> — Warning</li> - - <li><code>E</code> — Error</li> - - <li><code>F</code> — Fatal</li> - - <li><code>S</code> — Silent (highest priority, on which nothing is ever printed)</li> - </ul> - </li> - </ul> - - <p>You can obtain a list of tags used in the system, together with priorities, by running - LogCat and observing the first two columns of each message, given as - <code><priority>/<tag></code>.</p> - - <p>Here's an example of logcat output that shows that the message relates to priority level "I" - and tag "ActivityManager":</p> - <pre> -I/ActivityManager( 585): Starting activity: Intent { action=android.intent.action...} -</pre> - - <p>To reduce the log output to a manageable level, you can restrict log output using <em>filter - expressions</em>. Filter expressions let you indicate to the system the tags-priority - combinations that you are interested in — the system suppresses other messages for the - specified tags.</p> - - <p>A filter expression follows this format <code>tag:priority ...</code>, where <code>tag</code> - indicates the tag of interest and <code>priority</code> indicates the <em>minimum</em> level of - priority to report for that tag. Messages for that tag at or above the specified priority are - written to the log. You can supply any number of <code>tag:priority</code> specifications in a - single filter expression. The series of specifications is whitespace-delimited.</p> - - <p>Here's an example of a filter expression that suppresses all log messages except those with - the tag "ActivityManager", at priority "Info" or above, and all log messages with tag "MyApp", - with priority "Debug" or above:</p> - <pre> -adb logcat ActivityManager:I MyApp:D *:S -</pre> - - <p>The final element in the above expression, <code>*:S</code>, sets the priority level for all - tags to "silent", thus ensuring only log messages with "View" and "MyApp" are displayed. Using - <code>*:S</code> is an excellent way to ensure that log output is restricted to the filters that - you have explicitly specified — it lets your filters serve as a "whitelist" for log - output.</p> - - <p>The following filter expression displays all log messages with priority level "warning" and higher, on all tags:</p> - <pre> -adb logcat *:W -</pre> - - <p>If you're running LogCat from your development computer (versus running it on a - remote adb shell), you can also set a default filter expression by exporting a value for the - environment variable <code>ANDROID_LOG_TAGS</code>:</p> - <pre> -export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S" -</pre> - - <p>Note that <code>ANDROID_LOG_TAGS</code> filter is not exported to the emulator/device - instance, if you are running LogCat from a remote shell or using <code>adb shell - logcat</code>.</p> - - <h3 id="outputFormat">Controlling Log Output Format</h3> - - <p>Log messages contain a number of metadata fields, in addition to the tag and priority. You can - modify the output format for messages so that they display a specific metadata field. To do so, - you use the <code>-v</code> option and specify one of the supported output formats listed - below.</p> - - <ul> - <li><code>brief</code> — Display priority/tag and PID of the process issuing the - message (the default format).</li> - - <li><code>process</code> — Display PID only.</li> - - <li><code>tag</code> — Display the priority/tag only.</li> - - <li><code>raw</code> — Display the raw log message, with no other metadata fields.</li> - - <li><code>time</code> — Display the date, invocation time, priority/tag, and PID of the - process issuing the message.</li> - - <li><code>threadtime</code> — Display the date, invocation time, priority, tag, and - the PID and TID of the thread issuing the message.</li> - - <li><code>long</code> — Display all metadata fields and separate messages with blank - lines.</li> - </ul> - - <p>When starting LogCat, you can specify the output format you want by using the - <code>-v</code> option:</p> - <pre> -[adb] logcat [-v <format>] -</pre> - - <p>Here's an example that shows how to generate messages in <code>thread</code> output - format:</p> - <pre> -adb logcat -v thread -</pre> - - <p>Note that you can only specify one output format with the <code>-v</code> option.</p> - - <h3 id="alternativeBuffers">Viewing Alternative Log Buffers</h3> - - <p>The Android logging system keeps multiple circular buffers for log messages, and not all of - the log messages are sent to the default circular buffer. To see additional log messages, you can - run the <code>logcat</code> command with the <code>-b</code> option, to request viewing of an alternate - circular buffer. You can view any of these alternate buffers:</p> - - <ul> - <li><code>radio</code> — View the buffer that contains radio/telephony related - messages.</li> - - <li><code>events</code> — View the buffer containing events-related messages.</li> - - <li><code>main</code> — View the main log buffer (default)</li> - </ul> - - <p>The usage of the <code>-b</code> option is:</p> - <pre> -[adb] logcat [-b <buffer>] -</pre> - - <p>Here's an example of how to view a log buffer containing radio and telephony messages:</p> - <pre> -adb logcat -b radio -</pre><a name="stdout" - id="stdout"></a> - - <h2 id="viewingStd">Viewing stdout and stderr</h2> - - <p>By default, the Android system sends <code>stdout</code> and <code>stderr</code> - (<code>System.out</code> and <code>System.err</code>) output to <code>/dev/null</code>. In - processes that run the Dalvik VM, you can have the system write a copy of the output to the log - file. In this case, the system writes the messages to the log using the log tags - <code>stdout</code> and <code>stderr</code>, both with priority <code>I</code>.</p> - - <p>To route the output in this way, you stop a running emulator/device instance and then use the - shell command <code>setprop</code> to enable the redirection of output. Here's how you do it:</p> - <pre> -$ adb shell stop -$ adb shell setprop log.redirect-stdio true -$ adb shell start -</pre> - - <p>The system retains this setting until you terminate the emulator/device instance. To use the - setting as a default on the emulator/device instance, you can add an entry to - <code>/data/local.prop</code> on the device.</p> - - <h2 id="DebuggingWebPages">Debugging Web Apps</h2> - <p> - If you're developing a web application for Android, you can debug your JavaScript using the console JavaScript APIs, - which output messages to LogCat. For more information, see - <a href="{@docRoot}guide/webapps/debugging.html">Debugging Web Apps</a>.</p> diff --git a/docs/html/guide/developing/debugging/debugging-projects-cmdline.jd b/docs/html/guide/developing/debugging/debugging-projects-cmdline.jd deleted file mode 100644 index 3b5ceab..0000000 --- a/docs/html/guide/developing/debugging/debugging-projects-cmdline.jd +++ /dev/null @@ -1,78 +0,0 @@ -page.title=Debugging from Other IDEs -parent.title=Debugging -parent.link=index.html -@jd:body - - - <div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - - <ol> - <li><a href="#start-debugging">Starting a Debugging Environment</a> - <ul> - <li><a href="#debuggingPort">Configuring Your IDE to Attach to the Debugging Port</a></li> - </ul> - </li> - </ol> - </div> - </div> - - <p>If you are not using Eclipse to develop, you can still take advantage of all the tools that - the Android SDK provides for debugging. A basic debugging environment consists of:</p> - - <ul> - <li><a href="{@docRoot}guide/developing/tools/adb.html">ADB</a></li> - - <li><a href="{@docRoot}guide/developing/debugging/ddms.html">DDMS</a></li> - - <li>Java Debugger</li> - </ul> - - <p>You need to obtain a JDWP-compliant Java debugger to properly debug your application. - Most Java IDEs will already have one included, or you can use a command line debugger, - such as JDB, if you are using a simple text editor to develop applications.</p> - - <h2 id="start-debugging">Starting a debugging environment</h2> - <p>A Java Debugger assists you in finding problems with - your code by letting you set breakpoints, step through execution of your application, and examine - variable values. Since you are not using Eclipse, you have to manually start up the debugging - environment yourself by running a few tools that are provided in the Android SDK. To begin - debugging your application, follow these general steps:</p> - - <ol> - <li>Load an AVD with the Android emulator or connect a device to your computer.</li> - - <li>Start DDMS from the sdk <code>/tools</code> directory. This also starts ADB if it is - not already started. You should see your device appear in DDMS.</li> - - <li>Install and run your <code>.apk</code> file on the device or emulator. In DDMS, you should see your - application running under the device that you installed it to.</li> - - <li>Attach your debugger to the debugging port 8700, or to the specific port shown for the - application in DDMS.</li> - </ol> - - <h3 id="debuggingPort">Configuring Your IDE to Attach to the Debugging Port</h3> - - <p>DDMS assigns 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> - - - - - - - diff --git a/docs/html/guide/developing/debugging/debugging-projects.jd b/docs/html/guide/developing/debugging/debugging-projects.jd deleted file mode 100644 index 2283f8b..0000000 --- a/docs/html/guide/developing/debugging/debugging-projects.jd +++ /dev/null @@ -1,67 +0,0 @@ -page.title=Debugging from Eclipse with ADT -parent.title=Debugging -parent.link=index.html -@jd:body - - <div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - - <ol> - <li><a href="#tools">The Debug Perspective</a></li> - - <li><a href="#toptips">The DDMS Perspective</a></li> - </ol> - </div> - </div> - - <p>If you are developing in Eclipse with the ADT plugin, you can use the built-in Java Debugger, - along with DDMS, to debug your applications. To access the debugger and - DDMS, Eclipse displays the debugger and DDMS features as perspectives, which are customized - Eclipse views that display certain tabs and windows depending on the perspective that you are in. - Eclipse also takes care of starting the ADB host daemon for you, so you do not have to run this - manually.</p> - - <h2>The Debug Perspective in Eclipse</h2> - - <p>The Debug Perspective in Eclipse gives you access to the following tabs:</p> - - <ul> - <li>Debug - Displays previously and currently debugged Android applications and its currently - running threads</li> - - <li>Variables - When breakpoints are set, displays variable values during code execution</li> - - <li>Breakpoints - Displays a list of the set breakpoints in your application code</li> - - <li>LogCat - Allows you to view system log messages in real time. The LogCat tab is also - available in the DDMS perspective.</li> - </ul> - <p>You can access the Debug Perspective by clicking <strong>Window > Open Perspective > - Debug</strong>. Refer to the appropriate documentation for the Eclipse debugger for more - information.</p> - - <h2>The DDMS Perspective</h2> - <p>The DDMS Perspective in Eclipse lets you access all of the features - of DDMS from within the Eclipse IDE. The following sections of DDMS are available to you:</p> - - <ul> - <li>Devices - Shows the list of devices and AVDs that are connected to ADB.</li> - - <li>Emulator Control - Lets you carry out device functions.</li> - - <li>LogCat - Lets you view system log messages in real time.</li> - - <li>Threads - Shows currently running threads within a VM.</li> - - <li>Heap - Shows heap usage for a VM.</li> - - <li>Allocation Tracker - Shows the memory allocation of objects.</li> - - <li>File Explorer - Lets you explore the device's file system.</li> - </ul> - <p>To access the DDMS perspective, go to <strong>Window > Open Perspective > - DDMS</strong>. If DDMS does not appear, go to <strong>Window > Open Perspective > Other - ...</strong> and select <strong>DDMS</strong> from the Open Perspective window that appears. For - more information on using DDMS, see <a href="ddms.html">Using the Dalvik Debug Monitor Server</a>. - </p>
\ No newline at end of file diff --git a/docs/html/guide/developing/debugging/debugging-tracing.jd b/docs/html/guide/developing/debugging/debugging-tracing.jd deleted file mode 100644 index 72f6498..0000000 --- a/docs/html/guide/developing/debugging/debugging-tracing.jd +++ /dev/null @@ -1,402 +0,0 @@ -page.title=Profiling with Traceview and dmtracedump -parent.title=Debugging -parent.link=index.html -@jd:body - - <div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - - <ol> - <li> - <a href="#traceviewLayout">Traceview Layout</a> - - <ol> - <li><a href="#timelinepanel">Timeline Panel</a></li> - - <li><a href="#profilepanel">Profile Panel</a></li> - </ol> - </li> - - <li> - <a href="#format">Traceview File Format</a> - <ol> - <li><a href="#datafileformat">Data File Format</a></li> - - <li><a href="#keyfileformat">Key File Format</a></li> - </ol> - </li> - - <li><a href="#creatingtracefiles">Creating Trace Files</a></li> - - <li><a href="#copyingfiles">Copying Trace Files to a Host Machine</a></li> - - <li><a href="#runningtraceview">Viewing Trace Files in Traceview</a></li> - - <li><a href="#dmtracedump">Using dmtracedump</a></li> - - <li><a href="#knownissues">Traceview Known Issues</a></li> - </ol> - </div> - </div> - - <p>Traceview is a graphical viewer for execution logs that you create by using the {@link - android.os.Debug} class to log tracing information in your code. Traceview can help you debug - your application and profile its performance.</p> - - <h2 id="traceviewLayout">Traceview Layout</h2> - - <p>When you have a trace log file (generated by adding tracing code to your application or by DDMS), - you can have Traceview load the log files and display their data in a window visualizes your application - in two panels:</p> - - <ul> - <li>A <a href="#timelinepanel">timeline panel</a> -- describes when each thread and method - started and stopped</li> - - <li>A <a href="#timelinepanel">profile panel</a> -- provides a summary of what happened inside - a method</li> - </ul> - - <p>The sections below provide addition information about the traceview output panes.</p> - - <h3 id="timelinepanel">Timeline Panel</h3> - - <p>The image below shows a close up of the timeline panel. Each thread’s execution is shown - in its own row, with time increasing to the right. Each method is shown in another color (colors - are reused in a round-robin fashion starting with the methods that have the most inclusive time). - The thin lines underneath the first row show the extent (entry to exit) of all the calls to the - selected method. The method in this case is <code>LoadListener.nativeFinished()</code> and it was selected in - the profile view.</p> - - <img src="{@docRoot}images/traceview_timeline.png" - alt="Traceview timeline panel" - width="893" - height="284" /> - <p class="img-caption"><strong>Figure 1.</strong> The Traceview Timeline Panel</p> - - <h3 id="profilepanel">Profile Panel</h3> - - <p>Figure 2 shows the profile pane, a summary of all the time spent - in a method. The table shows both the inclusive and exclusive times (as well as the percentage of - the total time). Exclusive time is the time spent in the method. Inclusive time is the time spent - in the method plus the time spent in any called functions. We refer to calling methods as - "parents" and called methods as "children." When a method is selected (by clicking on it), it - expands to show the parents and children. Parents are shown with a purple background and children - with a yellow background. The last column in the table shows the number of calls to this method - plus the number of recursive calls. The last column shows the number of calls out of the total - number of calls made to that method. In this view, we can see that there were 14 calls to - <code>LoadListener.nativeFinished();</code> looking at the timeline panel shows that one of those calls took - an unusually long time.</p> - - <img src="{@docRoot}images/traceview_profile.png" - alt="Traceview profile panel." - width="892" - height="630" /> - <p class="img-caption"><strong>Figure 2.</strong> The Traceview Profile Panel</p> - - <h2 id="format">Traceview File Format</h2> - - <p>Tracing creates two distinct pieces of output: a <em>data</em> file, which holds the trace - data, and a <em>key</em> file, which provides a mapping from binary identifiers to thread and - method names. The files are concatenated when tracing completes, into a single <em>.trace</em> - file.</p> - - <p class="note"><strong>Note:</strong> The previous version of Traceview did not concatenate - these files for you. If you have old key and data files that you'd still like to trace, you can - concatenate them yourself with <code>cat mytrace.key mytrace.data > - mytrace.trace</code>.</p> - - <h3 id="datafileformat">Data File Format</h3> - - <p>The data file is binary, structured as follows (all values are stored in little-endian - order):</p> - <pre> -* File format: -* header -* record 0 -* record 1 -* ... -* -* Header format: -* u4 magic 0x574f4c53 ('SLOW') -* u2 version -* u2 offset to data -* u8 start date/time in usec -* -* Record format: -* u1 thread ID -* u4 method ID | method action -* u4 time delta since start, in usec -</pre> - - <p>The application is expected to parse all of the header fields, then seek to "offset to data" - from the start of the file. From there it just reads 9-byte records until EOF is reached.</p> - - <p><em>u8 start date/time in usec</em> is the output from <code>gettimeofday()</code>. It's mainly there so - that you can tell if the output was generated yesterday or three months ago.</p> - - <p><em>method action</em> sits in the two least-significant bits of the <em>method</em> word. The - currently defined meanings are:</p> - - <ul> - <li>0 - method entry</li> - - <li>1 - method exit</li> - - <li>2 - method "exited" when unrolled by exception handling</li> - - <li>3 - (reserved)</li> - </ul> - - <p>An unsigned 32-bit integer can hold about 70 minutes of time in microseconds.</p> - - <h3 id="keyfileformat">Key File Format</h3> - - <p>The key file is a plain text file divided into three sections. Each section starts with a - keyword that begins with '*'. If you see a '*' at the start of a line, you have found the start - of a new section.</p> - - <p>An example file might look like this:</p> - <pre> -*version -1 -clock=global -*threads -1 main -6 JDWP Handler -5 Async GC -4 Reference Handler -3 Finalizer -2 Signal Handler -*methods -0x080f23f8 java/io/PrintStream write ([BII)V -0x080f25d4 java/io/PrintStream print (Ljava/lang/String;)V -0x080f27f4 java/io/PrintStream println (Ljava/lang/String;)V -0x080da620 java/lang/RuntimeException <init> ()V -[...] -0x080f630c android/os/Debug startMethodTracing ()V -0x080f6350 android/os/Debug startMethodTracing (Ljava/lang/String;Ljava/lang/String;I)V -*end -</pre> -<p>The following list describes the major sections of a key file:</p> - <dl> - <dt><em>version section</em></dt> - - <dd>The first line is the file version number, currently 1. The second line, - <code>clock=global</code>, indicates that we use a common clock across all threads. A future - version may use per-thread CPU time counters that are independent for every thread.</dd> - - <dt><em>threads section</em></dt> - - <dd>One line per thread. Each line consists of two parts: the thread ID, followed by a tab, - followed by the thread name. There are few restrictions on what a valid thread name is, so - include everything to the end of the line.</dd> - - <dt><em>methods section</em></dt> - - <dd>One line per method entry or exit. A line consists of four pieces, separated by tab marks: - <em>method-ID</em> [TAB] <em>class-name</em> [TAB] <em>method-name</em> [TAB] - <em>signature</em> . Only the methods that were actually entered or exited are included in the - list. Note that all three identifiers are required to uniquely identify a method.</dd> - </dl> - - <p>Neither the threads nor methods sections are sorted.</p> - - <h2 id="creatingtracefiles">Creating Trace Files</h2> - - <p>To use Traceview, you need to generate log files containing the trace information you want to - analyze.</p> - - <p>There are two ways to generate trace logs:</p> - <ul> - <li>Include the {@link android.os.Debug} class in your code and call its - methods to start and stop logging of trace information to disk. This method is very precise because - you can specify in your code exactly where to start and stop logging trace data.</li> - <li>Use the method profiling feature of DDMS to generate trace logs. This method is less - precise since you do not modify code, but rather specify when to start and stop logging with - a DDMS. Although you have less control on exactly where the data is logged, this method is useful - if you don't have access to the application's code, or if you do not need the precision of the first method. - </li> - </ul> - - <p>Before you start generating trace logs, be aware of the following restrictions:</p> - <ul> - <li>If you are using the {@link android.os.Debug} class, your device or emulator must have an SD card - and your application must have permission to write to the SD card. </li> - <li>If you are using DDMS, Android 1.5 devices are not supported.</li> - <li>If you are using DDMS, Android 2.1 and earlier devices must - have an SD card present and your application must have permission to write to the SD card. - <li>If you are using DDMS, Android 2.2 and later devices do not need an SD card. The trace log files are - streamed directly to your development machine.</li> - </ul> - - <p>This document focuses on using the {@link android.os.Debug} class to generate trace data. For more information on using DDMS - to generate trace data, see <a href="ddms.html#profiling">Using the Dalvik Debug Monitor Server.</a> - </p> - - <p>To create the trace files, include the {@link android.os.Debug} class and call one of the - {@link android.os.Debug#startMethodTracing() startMethodTracing()} methods. In the call, you - specify a base name for the trace files that the system generates. To stop tracing, call {@link - android.os.Debug#stopMethodTracing() stopMethodTracing()}. These methods start and stop method - tracing across the entire virtual machine. For example, you could call - {@link android.os.Debug#startMethodTracing() startMethodTracing()} in - your activity's {@link android.app.Activity#onCreate onCreate()} method, and call - {@link android.os.Debug#stopMethodTracing() stopMethodTracing()} in that activity's - {@link android.app.Activity#onDestroy()} method.</p> - <pre> - // start tracing to "/sdcard/calc.trace" - Debug.startMethodTracing("calc"); - // ... - // stop tracing - Debug.stopMethodTracing(); -</pre> - - <p>When your application calls startMethodTracing(), the system creates a file called - <code><trace-base-name>.trace</code>. This contains the binary method trace data and a - mapping table with thread and method names.</p> - - <p>The system then begins buffering the generated trace data, until your application calls - stopMethodTracing(), at which time it writes the buffered data to the output file. If the system - reaches the maximum buffer size before stopMethodTracing() is called, the system stops tracing - and sends a notification to the console.</p> - - <p>Interpreted code will run more slowly when profiling is enabled. Don't try to generate - absolute timings from the profiler results (i.e. "function X takes 2.5 seconds to run"). The - times are only useful in relation to other profile output, so you can see if changes have made - the code faster or slower.</p> - - <p>When using the Android emulator, you must specify an SD card when you create your AVD because the trace files - are written to the SD card. Your application must have permission to write to the SD card as well. - - <p>The format of the trace files is previously described <a href="#format">in this - document</a>.</p> - - <h2 id="copyingfiles">Copying Trace Files to a Host Machine</h2> - - <p>After your application has run and the system has created your trace files - <code><trace-base-name>.trace</code> on a device or emulator, you must copy those files to - your development computer. You can use <code>adb pull</code> to copy the files. Here's an example - that shows how to copy an example file, calc.trace, from the default location on the emulator to - the /tmp directory on the emulator host machine:</p> - <pre> -adb pull /sdcard/calc.trace /tmp -</pre> - - <h2 id="runningtraceview">Viewing Trace Files in Traceview</h2> - - <p>To run Traceview and view the trace files, enter <code>traceview - <trace-base-name></code>. For example, to run Traceview on the example files copied in the - previous section, use:</p> - <pre> -traceview /tmp/calc -</pre> - - <p class="note"><strong>Note:</strong> If you are trying to view the trace logs of an application - that is built with ProGuard enabled (release mode build), some method and member names might be obfuscated. - You can use the Proguard <code>mapping.txt</code> file to figure out the original unobfuscated names. For more information - on this file, see the <a href="{@docRoot}guide/developing/tools/proguard.html">Proguard</a> documentation.</p> - - <h2 id="dmtracedump">Using dmtracdedump</h2> - - <p><code>dmtracedump</code> is a tool that gives you an alternate way of generating - graphical call-stack diagrams from trace log files. The tool uses the Graphviz Dot utility to - create the graphical output, so you need to install Graphviz before running dmtracedump.</p> - - <p>The dmtracedump tool generates the call stack data as a tree diagram, with each call - represented as a node. It shows call flow (from parent node to child nodes) using arrows. The - diagram below shows an example of dmtracedump output.</p> - <img src= - "{@docRoot}images/tracedump.png" - width="485" - height="401" /> - <p class="image-caption"><strong>Figure 3.</strong> Screenshot of dmtracedump</p> - - <p>For each node, dmtracedump shows <code><ref> - <em>callname</em> (<inc-ms>, <exc-ms>,<numcalls>)</code>, where</p> - - <ul> - <li><code><ref></code> -- Call reference number, as used in trace logs</li> - - <li><code><inc-ms></code> -- Inclusive elapsed time (milliseconds spent in method, - including all child methods)</li> - - <li><code><exc-ms></code> -- Exclusive elapsed time (milliseconds spent in method, - not including any child methods)</li> - - <li><code><numcalls></code> -- Number of calls</li> - </ul> - - <p>The usage for dmtracedump is:</p> - <pre> -dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] <trace-base-name> -</pre> - - <p>The tool then loads trace log data from <code><trace-base-name>.data</code> and - <code><trace-base-name>.key</code>. The table below lists the options for dmtracedump.</p> - - <table> - <tr> - <th>Option</th> - - <th>Description</th> - </tr> - - <tr> - <td><code>-d <trace-base-name></code></td> - - <td>Diff with this trace name</td> - </tr> - - <tr> - <td><code>-g <outfile></code></td> - - <td>Generate output to <outfile></td> - </tr> - - <tr> - <td><code>-h</code></td> - - <td>Turn on HTML output</td> - </tr> - - <tr> - <td><code>-o</code></td> - - <td>Dump the trace file instead of profiling</td> - </tr> - - <tr> - <td><code>-d <trace-base-name></code></td> - - <td>URL base to the location of the sortable javascript file</td> - </tr> - - <tr> - <td><code>-t <percent></code></td> - - <td>Minimum threshold for including child nodes in the graph (child's inclusive time as a - percentage of parent inclusive time). If this option is not used, the default threshold - is 20%.</td> - </tr> - </table> - - - - <h2 id="knownissues">Traceview Known Issues</h2> - - <dl> - <dt>Threads</dt> - - <dd> - Traceview logging does not handle threads well, resulting in these two problems: - - <ol> - <li>If a thread exits during profiling, the thread name is not emitted;</li> - - <li>The VM reuses thread IDs. If a thread stops and another starts, they may get the same - ID.</li> - </ol> - </dd> - - </dl>
\ No newline at end of file diff --git a/docs/html/guide/developing/debugging/debugging-ui.jd b/docs/html/guide/developing/debugging/debugging-ui.jd deleted file mode 100644 index 22748be..0000000 --- a/docs/html/guide/developing/debugging/debugging-ui.jd +++ /dev/null @@ -1,547 +0,0 @@ -page.title=Debugging and Profiling User Interfaces -parent.title=Debugging -parent.link=index.html -@jd:body - - <div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - - <ol> - <li> - <a href="#HierarchyViewer"> - Debugging and Optimizing User Interfaces with Hierarchy Viewer - </a> - <ol> - <li><a href="#runhv">Running Hierarchy Viewer and choosing a window</a></li> - <li><a href="#viewhierarchy">About the View Hierarchy window</a></li> - <li><a href="#indiView">Working with an individual View in Tree View</a></li> - <li><a href="#hvdebugging">Debugging with View Hierarchy</a></li> - <li><a href="#hvoptimize">Optimizing with View Hierarchy</a></li> - </ol> - </li> - <li> - <a href="#pixelperfect"> - Examining and Designing User Interfaces with Pixel Perfect - </a> - <ol> - <li><a href="#aboutpixelperfect">About the Pixel Perfect window</a></li> - <li><a href="#overlays">Working with Pixel Perfect overlays</a></li> - </ol> - </li> - <li><a href="#layoutopt">Optimizing Layouts with <code>layoutopt</code></a></li> - </ol> - <h2>Related videos</h2> - <ol> - <li> -<iframe title="Hierarchyviewer" - width="272" height="234" - src="http://www.youtube.com/embed/PAgE7saQUUY?rel=0&hd=1" - frameborder="0" allowfullscreen> -</iframe> - </li> - <li> -<iframe title="Pixel Perfect" - width="272" height="234" - src="http://www.youtube.com/embed/C45bMZGdN7Y?rel=0&hd=1" - frameborder="0" - allowfullscreen> -</iframe> - </li> - </ol> - </div> - </div> - - <p> -Sometimes your application's layout can slow down your application. - To help debug issues in your layout, the Android SDK provides the Hierarchy Viewer and - <code>layoutopt</code> tools. - </p> - - <p>The Hierarchy Viewer application allows you to debug and optimize your user interface. It - provides a visual representation of the layout's View hierarchy (the View Hierarchy window) - and a magnified view of the display (the Pixel Perfect window).</p> - - <p><code>layoutopt</code> is a command-line tool that helps you optimize the layouts and layout - hierarchies of your applications. You can run it against your layout files or resource - directories to quickly check for inefficiencies or other types of problems that could be - affecting the performance of your application.</p> - -<h2 id="HierarchyViewer">Debugging and Optimizing User Interfaces with Hierarchy Viewer</h2> - -<h3 id="runhv">Running Hierarchy Viewer and choosing a window</h3> -<p> - To run Hierarchy Viewer, follow these steps:</p> -<ol> - <li> - Connect your device or launch an emulator. - <p> - To preserve security, Hierarchy Viewer can only connect to devices running a - developer version of the Android system. - </p> - </li> - <li> - If you have not done so already, install the application you want to work with. - </li> - <li> - Run the application, and ensure that its UI is visible. - </li> - <li> - From a terminal, launch <code>hierarchyviewer</code> from the - <code><sdk>/tools/</code> - directory. - </li> - <li> - The first window you see displays a list of devices and emulators. To expand the list - of Activity objects for a device or emulator, click the arrow on the left. This displays a - list of the Activity objects whose UI is currently visible on the device or emulator. The - objects are listed by their Android component name. The list includes both your application - Activity and system Activity objects. A screenshot of this window appears in - figure 1. - </li> - <li> - Select the name of your Activity from the list. You can now look at its view - hierarchy using the View Hierarchy window, or look at a magnified image of the UI using - the Pixel Perfect window. - </li> -</ol> -<p> - To learn how to use the View Hierarchy window, go to - <a href="#viewhierarchy">About the View Hierarchy window</a>. To learn how to use the - Pixel Perfect window, go to <a href="#pixelperfect">About the Pixel Perfect window</a>. -</p> -<img id="Fig1" src="{@docRoot}images/developing/hv_device_window.png" alt="" height="600"/> -<p class="img-caption"><strong>Figure 1.</strong> Hierarchy Viewer device window</p> -<h3 id="viewhierarchy">About the View Hierarchy window</h3> -<p> - The View Hierarchy window displays the View objects that form the UI of the - Activity that is running on your device or emulator. You use it to look at individual - View objects within the context of the entire View tree. For each View object, the View - Hierarchy window also displays rendering performance data. -</p> -<p> - To see the View Hierarchy window, run Hierarchy Viewer as described in - the section <a href="#runhv">Running Hierarchy Viewer and choosing a window</a>. Next, click - <strong>View Hierarchy</strong> at the top of the device window. -</p> -<p> - You should see four panes: -</p> -<ul> - <li> - <strong>Tree View</strong>: The left-hand pane displays the Tree View, - a diagram of the Activity object's hierarchy of views. Use Tree View to examine individual - View objects and see the relationships between View objects in your UI. - <p> - To zoom in on the pane, use the slider at the bottom of the pane, or use your mouse - scroll wheel. To move around in the pane or reveal View objects that are not currently - visible, click and drag the pane. - </p> - <p> - To highlight the nodes in the tree whose class or ID match a search string, enter the - string in the <strong>Filter by class or id:</strong> edit box at the bottom of the - window. The background of nodes that match the search string will change from gray to - bright blue. - </p> - <p> - To save a screenshot of Tree View to a PNG file, click <strong>Save As PNG</strong> at - the top of the View Hierarchy window. This displays a dialog in which you can choose - a directory and file name. - </p> - <p> - To save a layered screenshot of your device or emulator to an Adobe Photoshop (PSD) - file, click <strong>Capture Layers</strong> at the top of the View Hierarchy window. - This displays a dialog in which you can choose a directory or file name. - Each View in the UI is saved as a separate Photoshop layer. - </p> - <p> - In Photoshop (or similar program that accepts .psd files), you can hide, show or edit a - layer independently of others. When you save a layered screenshot, you can examine and - modify the image of an individual View object. This helps you experiment with design - changes. - </p> - </li> - <li> - The upper right-hand pane displays the <strong>Tree Overview</strong>, a smaller map - representation of the entire Tree View window. Use Tree Overview to identify the part of the - view tree that is being displayed in Tree View. - <p> - You can also use Tree Overview to move around in the Tree View pane. Click and drag - the shaded rectangle over an area to reveal it in Tree View. - </p> - </li> - <li> - The middle right-hand pane displays the <strong>Properties View</strong>, - a list of the properties for a selected View object. With Properties View, you can - examine all the properties without having to look at your application source. - <p> - The properties are organized by category. To find an individual property, expand - a category name by clicking the arrow on its left. This reveals all the properties - in that category. - </p> - </li> - <li> - The lower right-hand pane displays the <strong>Layout View</strong>, - a block representation of the UI. Layout View is another way to navigate through your UI. - When you click on a View object in Tree View, its position in the UI is highlighted. - Conversely, when you click in an area of Layout View, the View object for that area is - highlighted in Tree View. - <p> - The outline colors of blocks in Layout View provide additional information: - </p> - <ul> - <li> - Bold red: The block represents the the View that is currently selected in - Tree View. - </li> - <li> - Light red: The block represents the parent of the block outlined in bold red. - </li> - <li> - White: The block represents a visible View that is not a parent or child of the - View that is currently selected in Tree View. - </li> - </ul> - </li> -</ul> -<p> - When the UI of the current Activity changes, the View Hierarchy window is not automatically - updated. To update it, click <strong>Load View Hierarchy</strong> at the top of the window. -</p> -<p> - Also, the window is not updated if you switch to a new Activity. To update it, start by - clicking the window selection icon in the bottom left-hand corner of the window. This - navigates back to the Window Selection window. From this window, click the Android - component name of the new Activity and then click <strong>Load View Hierarchy</strong> - at the top of the window. -</p> -<p> - A screenshot of the View Hierarchy window appears in figure 2. -</p> -<img id="Fig2" src="{@docRoot}images/developing/hv_view_hierarchy_window.png" alt="" height="600"/> -<p class="img-caption"><strong>Figure 2.</strong> The View Hierarchy window</p> -<h3 id="indiView">Working with an individual View in Tree View</h3> -<p> - Each node in Tree View represents a single View. Some information is always visible. Starting - at the top of the node, you see the following: -</p> -<ol> - <li> - View class: The View object's class. - </li> - <li> - View object address: A pointer to View object. - </li> - <li> - View object ID: The value of the - <code><a href="{@docRoot}guide/topics/resources/layout-resource.html#idvalue">android:id</a> - </code> attribute. - </li> - <li> - Performance indicators: A set of three colored dots that indicate the rendering - speed of this View relative to other View objects in the tree. The three dots - represent (from left to right) the measure, layout, and draw times of the rendering. - <p> - The colors indicate the following relative performance: - </p> - <ul> - <li> - Green: For this part of the render time, this View is in the faster 50% of all - the View objects in the tree. For example, a green dot for the measure time means - that this View has a faster measure time than 50% of the View objects in the tree. - </li> - <li> - Yellow: For this part of the render time, this View is in the slower 50% of all - the View objects in the tree. For example, a yellow dot for the layout time means - that this View has a slower layout time than 50% of the View objects in the tree. - </li> - <li> - Red: For this part of the render time, this View is the slowest one in the tree. - For example, a red dot for the draw time means that this View takes the most - time to draw of all the View objects in the tree. - </li> - </ul> - </li> - <li> - View index: The zero-based index of the View in its parent View. If it is the only child, - this is 0. - </li> -</ol> -<p> - When you select a node, additional information for the View appears in a small window above - the node. When you click one of the nodes, you see the following: -</p> -<ul> - <li> - Image: The actual image of the View, as it would appear in the emulator. If the View has - children, these are also displayed. - </li> - <li> - View count: The number of View objects represented by this node. This includes the View - itself and a count of its children. For example, this value is 4 for a View that has 3 - children. - </li> - <li> - Render times: The actual measure, layout, and draw times for the View rendering, in - milliseconds. These represent the same values as the performance indicators mentioned in - the preceding section. - </li> -</ul> -<p> - An annotated screenshot of an individual node in the Tree View window appears in figure 3. -</p> -<img id="Fig3" src="{@docRoot}images/developing/hv_treeview_screenshot.png" alt="" height="600"/> -<p class="img-caption"><strong>Figure 3.</strong> An annotated node in Tree View</p> -<h3 id="hvdebugging">Debugging with View Hierarchy</h3> -<p> - The View Hierarchy window helps you debug an application by providing a static display - of the UI. The display starts with your application's opening screen. As you step through - your application, the display remains unchanged until you redraw it by invalidating and - then requesting layout for a View. -</p> -<p> - To redraw a View in the display: -</p> - <ul> - <li> - Select a View in Tree View. As you move up towards the root of the tree (to the - left in the Tree View), you see the highest-level View objects. Redrawing a high-level - object usually forces the lower-level objects to redraw as well. - </li> - <li> - Click <strong>Invalidate</strong> at the top of the window. This marks the View as - invalid, and schedules it for a redraw at the next point that a layout is requested. - </li> - <li> - Click <strong>Request Layout</strong> to request a layout. The View and its children - are redrawn, as well as any other View objects that need to be redrawn. - </li> - </ul> -<p> - Manually redrawing a View allows you to watch the View object tree and examine the properties of - individual View objects one step at a time as you go through breakpoints in your code. -</p> -<h3 id="hvoptimize">Optimizing with View Hierarchy</h3> -<p> - View Hierarchy also helps you identify slow render performance. You start by looking at the - View nodes with red or yellow performance indicators to identify the slower View objects. As you - step through your application, you can judge if a View is consistently slow or slow only in - certain circumstances. -</p> -<p> - Remember that slow performance is not necessarily evidence of a problem, especially for - ViewGroup objects. View objects that have more children and more complex View objects render - more slowly. -</p> -<p> - The View Hierarchy window also helps you find performance issues. Just by looking at the - performance indicators (the dots) for each View node, you can see which View objects are the - slowest to measure, layout, and draw. From that, you can quickly identify the problems you - should look at first. -</p> -<h2 id="pixelperfect">Examining and Designing User Interfaces with Pixel Perfect</h2> -<p> - Pixel Perfect is a tool for examining pixel properties and laying out UIs from a design drawing. -</p> -<h3 id="aboutpixelperfect">About the Pixel Perfect window</h3> -<p> - The Pixel Perfect window displays a magnified image of the screen that is currently - visible on the emulator or device. In it, you can examine the properties - of individual pixels in the screen image. You can also use the Pixel Perfect window - to help you lay out your application UI based on a bitmap design. -</p> -<p> - To see the Pixel Perfect window, run Hierarchy Viewer, as described in - the section <a href="#runhv">Running Hierarchy Viewer and choosing a window</a>. Next, click - <strong>Inspect Screenshot</strong> at the top of the device window. The Pixel Perfect window - appears. -</p> -<p> - In it, you see three panes: -</p> -<ul> - <li> - View Object pane: This is a hierarchical list of the View objects that are currently - visible on the device or emulator screen, including both the ones in your application and - the ones generated by the system. The objects are listed by their View class. - To see the class names of a View object's children, expand the View by clicking the - arrow to its left. When you click a View, its position is highlighted in the Pixel Perfect - pane on the right. - </li> - <li> - Pixel Perfect Loupe pane: This is the magnified screen image. It is overlaid by a grid in - which each square represents one pixel. To look at the information for a pixel, click in its - square. Its color and X,Y coordinates appear at the bottom of the pane. - <p> - The magenta crosshair in the pane corresponds to the positioning - crosshair in the next pane. It only moves when you move the crosshair in the next pane. - </p> - <p> - To zoom in or out on the image, use the <strong>Zoom</strong> slider at the bottom of - the pane, or use your mouse's scroll wheel. - </p> - <p> - When you select a pixel in the Loupe pane, you see the following information at the - bottom of the pane: - </p> - <ul> - <li> - Pixel swatch: A rectangle filled with the same color as the pixel. - </li> - <li> - HTML color code: The hexadecimal RGB code corresponding to the pixel color - </li> - <li> - RGB color values: A list of the (R), green (G), and blue (B) color values of the - pixel color. Each value is in the range 0-255. - </li> - <li> - X and Y coordinates: The pixel's coordinates, in device-specific pixel units. - The values are 0-based, with X=0 at the left of the screen and Y=0 at the top. - </li> - </ul> - </li> - <li> - Pixel Perfect pane: This displays the currently visible screen as it would appear in the - emulator. - <p> - You use the cyan crosshair to do coarse positioning. Drag the crosshair in the image, - and the Loupe crosshair will move accordingly. You can also click on a point in the - Pixel Perfect pane, and the crosshair will move to that point. - </p> - <p> - The image corresponding to the View object selected in the View Object pane is - outlined in a box that indicates the View object's position on the screen. For the - selected object, the box is bold red. Sibling and parent View objects have a light - red box. View objects that are neither parents nor siblings are in white. - </p> - <p> - The layout box may have other rectangles either inside or outside it, each of which - indicates part of the View. A purple or green rectangle indicates the View bounding box. - A white or black box inside the layout box represents the <strong>padding</strong>, the - defined distance between the View object's content and its bounding box. An outer white - or black rectangle represents the <strong>margins</strong>, the distance between the - View bounding box and adjacent View objects. The padding and margin boxes are white if - the layout background is black, and vice versa. - </p> - <p> - You can save the screen image being displayed in the Pixel Perfect pane as a PNG file. - This produces a screenshot of the current screen. To do this, click - <strong>Save as PNG</strong> at the top of the window. This displays a dialog, - in which you can choose a directory and filename for the file. - </p> - </li> -</ul> -<p> - The panes are not automatically refreshed when you change one of the View objects or go to - another Activity. To refresh the Pixel Perfect pane and the Loupe pane, click - <strong>Refresh Screenshot</strong> at the top of the window. This will change the panes - to reflect the current screen image. You still may need to refresh the View Object pane; - to do this, click <strong>Refresh Tree</strong> at the top of the window. -</p> -<p> - To automatically refresh the panes while you are debugging, set - <strong>Auto Refresh</strong> at the top of the window, and then set a refresh rate - with the <strong>Refresh Rate</strong> slider at the bottom of the Loupe pane. -</p> -<h3 id="overlays">Working with Pixel Perfect overlays</h3> -<p> - You often construct a UI based on a design done as a bitmap image. The Pixel Perfect window - helps you match up your View layout to a bitmap image by allowing you to load the bitmap as an - <strong>overlay</strong> on the screen image. -</p> -<p> - To use a bitmap image as an overlay: -</p> -<ul> - <li> - Start your application in a device or emulator and navigate to the Activity whose UI you - want to work with. - </li> - <li> - Start Hierarchy Viewer and navigate to the Pixel Perfect window. - </li> - <li> - At the top of the window, click <strong>Load Overlay</strong>. A dialog opens, prompting - for the image file to load. Load the image file. - </li> - <li> - Pixel Perfect displays the overlay over the screen image in the Pixel Perfect pane. The - lower left corner of the bitmap image (X=0, Y=<em>max value</em>) is anchored on the lower - leftmost pixel (X=0, Y=<em>max screen</em>) of the screen. - <p> - By default, the overlay has a 50% transparency, which allows you to see the screen - image underneath. You can adjust this with the <strong>Overlay:</strong> slider at the - bottom of the Loupe pane. - </p> - <p> - Also by default, the overlay is not displayed in the Loupe pane. To display it, - set <strong>Show in Loupe</strong> at the top of the window. - </p> - </li> -</ul> -<p> - The overlay is not saved as part of the screenshot when you save the screen image as a PNG - file. -</p> -<p> - A screenshot of the Pixel Perfect window appears in figure 4. -</p> -<img id="Fig4" src="{@docRoot}images/developing/hv_pixelperfect.png" - alt="" - height="600"/> -<p class="img-caption"><strong>Figure 4.</strong> The Pixel Perfect window</p> -<h2 id="layoutopt">Optimizing layouts with layoutopt</h2> -<p> - The <code>layoutopt</code> tool lets you analyze the XML files that define your - application's UI to find inefficiencies in the view hierarchy.</p> - -<p> - To run the tool, open a terminal and launch <code>layoutopt <xmlfiles></code> - from your SDK <code>tools/</code> directory. The <xmlfiles> argument is a space- - delimited list of resources you want to analyze, either uncompiled resource xml files or - directories of such files. -</p> -<p> - The tool loads the specified XML files and analyzes their definitions and - hierarchies according to a set of predefined rules. For every issue it detects, it - displays the following information: -</p> -<ul> - <li> - The filename in which the issue was detected. - </li> - <li> - The line number for the issue. - </li> - <li> - A description of the issue, and for some types of issues it also suggests a resolution. - </li> -</ul> -<p>The following is a sample of the output from the tool:</p> -<pre> -$ layoutopt samples/ -samples/compound.xml - 7:23 The root-level <FrameLayout/> can be replaced with <merge/> - 11:21 This LinearLayout layout or its FrameLayout parent is useless -samples/simple.xml - 7:7 The root-level <FrameLayout/> can be replaced with <merge/> -samples/too_deep.xml - -1:-1 This layout has too many nested layouts: 13 levels, it should have <= 10! - 20:81 This LinearLayout layout or its LinearLayout parent is useless - 24:79 This LinearLayout layout or its LinearLayout parent is useless - 28:77 This LinearLayout layout or its LinearLayout parent is useless - 32:75 This LinearLayout layout or its LinearLayout parent is useless - 36:73 This LinearLayout layout or its LinearLayout parent is useless - 40:71 This LinearLayout layout or its LinearLayout parent is useless - 44:69 This LinearLayout layout or its LinearLayout parent is useless - 48:67 This LinearLayout layout or its LinearLayout parent is useless - 52:65 This LinearLayout layout or its LinearLayout parent is useless - 56:63 This LinearLayout layout or its LinearLayout parent is useless -samples/too_many.xml - 7:413 The root-level <FrameLayout/> can be replaced with <merge/> - -1:-1 This layout has too many views: 81 views, it should have <= 80! -samples/useless.xml - 7:19 The root-level <FrameLayout/> can be replaced with <merge/> - 11:17 This LinearLayout layout or its FrameLayout parent is useless -</pre> diff --git a/docs/html/guide/developing/debugging/index.jd b/docs/html/guide/developing/debugging/index.jd deleted file mode 100644 index 0ad1a08..0000000 --- a/docs/html/guide/developing/debugging/index.jd +++ /dev/null @@ -1,188 +0,0 @@ -page.title=Debugging -@jd:body - - - <div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - - <ol> - <li><a href="#stack">Debugging Environment</a></li> - - <li><a href="#addltools">Additional Debugging Tools</a></li> - - <li><a href="#tips">Debugging Tips</a></li> - </ol> - </div> - </div> - - <p>The Android SDK provides most of the tools that you need to debug your applications. You need - a JDWP-compliant debugger if you want to be able to do things such as step through code, - view variable values, and pause execution of an application. If you are using Eclipse, a - JDWP-compliant debugger is already included and there is no setup required. If you are using - another IDE, you can use the debugger that comes with it and attach the debugger to a special - port so it can communicate with the application VMs on your devices. The main components that - comprise a typical Android debugging environment are:</p> - - <dl> - <dt><a href="{@docRoot}guide/developing/tools/adb.html"><strong>adb</strong></a></dt> - - <dd><code>adb</code> acts as a middleman between a device and your development system. It provides various - device management capabilities, including moving and syncing files to the emulator, running a - UNIX shell on the device or emulator, and providing a general means to communicate with - connected emulators and devices.</dd> - - <dt><a href="{@docRoot}guide/developing/debugging/ddms.html"><strong>Dalvik Debug Monitor - Server</strong></a></dt> - - <dd>DDMS is a graphical program that communicates with your devices through <code>adb</code>. DDMS can - capture screenshots, gather thread and stack information, spoof incoming calls and SMS - messages, and has many other features.</dd> - - <dt><strong><a href="{@docRoot}guide/developing/device.html">Device</a> or - <a href="{@docRoot}guide/developing/devices/index.html">Android Virtual Device</a></strong></dt> - - <dd>Your application must run in a device or in an AVD so that it can be debugged. An <code>adb</code> device - daemon runs on the device or emulator and provides a means for the <code>adb</code> host daemon to - communicate with the device or emulator.</dd> - - <dt><strong>JDWP debugger</strong></dt> - - <dd>The Dalvik VM (Virtual Machine) supports the JDWP protocol to allow debuggers to attach to - a VM. Each application runs in a VM and exposes a unique port that you can attach a debugger to - via DDMS. If you want to debug multiple applications, attaching to each port might become - tedious, so DDMS provides a port forwarding feature that can forward a specific VM's debugging - port to port 8700. You can switch freely from application to application by highlighting it in the - Devices tab of DDMS. DDMS forwards the appropriate port to port 8700. Most modern Java IDEs include a JDWP debugger, - or you can use a command line debugger such as <a href="http://download.oracle.com/javase/6/docs/technotes/tools/"> - <code>jdb</code></a>.</dd> - </dl> - - <h2>Debugging Environment</h2> - - <p>Figure 1 shows how the various debugging tools work together in a typical - debugging environment.</p> - <img src="{@docRoot}images/debugging.png" - alt="Debugging workflow" /> - <p class="img-caption><strong>Figure 1. </strong> Debugging Workflow</p> - - <p>On your emulator or device, each application runs in its own instance of a Dalvik VM. The <code>adb</code> - device daemon allows communication with the VMs from an outside party.</p> - - <p>On your development machine, the <code>adb</code> host daemon communicates with the <code>adb</code> device daemon and - allows tools such as DDMS to communicate with the device or emulator. The <code>adb</code> host daemon also - allows you to access shell commands on the device as well as providing capabilities such as - application installation and file transferring.</p> - - <p>Each application VM on the device or emulator exposes a debugging port that you can attach to - via DDMS. DDMS can forward any of these ports to a static debugging port (typically port 8700) by - selecting the application that you want to debug in the DDMS user interface. A JDWP debugger can - attach to this static debugging port and debug all the applications that are running on the - device or emulator without having to attach to multiple ports.</p> - - <p>If you are using Eclipse, much of these interconnections are hidden from you. DDMS, <code>adb</code>, and a - JDWP debugger are all setup for you and you can access them through the Debug and DDMS - perspectives in Eclipse. If you are developing in a non-Eclipse environment, you have to invoke - these tools manually.</p> - - <h2 id="addltools">Additional Debugging Tools</h2> - - <p>In addition to the main debugging tools, the Android SDK provides additional tools to help you - debug and profile your applications:</p> - - <dl> - <dt><strong><a href="{@docRoot}guide/developing/debugging/debugging-ui.html">Heirarchy Viewer - and layoutopt</a></strong></dt> - - <dd>Graphical programs that let you debug and profile user interfaces.</dd> - - <dt><strong><a href= - "{@docRoot}guide/developing/debugging/debugging-tracing.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/debugging/debugging-devtools.html">Dev Tools - Android application</a></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. You can also transfer the - application to a hardware device.</dd> - </dl> - - - <h2 id="tips">Debugging Tips</h2> - -<p>While debugging, keep these helpful tips in mind to help you figure out common problems with your -applications:</p> - -<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 <code>ps</code> to find the process you -want, and then <code>kill -3</code>. 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="{@docRoot}guide/developing/debugging/debugging-devtools.html"> -Debugging with the Dev Tools App</a>. -</dd> - -<dt><strong>Get application and system state information from the emulator</strong></dt> -<dd>You can access dumpstate information from the <code>adb shell</code> commands. 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 DDMS. -From the <strong>Device</strong> menu, select <strong>Dump -radio state</strong>.</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/debugging/debugging-tracing.html">Profiling with Traceview and -dmtracedump</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> - -<dt><strong>Garbage collection</strong></dt> -<dd> -The debugger and garbage collector are currently loosely integrated. The VM guarantees that any -object the debugger is aware of is not garbage collected until after the debugger disconnects. -This can result in a buildup of objects over time while the debugger is connected. For example, -if the debugger sees a running thread, the associated {@link java.lang.Thread} object is not -garbage collected even after the thread terminates. -</dd> - -</dl> - -<p>See the <a href="{@docRoot}resources/faq/troubleshooting.html">Troubleshooting</a> document -for answers to some common developing and debugging issues.</p> - - - - - - - |