Doc change: Debugging section of dev guide restructuring
Change-Id: I1dc371d181800cb1b68bfa0f7a229f6447992052
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
new file mode 100644
index 0000000..d92fb3c
--- /dev/null
+++ b/docs/html/images/debug-ddms.png
Binary files differ
diff --git a/docs/html/images/debugging.png b/docs/html/images/debugging.png
new file mode 100644
index 0000000..fd6a41a
--- /dev/null
+++ b/docs/html/images/debugging.png
Binary files differ
