Doc change: Debugging section of dev guide restructuring

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>.

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>

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>

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