The Android DDMS Quick-Start Guide

The Dalvik Debug

Monitor Service (DDMS) is a debugging tool provided with Android Software Development Kit (SDK). Developers use DDMS to provide a window into the emulator or the actual phone for debugging purposes as well as file and process management. It’s a blend of several tools: a Task Manager, a File Explorer, an Emulator console, and a Logging console.This Quick-Start Guide is not complete documentation of the DDMS functionality. Instead, it is designed to get you up and running with common tasks. See the DDMS documentation provided with Android SDK for a complete list of features. Using DDMS with Eclipse and as a Stand-Alone Application If you use Eclipse with the Android Development Tools plug-in, the DDMS tool is tightly integrated with your development environment as a perspective. By using the DDMS Perspective (shown in Figure B.1, using the File Explorer to browse files on the emulator instance), you can explore any emulator instances running on the development machine and any Android devices connected via USB. If you’re not using Eclipse, the DDMS tool is also available within the /tools directory of Android SDK and you can launch it as a separate application, in which case it runs in its own process, as shown in Figure B.2 (sending an SMS message to the emulator). Tip There should be only one instance of the DDMS tool running at a given time. This includes the Eclipse perspective. Other DDMS launches are ignored; if you have Eclipse running and try to launch DDMS from the command line, you might see question marks instead of process names, and you see a debug output saying the instance of DDMS is being ignored. The Android DDMS Quick-Start Guide d. Getting Up to Speed Using Key Features of DDMS Whether you use DDMS from Eclipse or as a stand-alone tool, be aware of a few key features: n A list of running emulators and connected devices displays in the top-left corner. 636 Appendix B The Android DDMS Quick-Start Guide Working with Processes 637 n The File Explorer enables you to browse files on the emulator or device (including application files, directories, and databases) and pull and push files to the Android system. n The LogCat window enables you to monitor the Android Logging console (LogCat).This is where calls to Log.i(), Log.e(), and other Log messages display. n You can inspect individual processes (heap and thread updates).You can inspect individual threads.You can kill processes.You can prompt garbage collection on a process and then view the Heap for that application. n You can track application memory allocation using the Allocation Tracker pane. n You can take remote screenshots of the emulator or the device using the Screen Capture button. n You have some helpful Emulator console functionality at your fingertips, such as the ability to send GPS information and to simulate incoming calls and SMS messages. Some functionality applies only to the Eclipse DDMS Perspective; you can click on an individual process in an emulator or device and click the little green bug to attach a debugger to that process and debug using Eclipse, provided you have the source code open in the workspace.The process is similar if you’re using another debugger, such as JSwat or jdebug. Working with Processes One of the most useful features of DDMS is the ability to interact with processes.As you might remember, each Android application runs in its own VM with its own user id on the operating system. Using the left pane of DDMS, you can browse all instances of the VM running on a device, each identified by its package name.You can n Attach and debug applications in Eclipse n Monitor threads n Monitor the heap n Stop processes n Force Garbage Collection (GC) For example, in Figure B.3, there is a package named com.androidbook.myfirstandroidapp running on the emulator. You can see the application’s thread data in the right-hand pane. 638 Appendix B The Android DDMS Quick-Start Guide Attaching a Debugger to an Android Application Although you’ll use the Eclipse debug configurations to launch and debug your applications most of the time, you can also use DDMS to choose which application to debug and attach directly.To attach a debugger to a process, you need to have the package source code open in your Eclipse workspace. Now perform the following steps to debug: 1. On the emulator or device, verify that the application you want to debug is running. 2. In DDMS, find that application’s package name and highlight it. 3. Click the little green bug button ( ) to debug that application. 4. Switch to the Debug Perspective of Eclipse as necessary; debug as you would normally. Monitoring Thread Activity of an Android Application You can use DDMS to monitor thread activity of an individual Android application. For an example of DDMS monitoring the threading activity of an application, refer to Figure B.3. Follow these steps: 1. On the emulator or device, verify that the application you want to monitor is running. Figure B.3 Using DDMS to display thread information about an application. Working with Processes 639 2. In DDMS, find that application’s package name and highlight it. 3. Click the three black arrows button ( ) to display the threads of that application. They appear in the right portion of the Threads tab.This data updates every four seconds by default. 4. On the Threads tab, you can choose a specific thread and press the Refresh button to drill down within that thread.The resulting Classes in use display below. Note You can also start thread profiling using the button with three black arrows and a red dot ( ). Prompting Garbage Collection (GC) You can use DDMS to force the Garbage Collector (GC) to run by following these steps: 1. On the emulator or device, verify that the application you want to run GC is running. 2. In DDMS, find that application’s package name and highlight it. 3. Click the garbage can button ( ) to cause garbage collection to run for the application.You can also do this from the Heap tab, as detailed next. Monitoring Heap Activity You can use DDMS to monitor heap statistics of an individual Android application.The heap statistics are updated after every GC. For an example of DDMS monitoring the heap status of an application, see Figure B.4. Follow these steps: 1. On the emulator or device, verify that the application you want to monitor is running. 2. In DDMS, find that application’s package name and highlight it. 3. Click the green cylinder button ( ) to display the heap information for that application.The statistics appear in the right portion of the Heap tab.This data updates after every GC.You can also cause GC operations from the Heap tab using the button Cause GC. 4. On the Heap tab, you can choose a specific type of object.The resulting graph in use displays at the bottom of the Heap tab, as shown in Figure B.4

Monitoring Memory Allocation

You can use DDMS to monitor memory allocated by a specific Android application.The memory allocation statistics are updated on demand by the developer. Follow these steps to track memory allocations: 1. On the emulator or device, verify that the application you want to monitor is running. 2. In DDMS, find that application’s package name and highlight it. 3. Switch to the Allocation Tracker tab on the right pane. 4. Click the Start Tracking button to start tracking memory allocations and the Get Allocations to get the allocations at a given time. 5. To stop tracking allocations, click the Stop Tracking button. The Android developer website has a write-up on how to track memory allocations at http://developer.android.com/resources/articles/track-mem.html. Stopping a Process You can use DDMS to kill an Android application by following these steps: 1. On the emulator or device, verify that the application you want to stop is running. 2. In DDMS, find that application’s package name and highlight it. 3. Click the red stop sign button ( ) to stop that process.