docs/html/guide/developing/debugging/index.jd

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>