Installing on a Device

To debug programs on actual hardware you must declare the application to be debuggable in the Android manifest, configure both the phone and the development computer for hardware debugging, connect the phone to the development computer with a USB cable, and transfer the executable to the device from the development computer. We first describe how to configure for debugging, and then how to transfer the executables.

Configuring for Debugging on Actual Devices

We summarize the basics; a more extensive discussion may be found in the Android Setting up a Device for Development document.

1. Configuring the phone may be somewhat device-specific but here are two representative examples: On both the T-Mobile HTC G1 and the AT&T Motorola Backflip, choose Menu > Settings > Applications > Development and enable the USB debugging option. The following figure illustrates for a Motorola Backflip phone.
   
   
   
   
   

   We have also checked "Stay awake" to cause the screen to stay on while the phone is charging on the USB cable; it is generally useful in debugging for the screen to stay on.

   
   


2. Connect the device to your development computer with a USB cable appropriate for the device. If you get the display in the following figure,
   
   
   you can select Charge Only unless you intend to manually transfer files to or from the device SD card: Eclipse or the ADB bridge will still load executables to the phone and execute them with this mode selected.


3. Declare the application to be "debuggable" in the Android manifest in one of two ways:


• In Eclipse, select AndroidManifest.xml in the left panel, and in the right panel select the Application tab at the bottom. Then set Dubuggable to true in the corresponding Attributes dropdown menu .


• In the AndroidManifest.xml file, add android:debuggable="true" as an attribute of the <application> element. For example,

  
  <application android:icon="@drawable/icon" android:label="@string/app_name" android:debuggable="true">
      <activity android:name=".Mapper" android:label="@string/app_name">
          <intent-filter>
              <action android:name="android.intent.action.MAIN" />
              <category android:name="android.intent.category.LAUNCHER" />
          </intent-filter>
      </activity>
      <uses-library android:name="com.google.android.maps" />	
  </application>
  
  

  The selection of debuggable=true from the user interface in option (a) automatically makes this insertion in the AndroidManifest.xml file.

  
  


4. Configuration of the development computer depends on the operating system:


• For Windows, you need to install an Android USB driver. Here are the detailed instructions. These drivers work for several phones (e.g., T-Mobil G1, Google Ion, Verizon Droid, Nexus One, ...) but for some phones you may need to obtain drivers directly from the phone manufacturer. Do a Web search for information on the relevant phone if the above drivers don't work for the device you are using.


• The claim is that Macs don't require additional drivers; I have not tested this broadly but my Motorola Backflip phone worked immediately when plugged into a Mac.


• For Linux, a rules file with a single line for each device must be installed:


1. Log in as root and create a file /etc/udev/rules.d/51-android.rules that contains a line for each device to be used. Some examples:
   
   
   • Under Fedora 8 or 12 with a Motorola Backflip, the /etc/udev/rules.d/51-android.rules file contains a line:

     
       SUBSYSTEM=="usb", SYSFS{idVendor}=="22b8", MODE="0666"
     
     

     where 22b8 is the vendor ID for Motorola (table of vendor IDs)
   
   
   • Under Fedora with a Samsung Galaxy S (vendor ID 04e8):

     
       SUBSYSTEM=="usb", SYSFS{idVendor}=="04e8", MODE="0666"
     
     

   
   
   • Under Ubuntu 7.10 or 8.04 with an HTC phone (vendor ID 0bb4):

     
       SUBSYSTEM=="usb", SYSFS{idVendor}=="0bb4", MODE="0666"
     
     

   
   
   • Under Ubuntu 6.06 with an HTC phone:

     
     SUBSYSTEM=="usb_device", SYSFS{idVendor}=="0bb4", MODE="0666"
     
     

   For other Linux systems it is likely that one of the above patterns will work (with the appropriate vendor ID).
   
   
2. Execute chmod a+r /etc/udev/rules.d/51-android.rules to make the rules file readable by all.


5. To verify that your device is connected after the above steps, issue at a shell prompt adb devices (where adb is in the tools subdirectory of the SDK: we are assuming that you added this directory to your path earlier). Your device should appear in the list of devices that this command produces. For example, on my Fedora Linux system a typical result would be

   
     [guidry@m33 ~]$ adb devices
     List of devices attached
     TA5380467L      device
     emulator-5554   device
   
   

   In this output, emulator-5554 is the Simple2.2 emulator for Android 2.2 that we configured earlier (5554 is the port number associated with the virtual device) and TA5380467L is a Motorola Backflip phone that was connected to the computer according to the above instructions

Now that we have the device connected to the computer, we can install Android packages that we have developed and debug directly on the phone. Let's see how to do that.

Installing and Debugging Applications on the Device

To install an application on a physical device connected to your development computer by a USB cable as described above, you have two options:

• The app is installed through the .apk file, which is in the bin subdirectory of the Eclipse project. Thus one option is to issue from a shell prompt adb install <path to .apk file>. After doing this you should see the application in the list of apps that you get by clicking the MENU button on the phone.


• Alternatively, execute the app using Eclipse (right-click on the project name in the left panel and choose Run As > Android Application) and choose the device for output in the resulting Android Device Chooser window, as illustrated in the following figure.
  
  
  
  With the physical device (first line) selected, clicking OK will both install the app in the appropriate directory on the phone and execute the application on the phone if there are no errors.

Android requires that all applications installed on physical devices be digitally signed by the developer. If you deploy apps for 3rd-party installation through the channels such as the Android Market you must sign them with your own digital signature, but in development and debugging using Eclipse this isn't necessary because "under the hood" a debug certificate associated with the development machine is used automatically. If you debug on a device using a particular computer, the app will be installed using the debug certificate associated with that machine. If you leave the app installed and then attempt to debug the same device on a different computer you will get an error message in the logcat stream that the application signatures do not match. For example,

[2010-06-08 10:34:06 - MapTutorial] Installing MapTutorial.apk...
[2010-06-08 10:34:08 - MapTutorial] Re-installation failed due to different application signatures.
[2010-06-08 10:34:08 - MapTutorial] You must perform a full uninstall of the application. 
                       WARNING: This will remove the application data!
[2010-06-08 10:34:08 - MapTutorial] Please execute 'adb uninstall com.lightcone.maptutorial' in a shell.
[2010-06-08 10:34:08 - MapTutorial] Launch canceled!

In this case, use the uninstall command described below first to remove the application from the device, and then repeat the install as described above.

Uninstalling Applications from the Device

To uninstall an application resident on a physical device connected by USB:

1. Issue from the command line of a shell adb devices to get a list of currently-running devices and their serial numbers.


2. Issue the command adb -s <serialNumber> uninstall appname, where <serialNumber> is the serial number for the device and appname is the fully qualified name of the app package. For example,

[guidry@m33 ~]$ adb devices
List of devices attached
TA5380467L      device
emulator-5554   device

[guidry@m33 ~]$ adb -s TA5380467L uninstall com.lightcone.recipes
Success

If you know there is only a single device running, you can shorten the above to adb -d uninstall appname (the -d flag targets the only physical device running). For example,

[guidry@m33 workspaceAndroid]$ adb -d uninstall com.lightcone.recipes
Success

(This returns an error if more than one physical device is running.)