Doc change: Debugging section of dev guide restructuring

Change-Id: I1dc371d181800cb1b68bfa0f7a229f6447992052

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> &gt; <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).&nbsp; This is very useful for testing the {@link
+    android.app.Activity#onSaveInstanceState} / {@link
+    android.app.Activity#onCreate(android.os.Bundle)} code path, which would otherwise be difficult
+    to force. Choosing this option will probably reveal a number of problems in your application
+    due to not saving state. 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() &mdash; get item number " + position);
+</pre>
+
+  <p>The LogCat will then output something like:</p>
+  <pre class="no-pretty-print">
+I/MyActivity( 1557): MyClass.getView() &mdash; 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 [&lt;option&gt;] ... [&lt;filter-spec&gt;] ...
+</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&nbsp;&lt;filename&gt;</code></td>
+
+      <td>Writes log message output to <code>&lt;filename&gt;</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&nbsp;&lt;count&gt;</code></td>
+
+      <td>Sets the maximum number of rotated logs to <code>&lt;count&gt;</code>. The default value
+      is 4. Requires the <code>-r</code> option.</td>
+    </tr>
+
+    <tr>
+      <td><code>-r&nbsp;&lt;kbytes&gt;</code></td>
+
+      <td>Rotates the log file every <code>&lt;kbytes&gt;</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&nbsp;&lt;format&gt;</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> &mdash; Verbose (lowest priority)</li>
+
+        <li><code>D</code> &mdash; Debug</li>
+
+        <li><code>I</code> &mdash; Info</li>
+
+        <li><code>W</code> &mdash; Warning</li>
+
+        <li><code>E</code> &mdash; Error</li>
+
+        <li><code>F</code> &mdash; Fatal</li>
+
+        <li><code>S</code> &mdash; 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>&lt;priority&gt;/&lt;tag&gt;</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 &mdash; 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 &mdash; 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> &mdash; Display priority/tag and PID of originating process (the default
+    format).</li>
+
+    <li><code>process</code> &mdash; Display PID only.</li>
+
+    <li><code>tag</code> &mdash; Display the priority/tag only.</li>
+
+    <li><code>thread</code> &mdash; Display process:thread and priority/tag only.</li>
+
+    <li><code>raw</code> &mdash; Display the raw log message, with no other metadata fields.</li>
+
+    <li><code>time</code> &mdash; Display the date, invocation time, priority/tag, and PID of the
+    originating process.</li>
+
+    <li><code>long</code> &mdash; 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 &lt;format&gt;]
+</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> &mdash; View the buffer that contains radio/telephony related
+    messages.</li>
+
+    <li><code>events</code> &mdash; View the buffer containing events-related messages.</li>
+
+    <li><code>main</code> &mdash; View the main log buffer (default)</li>
+  </ul>
+
+  <p>The usage of the <code>-b</code> option is:</p>
+  <pre>
+[adb] logcat [-b &lt;buffer&gt;]
+</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 &gt; Open Perspective &gt;
+  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 &gt; Open Perspective &gt;
+  DDMS</strong>. If DDMS does not appear, go to <strong>Window &gt; Open Perspective &gt; 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&rsquo;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 &gt;
+  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   &lt;init&gt;    ()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>&lt;trace-base-name&gt;.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>&lt;trace-base-name&gt;.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
+  &lt;trace-base-name&gt;</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>&lt;ref&gt;
+      <em>callname</em> (&lt;inc-ms&gt;, &lt;exc-ms&gt;,&lt;numcalls&gt;)</code>, where</p>
+
+      <ul>
+        <li><code>&lt;ref&gt;</code> -- Call reference number, as used in trace logs</li>
+
+        <li><code>&lt;inc-ms&gt;</code> -- Inclusive elapsed time (milliseconds spent in method,
+        including all child methods)</li>
+
+        <li><code>&lt;exc-ms&gt;</code> -- Exclusive elapsed time (milliseconds spent in method,
+        not including any child methods)</li>
+
+        <li><code>&lt;numcalls&gt;</code> -- Number of calls</li>
+      </ul>
+
+      <p>The usage for dmtracedump is:</p>
+      <pre>
+dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] &lt;trace-base-name&gt;
+</pre>
+
+      <p>The tool then loads trace log data from <code>&lt;trace-base-name&gt;.data</code> and
+      <code>&lt;trace-base-name&gt;.key</code>. The table below lists the options for dmtracedump.</p>
+
+      <table>
+        <tr>
+          <th>Option</th>
+
+          <th>Description</th>
+        </tr>
+
+        <tr>
+          <td><code>-d&nbsp;&lt;trace-base-name&gt;</code></td>
+
+          <td>Diff with this trace name</td>
+        </tr>
+
+        <tr>
+          <td><code>-g&nbsp;&lt;outfile&gt;</code></td>
+
+          <td>Generate output to &lt;outfile&gt;</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&nbsp;&lt;trace-base-name&gt;</code></td>
+
+          <td>URL base to the location of the sortable javascript file</td>
+        </tr>
+
+        <tr>
+          <td><code>-t&nbsp;&lt;percent&gt;</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>&lt;sdk&gt;/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>&lt;Focused Window&gt;</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 &lt;resources&gt;</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 &lt;FrameLayout/&gt; can be replaced with &lt;merge/&gt;
+   11:21 This LinearLayout layout or its FrameLayout parent is useless
+samples/simple.xml
+   7:7 The root-level &lt;FrameLayout/&gt; can be replaced with &lt;merge/&gt;
+samples/too_deep.xml
+   -1:-1 This layout has too many nested layouts: 13 levels, it should have &lt;= 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 &lt;FrameLayout/&gt; can be replaced with &lt;merge/&gt;
+   -1:-1 This layout has too many views: 81 views, it should have &lt;= 80!
+samples/useless.xml
+   7:19 The root-level &lt;FrameLayout/&gt; can be replaced with &lt;merge/&gt;
+   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
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