Installing the SDKThis page describes how to install the
Android SDK and set up your development environment. If you haven't downloaded the SDK yet, you can use the link below to get started.
Contents
System and Software Requirements Developing Android Applications on Eclipse
System and Software RequirementsTo develop Android applications using
the code and tools in the Android SDK, you need a suitable development
computer and development environment, as described below.
Supported Operating Systems
- Windows XP or Vista
- Mac OS X 10.4.8 or later (x86 only)
- Linux (tested on Linux Ubuntu Dapper Drake)
Supported Development Environments
- Eclipse
- 3.2, 3.3 (Europa)
- (optional)
- Other development environments or IDEs
- (JRE alone is not sufficient)
- Not compatible with Gnu Compiler for Java (gcj)
- 1.6.5 or later for Linux and Mac, 1.7 or later for Windows
Installing
the SDKAfter downloading the SDK, unpack the .zip archive to a suitable
location on your machine. For the rest of this document, we will refer
to the directory where you installed the SDK as $SDK_ROOT.
Optionally, you can add $SDK_ROOT/tools to your path:
- On Linux, edit your ~/.bash_profile or ~/.bashrc file. Look for
a line that sets the PATH environment variable and add the full path to
your $SDK_ROOT/tools to it. If you don't see a line setting the path,
you can add one:
- On
a Mac, look in your home directory for .bash_profile and proceed as for
Linux. You can create the .bash_profile, if you haven't already set one
up on your machine.
- On Windows, right click on My Computer, and
select Properties. Under the Advanced tab, hit the Environment
Variables button, and in the dialog that comes up, double-click on Path
under System Variables, and add the full path to the tools/ directory
under $SDK_ROOT to it.
Adding $SDK_ROOT/tools to your path lets you run Android Debug Bridge (adb) and the other command line
without needing to supply the full path to the tools directory. Note
that, if you update your SDK, you should remember to update your PATH
settings to point to the new location, if different.
Installing the Eclipse Plugin (ADT)If you will be using the Eclipse IDE
as your environment for developing Android applications, you can
install a custom plugin called Android Development Tools (ADT), which
adds integrated support for Android projects and tools. The ADT plugin
includes a variety of powerful extensions that make creating, running,
and debugging Android applications faster and easier.
If you
will not be using the Eclipse IDE, you do not need to download or install the ADT plugin.
To download and install the ADT plugin, set up an Eclipse remote update site as described in the steps below.
- Start Eclipse, then select Help > Software Updates > Find and Install....
- In the dialog that appears, select Search for new features to install and press Next.
- Press New Remote Site.
- In
the resulting dialog box, enter a name for the remote site (e.g.
Android Plugin) and enter this as its URL:
eclipse/. Press OK.
- You should now see the new site added to the search list (and checked). Press Finish.
- In the subsequent Search Results dialog box, select the checkbox for Android Plugin > Eclipse Integration > Android Development Tools and press Next.
- Read the license agreement and then select Accept terms of the license agreement, if appropriate. Press Next.
- Press Finish.
- The ADT plugin is not signed; you can accept the installation anyway by pressing Install All.
- Restart Eclipse.
- After restart, update your Eclipse preferences to point to the SDK root directory ($SDK_ROOT):
- Select Window > Preferences... to open the Preferences panel. (Mac OS X: Eclipse > Preferences)
- Select Android from the left panel.
- For the SDK Location in the main panel, press Browse... and find the SDK root directory.
- Press Apply, then OK
Updating the ADT Plugin To update the ADT plugin to the latest version, follow these steps:
- Select Help > Software Updates > Find and Install....
- Select Search for updates of the currently installed features and press Finish.
- If any update for ADT is available, select and install.
Alter
natively,
- Select Help > Software Updates > Manage Configuration.
- Navigate down the tree and select Android Development Tools
- Select Scan for Updates under Available Tasks.
Developing
Android Applications on EclipseTo begin developing Android applications
in the Eclipse IDE, you first create an Android project and then set up
a launch configuration. After that, you can write, run, and debug your
application.
The sections below provide instructions assuming that you have
installed the ADT plugin in your Eclipse environment. If you haven't
installed the ADT plugin, you should do that before using the
instructions below. See the
for more information. Creating an Android ProjectThe ADT plugin
provides a New Project Wizard that you can use to quickly create an
Eclipse project for new or existing code. To create the project, follow
these steps:
- Select File > New > Project
- Select Android > Android Project, and press Next
- Select the contents for the project:
- Select Create new project in workspace
to start a project for new code. Enter the project name, the base
package name, the name of a single Activity class to create as a stub .java file, and a name to use for your application.
- Select Create project from existing source to
start a project from existing code. Use this option if you want to
build and run any of the sample applications included with the SDK. The
sample applications are located in the samples/ directory in the SDK.
Browse to the directory containing the existing source code and click
OK. If the directory contains a valid Android manifest file, the ADT
plugin fills in the package, activity, and application names for you.
- Press Finish.
The ADT plugin creates the these folders and files for you as appropriate for the type of project:
- src/ A folder that includes your stub .java Activity file.
- res/ A folder for your resources.
- AndroidManifest.xml The manifest for your project.
Creating
a Launch Configuration Before you can run and debug your application in
Eclipse, you must create a launch configuration for it. A launch
configuration specifies the project to launch, the Activity to start,
the emulator options to use, and so on.
To create a launch configuration for the application, follow these steps:
- Select Run > Open Run Dialog... or Run > Open Debug Dialog... as appropriate.
- In the project type list on the left, right-click Android Application and select New.
- Enter a name for your configuration.
- On the Android tab, browse for the project and Activity to start.
- On the Emulator tab, set the desired screen and network properties, as well as any other .
- You can set additional options on the Common tab as desired.
- Press Apply to save the launch configuration, or press Run or Debug (as appropriate).
Running
and Debugging an ApplicationOnce you've set up the project and launch
configuration for your application, you can run or debug it as
described below.
From the Eclipse main menu, select
Run >
Run or
Run >
Debug
as appropriate, to run or debug the active launch configuration. Note
that the active launch configuration is the one most recently selected
in the Run configuration manager. It does not necessarily correspond to
the application that is selected in the Eclipse Navigation pane (if
any).
To set or change the active launch configuration, use the Run configuration manager, which you can access through
Run >
Open Run Dialog... or
Run >
Open Debug Dialog....
Running or debugging the application triggers these actions:
- Starts the emulator, if it is not already running.
- Compiles the project, if there have been changes since the last build, and installs the application on the emulator.
- Run starts the application.
- Debug
starts the application in "Wait for debugger" mode, then opens the
Debug perspective and attaches the Eclipse Java debugger to the
application.
Developing Android Applications with Other IDEs and ToolsThe recommended way to develop an Android application is to use
Eclipse with the Android plugin.
This plugin provides editing, building, and debugging functionality
integrated right into the IDE. However, the SDK includes tools to
enable you to develop with other IDEs, including intelliJ (or if you'd
rather use Eclipse without the plugin).
Creating an Android Project The Android SDK includes activityCreator, a
program that generates a number of stub files for your project, as well
as a build file. You can use the program to create an Android project
for new code or from existing code, such as the sample applications
included in the SDK. For Linux and Mac, the SDK provides
activityCreator.py, a Python script, and for Windows,
activityCreator.bat, a batch script. Regardless of platform, you can
use activityCreator in the same way.
To run activityCreator and create an Android project, follow these steps:
- In the command line, change to the tools/ directory of
the SDK and create a new directory for your project files. If you are
creating a project from existing code, change to the root folder of
your application instead.
- Run activityCreator. In the command,
you must specify a fully-qualified class name as an argument. If you
are creating a project for new code, the class represents the name of a
stub class that the script will create. If you are creating a project
from existing code, you must specify the name of one Activity class in
the package. Command options for the script include:
- --out
which sets the output directory. By default, the output
directory is the current directory. If you created a new directory for
your project files, use this option to point to it.
- --ide intellij, which generates IntelliJ IDEA project files in the newly created project
Here's an example:
~/android_linux_sdk/tools$ ./activityCreator.py --out
myproject your.package.name.ActivityName package:
your.package.name out_dir: myproject
activity_name: ActivityName ~/android_linux_sdk/tools$
The activityCreator script generates the following files and
directories (but will not overwrite existing ones):
- AndroidManifest.xml The application manifest file, synced to the specified Activity class for the project.
- build.xml An Ant file that you can use to build/package the application.
- src/your/package/name/ActivityName.java The Activity class you specified on input.
- your_activity.iml, your_activity.ipr, your_activity.iws [only with the -ide intelliJ flag] intelliJ project files.
- res/ A directory to hold resources.
- src/ The source directory.
- bin/ The output directory for the build script.
You can now move your folder wherever you want for development, but keep in mind that you'll have to use the program in the tools/ folder to send files to the emulator, so you'll need access between your solution and the tools/ folder.
Also, you should refrain from moving the location of the SDK directory,
since this will break the build scripts (they will need to be manually
updated to reflect the new SDK location before they will work again).
Building an Android ApplicationUse the Ant build.xml file generated by activityCreator to build your application.
- If you don't have it, you can obtain Ant from the . Install it and make sure it is on your executable path.
- Before
calling Ant, you need to declare the JAVA_HOME environment variable to
specify the path to where the JDK is installed. Note: When installing
JDK on Windows, the default is to install in the "Program Files"
directory. This location will cause ant to fail, because of the space.
To fix the problem, you can specify the JAVA_HOME variable like this:
set JAVA_HOME=c:\Prora~1\Java\. The easiest solution, however, is to
install JDK in a non-space directory, for example: c:\java\jdk1.6.0_02.
- If you have not done so already, follow the instructions for Creating a New Project above to set up the project.
- You
can now run the Ant build file by simply typing ant in the same folder
as the build.xml file for your project. Each time you change a source
file or resource, you should run ant again and it will package up the
latest version of the application for you to deploy.
Running
an Android ApplicationTo run a compiled application, you will upload
the .apk file to the /data/app/ directory in the emulator using the tool as described here:
- Start the emulator (run $SDK_HOME/tools/emulator from the command line)
- On
the emulator, navigate to the home screen (it is best not to have that
application running when you reinstall it on the emulator; press the Home key to navigate away from that application).
- Run adb install myproject/bin/<appname>.apk
to upload the executable. So, for example, to install the Lunar Lander
sample, navigate in the command line to $SDK_ROOT/sample/LunarLander
and type ../../tools/adb install bin/LunarLander.apk
- In the emulator, open the list of available applications, and scroll down to select and start your application.
Note:
When you install an Activity for the first time, you might have to
restart the emulator before it shows up in the application launcher, or
other applications can call it. This is because the package manager
usually only examines manifests completely on emulator startup.
Attaching a Debugger to Your ApplicationThis section describes how to
display debug information on the screen (such as CPU usage), as well as
how to hook up your IDE to debug running applications on the emulator.
Attaching a debugger is automated using the Eclipse plugin, but you can
configure other IDEs to listen on a debugging port to receive debugging
information.
- Start the , which acts as a port forwarding service between your IDE and the emulator.
- Set optional debugging configurations on your emulator,
such as blocking application startup for an activity until a debugger
is attached. Note that many of these debugging options can be used
without DDMS, such as displaying CPU usage or screen refresh rate on
the emulator.
- Configure your IDE to attach to port 8700 for debugging. We include information on .
Configuring
your IDE to attach to the debugging portDDMS will assign 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.
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.
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.
DebuggingAndroid has a fairly extensive set of tools to help you debug your programs:
-
- A graphical program that supports port forwarding (so you can set up
breakpoints in your code in your IDE), screen captures on the emulator,
thread and stack information, and many other features. You can also run
logcat to retrieve your Log messages. See the linked topic for more
information.
-
- Dumps a log of system messages. The messages include a stack trace
when the emulator throws an error, as well as Log messages. To run
logcat, see the linked topic. ...I/MemoryDealer( 763): MemoryDealer
(this=0x54bda0): Creating 2621440 bytes heap at 0x438db000I/Logger(
1858): getView() requesting item number 0I/Logger( 1858): getView()
requesting item number 1I/Logger( 1858): getView() requesting item
number 2D/ActivityManager( 763): Stopping: HistoryRecord{409dbb20
com.google.android.home.AllApps}...
- -
A logging class to print out messages to a log file on the emulator.
You can read messages in real time if you run logcat on DDMS (covered
next). Add a few logging method calls to your code.
To use the Log class, you just call Log.v() (verbose), Log.d() (debug),
Log.i() (information), Log.w() (warning) or Log.e (error) depending on
the importance you wish to assign the log message.
Log.i("MyActivity", "MyClass.getView() — Requesting item number " + position) You can use logcat to read these messages
- -
Android can save a log of method calls and times to a logging file that
you can view in a graphical reader called Traceview. See the linked
topic for more information.
- Eclipse plugin
- The Eclipse Android plugin incorporates a number of these tools (ADB,
DDMS, logcat output, and other functionality). See the linked topic for
more information.
- Debug and Test Device Settings - Android exposes several settings that expose useful information such as CPU usage and frame rate. See below.
Also, see the section of the doc to figure out why your application isn't appearing on the emulator, or why it's not starting.
Debug and Test Settings on the DeviceAndroid lets you set a number of
settings that will make it easier to test and debug your applications.
To get to the development settings page on the emulator, go to
Dev Tools >
Development Settings. This will open the development settings page with the following options (among others):
- Debug app Selects the application that will
be debugged. You do not need to set this to attach a debugger, but
setting this value has two effects:
- It will prevent Android from throwing an error if you pause on a breakpoint for a long time while debugging.
- It will enable you to select the Wait for Debugger option to pause application startup until your debugger attaches (described next).
- Wait for debugger
Blocks the selected application from loading until a debugger
attaches. This way you can set a breakpoint in 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 to your code.
- Immediately destroy activities
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
/
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.
- Show screen updates
Flashes a momentary pink rectangle on any screen sections that are
being redrawn. This is very useful for discovering unnecessary screen
drawing.
- Show CPU usage 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. Note: You cannot turn this feature off once it is on, without restarting the emulator.
- Show screen FPS Displays the current frame rate. Mostly useful for games to see the overall frame rate they are achieving. Note: You cannot turn this feature off once it is on without restarting the emulator.
- Show background
Displays a background pattern when no activity screens are visible.
This typically does not happen, but can happen during debugging.
These settings will be remembered across emulator restarts.
Top Debugging TipsQuick stack dump To obtain a stack dump from
emulator, you can log in with adb shell, use "ps" to find the process
you want, and then "kill -3 ". The stack trace appears in the log file.
Displaying useful info on the emulator screen The device can display
useful information such as CPU usage or highlights around redrawn
areas. Turn these features on and off in the developer settings window
as described in .
Getting system state information from the emulator (dumpstate) You can
access dumpstate information from the Dalvik Debug Monitor Service
tool. See
on the adb topic page. Getting application state information from the
emulator (dumpsys) You can access dumpsys information from the Dalvik
Debug Monitor Service tool. See
on the adb topic page. Getting wireless connectivity information You
can get information about wireless connectivity using the Dalvik Debug
Monitor Service tool. From the
Device menu, select
"Dump radio state". Logging Trace Data You can log method calls and
other tracing data in an activity by calling
android.os.Debug.startMethodTracing(). See
for details. Logging Radio Data By default, radio information is not
logged to the system (it is a lot of data). However, you can enable
radio logging using the following commands: adb shelllogcat -b
radioRunning adb Android ships with a tool called adb that provides
various capabilities, including moving and syncing files to the
emulator, forwarding ports, and running a UNIX shell on the emulator.
See
for details. Getting screen captures from the emulator Dalvik Debug
Monitor Server (DDMS) can capture screenshots from the emulator. Using
debugging helper classes Android provides debug helper classes such as and
for your convenience. Building and Installing an Android
ApplicationAndroid requires custom build tools to be able to properly
build the resource files and other parts of an Android application.
Because of this, you must have a specialized build environment for your
application.
Custom Android compilation steps include compiling the XML and other
resource files, and creating the proper output format. A compiled
Android application is an .apk file, which is a compressed file
containing
files, resource files, raw data files, and other files. You can create
a properly structured Android project either from scratch, or from
existing source files.
Android does not currently support development of third party applications in native code (C/C++).
The recommended way to develop an Android application is to
use Eclipse with the Android plugin, which provides support for building, running, and debugging Android applications.
If you have another IDE, to build and debug Android applications, but they are not as integrated.
Removing an Android ApplicationTo remove an application that you have installed on the emulator, you will need to
and delete the .apk file you sent to the emulator when you installed
it. Use adb shell to drop into a shell on the device as described in
the linked topic, navigate to data/app/, and then remove the file using
rm
your_app.apk.
Eclipse Tips Executing arbitrary Java expressions in EclipseYou 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
android.os.Debug.startMethodTracing() will start dmTrace.
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 in Object.wait().)
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 smaller blocks.
Here are a few sample inputs and responses in Eclipse using the Display window.
| Input | Response |
| zip | (java.lang.String) /work/device/out/linux-x86-debug/android/app/android_sdk.zip |
| zip.endsWith(".zip") | (boolean) true |
| zip.endsWith(".jar") | (boolean) false |
You
can also execute arbitrary code when not debugging by using a scrapbook
page. Search the Eclipse documentation for "scrapbook".
Running DDMS ManuallyAlthough 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 ).
