diff options
author | Robert Ly <robertly@google.com> | 2010-12-16 17:26:11 -0800 |
---|---|---|
committer | Robert Ly <robertly@google.com> | 2010-12-29 12:43:23 -0800 |
commit | ce4d229afcc156885f084ac0f0cbaf1661c3dd19 (patch) | |
tree | 6bb47ac8fcde56b674ff2127a9fcb4bbaa1f1746 /docs/html | |
parent | 4105f1e9459854b57810cd1446c41d8a1c52b118 (diff) | |
download | frameworks_base-ce4d229afcc156885f084ac0f0cbaf1661c3dd19.zip frameworks_base-ce4d229afcc156885f084ac0f0cbaf1661c3dd19.tar.gz frameworks_base-ce4d229afcc156885f084ac0f0cbaf1661c3dd19.tar.bz2 |
Doc change: Debugging section of dev guide restructuring
Change-Id: I1dc371d181800cb1b68bfa0f7a229f6447992052
Diffstat (limited to 'docs/html')
-rw-r--r-- | docs/html/guide/developing/debugging/ddms.jd | 284 | ||||
-rw-r--r-- | docs/html/guide/developing/debugging/debugging-devtools.jd | 82 | ||||
-rw-r--r-- | docs/html/guide/developing/debugging/debugging-log.jd | 305 | ||||
-rw-r--r-- | docs/html/guide/developing/debugging/debugging-projects-cmdline.jd | 76 | ||||
-rw-r--r-- | docs/html/guide/developing/debugging/debugging-projects.jd | 65 | ||||
-rw-r--r-- | docs/html/guide/developing/debugging/debugging-tips.jd | 83 | ||||
-rw-r--r-- | docs/html/guide/developing/debugging/debugging-tracing.jd | 402 | ||||
-rw-r--r-- | docs/html/guide/developing/debugging/debugging-ui.jd | 201 | ||||
-rw-r--r-- | docs/html/guide/developing/debugging/index.jd | 109 | ||||
-rw-r--r-- | docs/html/images/debug-ddms.png | bin | 0 -> 195963 bytes | |||
-rw-r--r-- | docs/html/images/debugging.png | bin | 0 -> 35399 bytes |
11 files changed, 1607 insertions, 0 deletions
diff --git a/docs/html/guide/developing/debugging/ddms.jd b/docs/html/guide/developing/debugging/ddms.jd new file mode 100644 index 0000000..218ea44 --- /dev/null +++ b/docs/html/guide/developing/debugging/ddms.jd @@ -0,0 +1,284 @@ +page.title=Using the Dalvik Debug Monitor Server +@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></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.example.android.notepad</code>, that is running in the emulator + has the debugging port 8700 assigned to it as well as 8609. This signifies that DDMS is currently + forwarding port 8609 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/.ddmsrc</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>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>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. + If you want more granular control over where allocation data is collected, use the + {@link android.os.Debug#startAllocCounting()} and {@link android.os.Debug#stopAllocCounting()} + methods.</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>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>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="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>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="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 new file mode 100644 index 0000000..d0af1c5 --- /dev/null +++ b/docs/html/guide/developing/debugging/debugging-devtools.jd @@ -0,0 +1,82 @@ +page.title=Debugging with the Dev Tools App +@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 application's state, see + <a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime Changes</a>.</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 new file mode 100644 index 0000000..6ee69c7 --- /dev/null +++ b/docs/html/guide/developing/debugging/debugging-log.jd @@ -0,0 +1,305 @@ +page.title=Reading and Writing Log Messages +@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 originating process (the default + format).</li> + + <li><code>process</code> — Display PID only.</li> + + <li><code>tag</code> — Display the priority/tag only.</li> + + <li><code>thread</code> — Display process:thread and 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 + originating process.</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>
\ No newline at end of file diff --git a/docs/html/guide/developing/debugging/debugging-projects-cmdline.jd b/docs/html/guide/developing/debugging/debugging-projects-cmdline.jd new file mode 100644 index 0000000..f7be0d6 --- /dev/null +++ b/docs/html/guide/developing/debugging/debugging-projects-cmdline.jd @@ -0,0 +1,76 @@ +page.title=Debugging Projects in other IDEs +@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 new file mode 100644 index 0000000..d4818ce --- /dev/null +++ b/docs/html/guide/developing/debugging/debugging-projects.jd @@ -0,0 +1,65 @@ +page.title=Debugging Android Projects in Eclipse +@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-tips.jd b/docs/html/guide/developing/debugging/debugging-tips.jd new file mode 100644 index 0000000..fc2ec54 --- /dev/null +++ b/docs/html/guide/developing/debugging/debugging-tips.jd @@ -0,0 +1,83 @@ +page.title=Debugging Tips +@jd:body + +<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> +</dl> + +<p>See the <a href="{@docRoot}resources/faq/troubleshooting.html">Troubleshooting</a> document +for answers to some common developing and debugging issues.</p> + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/html/guide/developing/debugging/debugging-tracing.jd b/docs/html/guide/developing/debugging/debugging-tracing.jd new file mode 100644 index 0000000..cfa1bb1 --- /dev/null +++ b/docs/html/guide/developing/debugging/debugging-tracing.jd @@ -0,0 +1,402 @@ +page.title=Profiling with Traceview and dmtracedump +@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="/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="/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> + </dd> + </dl> + + + + <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 new file mode 100644 index 0000000..eba5bf1 --- /dev/null +++ b/docs/html/guide/developing/debugging/debugging-ui.jd @@ -0,0 +1,201 @@ +page.title=Debugging and Profiling User Interfaces +@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> + <ul> + <li><a href="#layoutview">Layout View</a></li> + + </li> + + <li><a href="#layoutopt">Optimizing Layouts with <code>layoutopt</code></a></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 Layout View) and a magnified + inspector of the display (the Pixel Perfect View).</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> + + <p>To get the Hierarchy Viewer started:</p> + + <ol> + <li>Connect your device or launch an emulator.</li> + + <li>From a terminal, launch <code>hierarchyviewer</code> from the <code><sdk>/tools/</code> + directory.</li> + + <li>In the window that opens, you'll see a list of <strong>Devices</strong>. When a device is + selected, a list of currently active <strong>Windows</strong> is displayed on the right. The + <em><Focused Window></em> is the window currently in the foreground, and also the default + window loaded if you do not select another.</li> + + <li>Select the window that you'd like to inspect and click <strong>Load View + Hierarchy</strong>. The Layout View will be loaded. You can then load the Pixel Perfect View by + clicking the second icon at the bottom-left of the window.</li> + </ol> + + <p>If you've navigated to a different window on the device, press <strong>Refresh + Windows</strong> to refresh the list of available windows on the right.</p> + + + <h3 id="layoutview">Layout View</h3> + + <p>The Layout View offers a look at the View layout and properties. It has three views:</p> + + <ul> + <li>Tree View: a hierarchy diagram of the Views, on the left.</li> + + <li>Properties View: a list of the selected View's properties, on the top-right.</li> + + <li>Wire-frame View: a wire-frame drawing of the layout, on the bottom-right.</li> + </ul><br /> + <img src="{@docRoot}images/hierarchyviewer-layout.png" + alt="" + height="509" + width="700" /> + <p class="img-caption"><strong>Figure 1.</strong> Screenshot of Hierarchy Viewer</p> + + <p>Select a node in the Tree View to display the properties of that element in the Properties + View. When a node is selected, the Wire-frame View also indicates the bounds of the element with + a red rectangle. Double click a node in the tree (or select it, and click <strong>Display + View</strong>) to open a new window with a rendering of that element.</p> + + <p>The Layout View includes a couple other helpful features for debugging your layout: + <strong>Invalidate</strong> and <strong>Request Layout</strong>. These buttons execute the + respective View calls, {@link android.view.View#invalidate()} and {@link + android.view.View#requestLayout()}, on the View element currently selected in the tree. Calling + these methods on any View can be very useful when simultaneously running a debugger on your + application.</p> + + <p>The Tree View can be resized by adjusting the zoom slider, below the diagram. The number of + View elements in the window is also given here. You should look for ways to minimize the number + of Views. The fewer View elements there are in a window, the faster it will perform.</p> + + <p>If you interact with the device and change the focused View, the diagram will not + automatically refresh. You must reload the Layout View by clicking <strong>Load View + Hierarchy</strong>.</p> + + <h3>Pixel Perfect View</h3> + + <p>The Pixel Perfect View provides a magnified look at the current device window. It helps you + design your UI better by giving you a closer look at your UI's image quality, alignment, and other + aesthetic qualities. It has three views:</p> + + <ul> + <li>Explorer View: shows the View hierarchy as a list, on the left.</li> + + <li>Normal View: a normal view of the device window, in the middle.</li> + + <li>Loupe View: a magnified, pixel-grid view of the device window, on the right.</li> + </ul><br /> + <img src="{@docRoot}images/hierarchyviewer-pixelperfect.png" + alt="" + height="509" + width="700" /> + + <p>Click on an element in the Explorer View and a "layout box" will be drawn in the Normal View + to indicate the layout position of that element. The layout box uses multiple rectangles, to + indicate the normal bounds, the padding and the margin (as needed). The purple or green rectangle + indicates the normal bounds of the element (the height and width). The inner white or black + rectangle indicates the content bounds, when padding is present. A black or white rectangle + outside the normal purple/green rectangle indicates any present margins. (There are two colors + for each rectangle, in order to provide the best contrast based on the colors currently in the + background.)</p> + + <p>A very handy feature for designing your UI is the ability to overlay an image in the Normal + and Loupe Views. For example, you might have a mock-up image of how you'd like to layout your + interface. By selecting <strong>Load...</strong> from the controls in the Normal View, you can + choose the image from your computer and it will be placed atop the preview. Your chosen image + will anchor at the bottom left corner of the screen. You can then adjust the opacity of the + overlay and begin fine-tuning your layout to match the mock-up.</p> + + <p>The Normal View and Loupe View refresh at regular intervals (5 seconds by default), but the + Explorer View does not. If you navigate away and focus on a different View, then you should + refresh the Explorer's hierarchy by clicking <strong>Load View Hierarchy</strong>. This is even + true when you're working in a window that holds multiple Views that are not always visible. If + you do not, although the previews will refresh, clicking a View in the Explorer will not provide + the proper layout box in the Normal View, because the hierarchy believes you are still focused on + the prior View.</p> + + <p>Optional controls include:</p> + + <ul> + <li><strong>Overlay</strong>: Load an overlay image onto the view and adjust its opacity.</li> + + <li><strong>Refresh Rate</strong>: Adjust how often the Normal and Loupe View refresh their + display.</li> + + <li><strong>Zoom</strong>: Adjust the zoom level of the Loupe View.</li> + </ul> + + <h2 id="layoutopt">Optimizing layouts with layoutopt</h2> + <p>The <code>layoutopt</code> tool lets you analyze the XML files that represent your application's layout + and finds ineffiencies in the view hierarchy.</p> + + <p>To run the tool, open a terminal and launch <code>layoutopt <resources></code> from your + SDK <code>tools/</code> directory. In the command, supply a list of uncompiled resource xml files + or directories that you want to analyze.</p> + + <p>When run, the tool loads the specified XML files and analyzes their layout structures and + hierarchies according to a set of predefined rules. If it detects issues, it outputs information + about the issues, giving filename, line numbers, description of issue, and for some types of + issues a suggested resolution.</p> + + <p>Here's an example of the output:</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> + +<p> +For more information on running the tool, see the +<a href="${@docRoot}guide/developing/tools/layoutopt.html">layoutopt</a> reference.</p> + + + + + + + + diff --git a/docs/html/guide/developing/debugging/index.jd b/docs/html/guide/developing/debugging/index.jd new file mode 100644 index 0000000..0107621 --- /dev/null +++ b/docs/html/guide/developing/debugging/index.jd @@ -0,0 +1,109 @@ +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> + </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/tools/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><a href="{@docRoot}guide/developing/devices/avds-devices.html"><strong>Device or + Emulator</strong></a></dt> + + <dd>Your application must run in a device or emulator 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.</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="/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>
\ No newline at end of file diff --git a/docs/html/images/debug-ddms.png b/docs/html/images/debug-ddms.png Binary files differnew file mode 100644 index 0000000..d92fb3c --- /dev/null +++ b/docs/html/images/debug-ddms.png diff --git a/docs/html/images/debugging.png b/docs/html/images/debugging.png Binary files differnew file mode 100644 index 0000000..fd6a41a --- /dev/null +++ b/docs/html/images/debugging.png |