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.
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 the 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 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:\Prora~1\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.apkNote: 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.
The Android system requires that all installed applications are digitally signed — the system will not install or run an application that is not signed appropriately. This applies wherever the Android system is run, whether on an actual device or on the emulator. For this reason, you must set up signing for your application before you will be able to run or debug it on an emulator or device.
The important points to understand about signing Android applications are:
The Android SDK tools assist you in signing your applications when debugging. Both the ADT Plugin for Eclipse and the Ant build tool offer two signing modes — debug mode and release mode.
To support the generation of a keystore and debug key, you should first make sure that Keytool is available to the SDK build tools. In most cases, you can tell the SDK build tools how to find Keytool by making sure that your JAVA_HOME environment variable is set and that it references a suitable JDK. Alternatively, you can add the JDK version of Keytool to your PATH variable.
If you are developing on a version of Linux that originally came with Gnu Compiler for Java, make sure that the system is using the JDK version of Keytool, rather than the gcj version. If Keytool is already in your PATH, it might be pointing to a symlink at /usr/bin/keytool. In this case, check the symlink target to make sure that it points to the Keytool in the JDK.
If you are developing in Eclipse and have set up Keytool as described above, signing in debug mode is enabled by default. When you run or debug your app, ADT signs the .apk for you and installs it on the emulator. No specific action on your part is needed, provided ADT has access to Keytool.
To compile your application in release mode, right-click the project in the Package pane and select Android Tools > Export Application Package. Alternatively, you can follow the "Exporting the unsigned .apk" link in the Manifest Editor overview page. After you have saved the exported .apk, you need to use Jarsigner to sign the .apk with your own key before distribution. If you don't have a key, you can use Keystore to create a keystore and key with all the appropriate fields. If you already have a key, such as a corporate key, you can use that to sign the .apk.
If you use Ant to build your .apk files, debug signing mode is enabled by default, assuming that you are using a build.xml file generated by the activitycreator tool included in the latest SDK. When you run Ant against build.xml to compile your app, the build script generates a keystore/key and signs the .apk for you. No specific action on your part is needed.
To compile your application in release mode, all you need to do is specify a build target "release" in the Ant command. For example, if you are running Ant from the directory containing your build.xml file, the command would look like this:
ant release
The build script compiles the application .apk without signing it. After you have compiled the.apk, you need to use Jarsigner to sign the .apk with your own key before distribution. If you don't have a key, you can use Keystore to create a keystore and key with all the appropriate fields. If you already have a key, such as a corporate key, you can use that to sign the .apk.
The self-signed certificate used to sign your application in debug mode (the default on Eclipse/ADT and Ant builds) will have an expiration date of 1 year from its creation date.
When the certificate expires, you will get a build error. On Ant builds, the error looks like this:
debug: [echo] Packaging bin/samples-debug.apk, and signing it with a debug key... [exec] Debug Certificate expired on 8/4/08 3:43 PM
In Eclipse/ADT, you will see a similar error in the Android console.
To fix this problem, simply delete the debug.keystore file. On Linux/Mac OSX,
the file is stored in ~/.android. OOn Windows XP, the file is stored in
C:\Documents and Settings\<user>\Local Settings\Application Data\Android.
On Windows Vista, the file is stored in
C:\Users\<user>\AppData\Local\Android.
The next time you build, the build tools will regenerate a new keystore and debug key.
Note that, if your development machine is using a non-Gregorian locale, the build tools may erroneously generate an already-expired debug certificate, so that you get an error when trying to compile your application. For workaround information, see the troubleshooting topic I can't compile my app because the build tools generated an expired debug certificate.
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 and look at it 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}
...
{@link android.util.Log 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.