The Android Development Tools (ADT) plugin for Eclipse adds powerful extensions to the Eclipse
integrated development environment. It allows you to create and debug Android applications easier
and faster. If you use Eclipse, the ADT plugin gives you an incredible boost in developing Android
- It gives you access to other Android development tools from inside the Eclipse IDE. For
example, ADT lets you access the many capabilities of the DDMS tool: take screenshots, manage
port-forwarding, set breakpoints, and view thread and process informationd irectly from Eclipse.
- It provides a New Project Wizard, which helps you quickly create and set up all of the
basic files you'll need for a new Android application.
- It automates and simplifies the process of building your Android application.
- It provides an Android code editor that helps you write valid XML for your Android
manifest and resource files.
- It will even export your project into a signed APK, which can be distributed to users.
To begin developing Android applications in the Eclipse IDE with ADT, you first need to
download the Eclipse IDE and then download and install the ADT plugin. To do so, follow the
steps given in Installing
the ADT Plugin.
If you are already developing applications using a version of ADT earlier than 0.9, make
sure to upgrade to the latest version before continuing. See the guide to
Updating Your Eclipse ADT Plugin.
Note: This guide assumes you are using the latest version of
the ADT plugin. While most of the information covered also applies to previous
versions, if you are using an older version, you may want to consult this document from
the set of documentation included in your SDK package (instead of the online version).
Creating an Android Project
The ADT plugin provides a New Project Wizard that you can use to quickly create a new
Android project (or a project from existing code). To create a new project:
- Select File > New > Project.
- Select Android > Android Project, and click
- Select the contents for the project:
- Enter a Project Name. This will be the name of the folder where your
project is created.
- Under Contents, select Create new project in workspace.
Select your project workspace location.
- Under Target, select an Android target to be used as the project's Build Target.
The Build Target
specifies which Android platform you'd like your application built against.
Unless you know that you'll be using new APIs introduced in the latest SDK, you should
select a target with the lowest platform version possible, such as Android 1.1.
Note: You can change your the Build Target for your
project at any time: Right-click the project in the Package Explorer, select
Properties, select Android and then check
the desired Project Target.
- Under Properties, fill in all necessary fields.
- Enter an Application name. This is the human-readable title for your
application — the name that will appear on the Android device.
- Enter a Package name. This is the package namespace (following the same rules
as for packages in the Java programming language) where all your source code
- Select Create Activity (optional, of course, but common) and enter a name
for your main Activity class.
- Enter a Min SDK Version. This is an integer that indicates
the minimum API Level required to properly run your application.
Entering this here automatically sets the
minSdkVersion attribute in the
of your Android Manifest file. If you're unsure of the appropriate API Level to use,
copy the API Level listed for the Build Target you selected in the Target tab.
- Click Finish.
You can also start the New Project Wizard from the New icon in the toolbar.
Once you complete the New Project Wizard, ADT creates the following
folders and files in your new project:
- Includes your stub Activity Java file. All other Java files for your application
<Android Version>/ (e.g.,
- Includes the
android.jar file that your application will build against.
This is determined by the build target that you have chosen in the New Project
- This contains the Java files generated by ADT, such as your
and interfaces created from AIDL files.
- This is empty. You can use it to store raw asset files. See
Resources and Assets.
- A folder for your application resources, such as drawable files, layout files, string
values, etc. See
Resources and Assets.
- The Android Manifest for your project. See
- This file contains project settings, such as the build target. This files is integral
to the project, as such, it should be maintained in a Source Revision Control system.
It should never be edited manually — to edit project properties,
right-click the project folder and select "Properties".
Running Your Application
Wait! Before you can run your application on the Android Emulator,
you must create an Android Virtual Device (AVD).
An AVD is a configuration that specifies the Android platform to be used on the emulator.
You can read more in the Android Virtual
Devices document, but if you just want to get started, follow the simple guide below to
create an AVD.
If you will be running your applications only on actual device hardware, you do not
need an AVD — see
Developing On a Device for information
on running your applicaiton.
Creating an AVD
To avoid some explanation that's beyond the scope of this document, here's the
basic procedure to create an AVD:
- Open a command-line (e.g.,"Command Prompt" application on Windows, or "Terminal"
on Mac/Linux) and navigate to your SDK package's
- First, you need to select a Deployment Target. To view available targets, execute:
android list targets
This will output a list of available Android targets, such as:
Name: Android 1.1
API level: 2
Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P
Name: Android 1.5
API level: 3
Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P
Find the target that matches the Android platform upon which you'd like
to run your application. Note the integer value of the
you'll use this in the next step.
- Create a new AVD using your selected Deployment Target. Execute:
android create avd --name <your_avd_name> --target <targetID>
- Next, you'll be asked whether you'd like to create a custom hardware profile.
If you respond "yes," you'll be presented with a series of prompts to define various aspects of the
device hardware (leave entries blank to use default values, which are shown in brackets). Otherwise,
press return to use all default values ("no" is the default).
That's it; your AVD is ready. In the next section, you'll see how the AVD is used
when launching your application on an emulator.
To learn more about creating and managing AVDs, please read the
Android Virtual Devices
Running your application
Note: Before you can run your application, be sure that
you have created an AVD with a target that satisfies your application's Build Target.
If an AVD cannot be found that meets the requirements of your Build Target, you will see
a console error telling you so and the launch will be aborted.
To run (or debug) your application, select Run > Run (or
Run > Debug) from the Eclipse main menu. The ADT plugin
will automatically create a default launch configuration for the project.
When you choose to run or debug your application, Eclipse will perform the following:
- Compile the project (if there have been changes since the last build).
- Create a default launch configuration (if one does not already exist for the project).
- Install and start the application on an emulator or device (based on the Deployment Target
defined by the run configuration).
By default, Android application 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 debugging, the application will start in the "Waiting For Debugger" mode. Once the
debugger is attached, Eclipse will open the Debug perspective.
To set or change the launch configuration used for your project, use the launch configuration manager.
Creating a Launch Configuration for information.
Creating a Run Configuration
The run configuration specifies the project to run, the Activity
to start, the emulator options 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 setting don't suit your project, you can
customize the launch configuration or even create a new.
To create or modify a launch configuration, follow these steps as appropriate
for your Eclipse version:
- Open the run configuration manager.
- In Eclipse 3.3 (Europa), select Run >
Open Run Dialog (or Open Debug Dialog)
- In Eclipse 3.4 (Ganymede), select Run >
Run Configurations (or
- Expand the Android Application item and create a new
configuration or open an existing one.
- To create a new configuration:
- Select Android Application and click the New launch configuration
icon above the list (or, right-click Android Application and click
- Enter a Name for your configuration.
- In the Android tab, browse and select the project you'd like to run with the
- To open an existing configuration, select the configuration name from the list
nested below Android Application.
- Adjust your desired launch configuration settings.
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
Automatic and manual target modes
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:
- If there's a device or emulator already running and its AVD configuration
meets the requirements of the application's build target, the application is installed
and run upon it.
- If there's more than one device or emulator running, each of which meets the requirements
of the build target, a "device chooser" is shown to let you select which device to use.
- If there are no devices or emulators running that meet the requirements of the build target,
ADT looks at the available AVDs. If one meets the requirements of the build target,
the AVD is used to launch a new emulator, upon which the application is installed and run.
- If all else fails, the application will not be run and you will see a console error warning
you that there is no existing AVD that meets the build target requirements.
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.
Signing your Applications
As you begin developing Android applications, understand that all
Android applications must be digitally signed before the system will install
them on an emulator or an actual device. There are two ways to do this:
with a debug key (for immediate testing on an emulator or development device)
or with a private key (for application distribution).
The ADT plugin helps you get started quickly by signing your .apk files with
a debug key, prior to installing them on an emulator or development device. This means that you can
quickly run your application from Eclipse without having to
generate your own private key. No specific action on your part is needed,
provided ADT has access to Keytool.However, please note that if you intend
to publish your application, you must sign the application with your
own private key, rather than the debug key generated by the SDK tools.
Please read Signing Your
Applications, which provides a thorough guide to application signing on Android
and what it means to you as an Android application developer. The document also includes
a guide to exporting and signing your application with the ADT's Export Wizard.
Executing arbitrary Java expressions in Eclipse
You can execute arbitrary code when paused at a breakpoint in Eclipse. For example,
when in a function with a String argument called "zip", you can get
information about packages and call class methods. You can also invoke arbitrary
static methods: for example, entering
Open a code execution window, select Window>Show
View>Display from the main menu to open the
Display window, a simple text editor. Type your expression, highlight the
text, and click the 'J' icon (or CTRL + SHIFT + D) to run your
code. The code runs in the context of the selected thread, which must be
stopped at a breakpoint or single-step point. (If you suspend the thread
manually, you have to single-step once; this doesn't work if the thread is
If you are currently paused on a breakpoint, you can simply highlight and execute
a piece of source code by pressing CTRL + SHIFT + D.
You can highlight a block of text within the same scope by pressing ALT +SHIFT
+ UP ARROW to select larger and larger enclosing blocks, or DOWN ARROW to select
Here are a few sample inputs and responses in Eclipse using the Display window.
You can also execute arbitrary code when not debugging by using a scrapbook page.
Search the Eclipse documentation for "scrapbook".
Running DDMS Manually
Although the recommended way to debug is to use the ADT plugin, you can manually run
DDMS and configure Eclipse to debug on port 8700. (Note: Be sure that you
have first started DDMS).