Eclipse and ADT provide an environment where most of the details of the build process are hidden from you. By default, the build process constantly runs in the background as you make changes to your project.
When Eclipse automatically builds your application, it enables debugging and signs the
.apk with a debug key, by default. When you run the application, Eclipse invokes ADB and installs your application to a device or emulator, so you do not have to manually perform these tasks. Since most of the build process is taken care of by Eclipse, the following topics show you how to run an application, which will automatically build your application as well.
To distribute your application, however, you must build your application in release mode and sign the
.apk file with your own private key.
This document shows you how to run your application on an emulator or a real device from Eclipse—all of which is done using the debug version of your application. For more information about how to sign your application with a private key for release, see Signing Your Applications
Before you can run your application on the Android Emulator, you must create an AVD.
To run (or debug) your application, select Run > Run (or Run > Debug) from the Eclipse menu bar. The ADT plugin will automatically create a default run configuration for the project. Eclipse will then perform the following:
By default, Android run configurations use an "automatic target" mode for selecting a device target. For information on how automatic target mode selects a deployment target, see Automatic and manual target modes below.
If you run the application with the Debug option, the application will start in the "Waiting For Debugger" mode. Once the debugger is attached, Eclipse opens the Debug perspective and starts the application's main activity. Otherwise, if you run the application with the normal Run option, Eclipse installs the application on the device and launches the main activity.
To set or change the run configuration used for your project, use the run configuration manager. See the section below about Creating a Run Configuration for more information.
Be certain to create multiple AVDs upon which to test your application. You should have one AVD for each platform and screen type with which your application is compatible. For instance, if your application compiles against the Android 1.5 (API Level 3) platform, you should create an AVD for each platform equal to and greater than 1.5 and an AVD for each screen type you support, then test your application on each one.
Before you can run your application on a device, you must perform some basic setup for your device:
android:debuggableattribute of the
true. As of ADT 8.0, this is done by default when you build in debug mode.
Read Using Hardware Devices for more information.
Once set up and your device is connected via USB, install your application on the device by selecting Run > Run (or Run > Debug) from the Eclipse menu bar.
The run configuration specifies the project to run, the Activity to start, the emulator or connected device to use, and so on. When you first run a project as an Android Application, ADT will automatically create a run configuration. The default run configuration will launch the default project Activity and use automatic target mode for device selection (with no preferred AVD). If the default settings don't suit your project, you can customize the run configuration or even create a new one.
To create or modify a run configuration, refer to the Eclipse documentation on how to create Run configurations. The following steps highlight the important things you need to do for an Android project:
In the Target tab, consider whether you'd like to use Manual or Automatic mode when selecting an AVD to run your application. See the following section on Automatic and manual target modes).
You can specify any emulator options to the Additional Emulator Command Line Options field. For example, you could add
-scale 96dpi to scale the AVD's screen to an accurate size, based on the dpi of your computer monitor. For a full list of emulator options, see the Android Emulator document.
By default, a run configuration uses the automatic target mode in order to select an AVD. In this mode, ADT will select an AVD for the application in the following manner:
However, if a "preferred AVD" is selected in the run configuration, then the application will always be deployed to that AVD. If it's not already running, then a new emulator will be launched.
If your run configuration uses manual mode, then the "device chooser" is presented every time that your application is run, so that you can select which AVD to use.