This page offers an introduction to developing and debugging applications on Android. It teaches how to create, build, run and debug your Android code. Alternatively, you may like to begin with the Hello Android tutorial.
Developing on Android Hardware
The first Android device, the T-Mobile G1 has arrived! If you've got your hands on one and want to use it (instead of the emulator) to develop and debug applications, there are just a few things you need to know.
To 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 Installing the Eclipse Plugin (ADT) for more information.
The 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:
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.
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.
The ADT plugin creates these folders and files for you as appropriate for the type of project:
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 as appropriate for your Eclipse version:
Once 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 launch configuration manager. See Creating a Launch Configuration for information about how to access the launch configuration manager..
Running or debugging the application triggers these actions:
The recommended way to develop an Android application is to use Eclipse with the ADT plugin. This plugin provides editing, building, and debugging functionality integrated right into the IDE.
However, if you'd rather develop your application in another IDE, such as IntelliJ, or use Eclipse without the ADT plugin, you can do that instead. The SDK provides the tools you need to set up, build, and debug your application.
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:
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 <folder>
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 projectHere'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 adb 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).
Use the Ant build.xml
file generated by
activityCreator
to build your application.
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:\Programs\Java\
. The easiest solution, however, is to install JDK in a non-space directory, for example: c:\java\jdk1.6.0_02
.
To run a compiled
application, you will upload the .apk file to the /data/app/
directory
in the emulator using the adb tool as described here:
<your_sdk_dir>/tools/emulator
from the command line)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 <your_sdk_dir>/sample/LunarLander
and type ../../tools/adb install bin/LunarLander.apk
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.
This 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.
DDMS 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.
If you have an Android device, you can develop and debug your Android applications just as usual. Launching your apps on a device works just the same as on the emulator, but there are a few things to do before you can start.
In Eclipse, you can do this from the Application tab when viewing the Manifest
(on the right side, set Debuggable to true). Otherwise, in the AndroidManifest.xml
file, add android:debuggable="true"
to the <application>
element.
On the T-Mobile G1, go to the home screen, press MENU, select Applications > Development, then enable USB debugging.
/etc/udev/rules.d/50-android.rules
.
For Gusty/Hardy, edit the file to read:
SUBSYSTEM=="usb", SYSFS{idVendor}=="0bb4", MODE="0666"
For Dapper, edit the file to read:
SUBSYSTEM=="usb_device", SYSFS{idVendor}=="0bb4", MODE="0666"
chmod a+rx /etc/udev/rules.d/50-android.rules
You can verify that your device is connected by executing adb devices
from your
SDK tools/ directory. If connected, you'll see the device name listed as a "device."
If using Eclipse, select run or debug as usual. You will be presented with a Device Chooser dialog that lists the available emulator(s) and connected device(s). Select the device to install and run the application there.
If using the Android Debug Bridge (adb),
you can issue commands with the -d
flag to target your connected device.
The information about signing your applications has moved to Signing and Publishing Your Applications.
The Android SDK includes a set of sample applications that demonstrate much of the functionality and API usage needed for your applications. The ApiDemos package is preinstalled on the emulator, so you can access it by starting an emulator and sliding open the home screen's application drawer.
You can find the source code corresponding to the ApiDemos apps in <SDK>/samples/ApiDemos
.
Take a look to learn more about how it is implemented.
If you want, you can load the ApiDemos sample applications as source projects and modify them, then run them in the emulator. However, to do so, you need to uninstall the preinstalled version of ApiDemos first. If you try to run or modify ApiDemos from your development environment without removing the preinstalled version first, you will get an install error.
For information about how to uninstall and then reinstall ApiDemos so that you can work with them in your development environment, see the troubleshooting topic I can't install ApiDemos apps in my IDE because of a signing error.
Android has a fairly extensive set of tools to help you debug your programs:
...
I/MemoryDealer( 763): MemoryDealer (this=0x54bda0): Creating 2621440 bytes heap at 0x438db000
I/Logger( 1858): getView() requesting item number 0
I/Logger( 1858): getView() requesting item number 1
I/Logger( 1858): getView() requesting item number 2
D/ActivityManager( 763): Stopping: HistoryRecord{409dbb20 com.android.home.AllApps}
...
Android Log - 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.
Also, see the Troubleshooting section of the doc to figure out why your application isn't appearing on the emulator, or why it's not starting.
Android 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):
These settings will be remembered across emulator restarts.
adb shell
, use "ps" to find the process you
want, and then "kill -3 ". The stack trace appears in the log file.
adb shell logcat -b radio
Android 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 .dex 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, Android provides tools for other IDEs to build and debug Android applications, but they are not as integrated.
To remove an application that you have installed on the emulator, you will
need to run adb 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
.
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 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".
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).
In Eclipse/ADT, you can add JUnit test classes to your application. However, you need to set up a custom JUnit configuration before your tests will run properly. For detailed information about how to set up the JUnit configuration, see the troubleshooting topic I can't run a Junit test class in Eclipse.