Android Getting Started

Welcome to Android!

The Android platform is a software stack for mobile devices including an operating system, middleware and key applications. Developers can create applications for the platform using the Android SDK. Applications are written using the Java programming language and run on Dalvik, a custom virtual machine designed for embedded use which runs on top of a Linux kernel.

If you want to know how to develop applications for Android, you're in the right place. This site provides a variety of documentation that will help you learn about Android and develop mobile applications for the platform.

An early look at the the Android SDK is also available. It includes sample projects with source code, development tools, an emulator, and of course all the libraries you'll need to build an Android application.

Download the SDK

To start learning about the Android platform, please read the documentation in the following order:

What is Android?

An overview of the Android platform

Getting Started

All the basics, including Hello World

Developing Applications

The nuts and bolts of Android applications

Developer Toolbox

In-depth information on specific topics

Reference Information

A myriad of reference material

Sample Code

Several sample Android applications for your viewing pleasure

Frequently Asked Questions

Common issues and questions

————————————————————————————————————————————————

What is Android?

Android is a software stack for mobile devices that includes an operating system, middleware and key applications. This early look at the Android SDK provides the tools and APIs necessary to begin developing applications on the Android platform using the Java programming language.

Features

• Application framework enabling reuse and replacement of components
• Dalvik virtual machine optimized for mobile devices
• Integrated browser based on the open source WebKit engine
• Optimized graphics powered by a custom 2D graphics library; 3D graphics based on the OpenGL ES 1.0 specification (hardware acceleration optional)
• SQLite for structured data storage
• Media support for common audio, video, and still image formats (MPEG4, H.264, MP3, AAC, AMR, JPG, PNG, GIF)
• GSM Telephony (hardware dependent)
• Bluetooth, EDGE, 3G, and WiFi (hardware dependent)
• Camera, GPS, compass, and accelerometer (hardware dependent)
• Rich development environment including a device emulator, tools for debugging, memory and performance profiling, and a plugin for the Eclipse IDE

Android Architecture

The following diagram shows the major components of the Android operating system. Each section is described in more detail below.

Applications

Android will ship with a set of core applications including an email client, SMS program, calendar, maps, browser, contacts, and others. All applications are written using the Java programming language.

Application Framework

Developers have full access to the same framework APIs used by the core applications. The application architecture is designed to simplify the reuse of components; any application can publish its capabilities and any other application may then make use of those capabilities (subject to security constraints enforced by the framework). This same mechanism allows components to be replaced by the user.

Underlying all applications is a set of services and systems, including:

• A rich and extensible set of Views that can be used to build an application, including lists, grids, text boxes, buttons, and even an embeddable web browser
• Content Providers that enable applications to access data from other applications (such as Contacts), or to share their own data
• A Resource Manager, providing access to non-code resources such as localized strings, graphics, and layout files
• A Notification Manager that enables all applications to display custom alerts in the status bar
• An Activity Manager that manages the life cycle of applications and provides a common navigation backstack

For more details and a walkthrough of an application, see Writing an Android Application.

Libraries

Android includes a set of C/C++ libraries used by various components of the Android system. These capabilities are exposed to developers through the Android application framework. Some of the core libraries are listed below:

• System C library - a BSD-derived implementation of the standard C system library (libc), tuned for embedded Linux-based devices
• Media Libraries - based on PacketVideo's OpenCORE; the libraries support playback and recording of many popular audio and video formats, as well as static image files, including MPEG4, H.264, MP3, AAC, AMR, JPG, and PNG
• Surface Manager - manages access to the display subsystem and seamlessly composites 2D and 3D graphic layers from multiple applications
• LibWebCore - a modern web browser engine which powers both the Android browser and an embeddable web view
• SGL - the underlying 2D graphics engine
• 3D libraries - an implementation based on OpenGL ES 1.0 APIs; the libraries use either hardware 3D acceleration (where available) or the included, highly optimized 3D software rasterizer
• FreeType - bitmap and vector font rendering
• SQLite - a powerful and lightweight relational database engine available to all applications

Android Runtime

Android includes a set of core libraries that provides most of the functionality available in the core libraries of the Java programming language.

Every Android application runs in its own process, with its own instance of the Dalvik virtual machine. Dalvik has been written so that a device can run multiple VMs efficiently. The Dalvik VM executes files in the Dalvik Executable (.dex) format which is optimized for minimal memory footprint. The VM is register-based, and runs classes compiled by a Java language compiler that have been transformed into the .dex format by the included "dx" tool.

The Dalvik VM relies on the Linux kernel for underlying functionality such as threading and low-level memory management.

Linux Kernel

Android relies on Linux version 2.6 for core system services such as security, memory management, process management, network stack, and driver model. The kernel also acts as an abstraction layer between the hardware and the rest of the software stack.

——————————————————————————————————————————————————

Getting Started with Android

To get started with Android, please read the following sections first:

Installing the SDK and Plugin

How to install the SDK and Eclipse plugin, or how to use other tools to build Android applications. Also a guide to running the sample applications.

Hello Android!

Writing your first Android Application, the ever popular Hello World, Android style.

Anatomy of an Android Application

A guide to the structure and architecture of an Android Application. This guide will help you understand the pieces that make up an Android app.

Tutorial: Building a Full Android Application

This tutorial document will lead you through constructing a real Android Application: A notepad which can create, edit and delete notes, and covers many of the basic concepts with practical examples.

Development Tools

The command line tools included with the SDK, what they do, and how to use them.

Life Cycle of an Android Application

The important life-cycle details for Applications and Activities running inside of them.

Other Introductory Material

After reading the sections above, the following Getting Started information is also very useful:

Core Packages

These are the basic packages that make up the Android SDK for writing applications. The packages are organized as layers, listed here from lowest-level to highest.

android.util

contains various low-level utility classes, such as specialized container classes, XML utilities, etc.

android.os

provides basic operating system services, message passing, and inter-process communication.

android.graphics

is the core rendering package.

android.text, android.text.method, android.text.style, and android.text.util

supply a rich set of text processing tools, supporting rich text, input methods, etc.

android.database

contains low-level APIs for working with databases.

android.content

provides various services for accessing data on the device: applications installed on the device and their associated resources, and content providers for persistent dynamic data.

android.view

is the core user-interface framework.

android.widget

supplies standard user interface elements (lists, buttons, layout managers, etc) built from the view package.

android.app

provides the high-level application model, implemented using Activities.

Other Notable Packages

These packages provide additional domain-specific features of the Android platform. They are not necessary for basic application development.

android.provider

contains definitions for various standard content providers included with the platform.

android.telephony

provides APIs for interacting with the device's phone stack.

android.webkit

includes various APIs for working with web-based content.

 

————————————————————————————————————————————————

Installing the SDK

This 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. Then read the rest of this document to learn how to install, configure, and use the SDK to create Android applications.

Download the SDK

Upgrading?

If you have already downloaded an earlier version of the SDK and developed applications on it, please read the Upgrading the SDK document instead. The Upgrading document explains how to migrate your existing development environment and applications to the new SDK release. The document also provides information that you will find useful during the upgrade, such as lists of framework and API changes.

Contents

System and Software Requirements Installing the SDK Installing the Eclipse Plugin (ADT) Developing Android Applications on Eclipse Developing Android Applications with Other IDEs and Tools Debugging Debug and Test Settings on the Device Top Debugging Tips Building and Installing an Android Application Removing an Android Application Eclipse Tips

System and Software Requirements

To 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 IDE
  • Eclipse 3.2, 3.3 (Europa)
    • Eclipse JDT plugin (included in most Eclipse IDE packages)
    • WST (optional, but needed for the Android Editors feature; included in most Eclipse IDE packages)
  • JDK 5 or JDK 6 (JRE alone is not sufficient)
  • Not compatible with Gnu Compiler for Java (gcj)
  • Android Development Tools plugin (optional)
• Other development environments or IDEs
  • JDK 5 or JDK 6 (JRE alone is not sufficient)
  • Not compatible with Gnu Compiler for Java (gcj)
  • Apache Ant 1.6.5 or later for Linux and Mac, 1.7 or later for Windows

Note: If JDK is already installed on your development computer, please take a moment to make sure that it meets the version requirements listed above. In particular, note that some Linux distributions may include JDK 1.4 or Gnu Compiler for Java, both of which are not supported for Android development.

Installing the SDK

After downloading the SDK, unpack the .zip archive to a suitable location on your machine. By default, the SDK files are unpacked into a directory named android_sdk_<platform>_<release>_<build>. The directory contains the subdirectories tools/, samples/, and others.

Make a note of the name and location of the unpacked SDK directory on your system — you will need to refer to the SDK directory later, when setting up the Android plugin or using SDK tools.

Optionally, you can add the path to the SDK tools directory to your path. As mentioned above, the tools/ directory is located in the SDK directory.

• 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 the tools/ directory to it. If you don't see a line setting the path, you can add one:
  • export PATH=${PATH}:<your_sdk_dir>/tools
• 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. Add the full path to the tools/ directory to the path.

Adding tools to your path lets you run Android Debug Bridge (adb) and the other command line tools 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)

Tips for downloading ADT

If you are having trouble downloading the ADT plugin after following the steps listed at left, here are some suggestions:

• In Step 4, try changing the remote update site URL to use http, rather than https.
• If you are behind a firewall (such as a corporate firewall), make sure that you have properly configured your proxy settings in Eclipse. In Eclipse 3.3, you can configure proxy information from the main Eclipse menu in Window > Preferences > General > Network Connections. In Eclipse 3.2, use Window > Preferences > Install/Update.

If you are still unable to use Eclipse to download the ADT plugin, follow these steps to download and install the plugin from your computer:

1. Download the ADT zip file
2. Unpack the zip file in its own folder
3. Follow steps 1 and 2 in the default install instructions (on the left)
4. Press New Local Site...
5. In the resulting dialog box, select the folder where you unpacked the zip file
6. Follow steps 5 through 11 in the default install instructions (on the left) to complete the installation

Note that to update your plugin, you will have to follow these steps again instead of the default update instructions.

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, follow the steps below.

1. Start Eclipse, then select Help > Software Updates > Find and Install....
2. In the dialog that appears, select Search for new features to install and press Next.
3. Press New Remote Site.
4. In the resulting dialog box, enter a name for the remote site (e.g. Android Plugin) and enter this as its URL:

   https://dl-ssl.google.com/android/eclipse/

   Press OK.
5. You should now see the new site added to the search list (and checked). Press Finish.
6. In the subsequent Search Results dialog box, select the checkbox for Android Plugin > Developer Tools. This will check both features: "Android Developer Tools", and "Android Editors". The Android Editors feature is optional, but recommended. If you choose to install it, you need the WST plugin mentioned earlier in this page.

   Now press Next.

7. Read the license agreement and then select Accept terms of the license agreement, if appropriate. Press Next.
8. Press Finish.
9. The ADT plugin is not signed; you can accept the installation anyway by pressing Install All.
10. Restart Eclipse.
11. After restart, update your Eclipse preferences to point to the SDK directory:
    1. Select Window > Preferences... to open the Preferences panel. (Mac OS X: Eclipse > Preferences)
    2. Select Android from the left panel.
    3. For the SDK Location in the main panel, press Browse... and locate the SDK directory.
    4. Press Apply, then OK.

Updating the ADT Plugin

In some cases, a new ADT plugin may become available for your existing version of the SDK. You can use the steps below to update the ADT plugin from inside Eclipse.

1. Select Help > Software Updates > Find and Install....
2. Select Search for updates of the currently installed features and press Finish.
3. If any update for ADT is available, select and install.

Alternatively,

1. Select Help > Software Updates > Manage Configuration.
2. Navigate down the tree and select Android Development Tools <version>
3. Select Scan for Updates under Available Tasks.

Developing Android Applications on Eclipse

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.

Creating an Android Project

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:

1. Select File > New > Project
2. Select Android > Android Project, and press Next
3. 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.

4. 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.

1.  

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:

1. Select Run > Open Run Dialog... or Run > Open Debug Dialog... as appropriate.
2. In the project type list on the left, right-click Android Application and select New.
3. Enter a name for your configuration.
4. On the Android tab, browse for the project and Activity to start.
5. On the Target tab, set the desired screen and network properties, as well as any other emulator startup options.
6. You can set additional options on the Common tab as desired.
7. Press Apply to save the launch configuration, or press Run or Debug (as appropriate).

Running and Debugging an Application

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 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 Tools

The 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:

1. 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.

2. 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 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 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).

Building an Android Application

Use the Ant build.xml file generated by activityCreator to build your application.

1. If you don't have it, you can obtain Ant from the Apache Ant home page. Install it and make sure it is on your executable path.
2. 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.

3. If you have not done so already, follow the instructions for Creating a New Project above to set up the project.
4. 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 Application

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:

1. Start the emulator (run <your_sdk_dir>/tools/emulator from the command line)
2. 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).
3. 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 <your_sdk_dir>/sample/LunarLander and type ../../tools/adb install bin/LunarLander.apk
4. 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 Application

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.

1. Start the Dalvik Debug Monitor Server (DDMS) tool , which acts as a port forwarding service between your IDE and the emulator.
2. 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.
3. Configure your IDE to attach to port 8700 for debugging. We include information on how to set up Eclipse to debug your project.

Configuring your IDE to attach to the debugging port

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.

Debugging

Android has a fairly extensive set of tools to help you debug your programs:

• DDMS - 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.
• logcat - 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 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.google.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

• Traceview - 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 Debug and Test Settings on the Emulator below.

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.

Debug and Test Settings on the Device

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):

• 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 waitForDebugger() 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 onFreeze(Bundle) / onCreate(android.os.Bundle) 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 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 Tips

Quick 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 Setting debug and test configurations on the emulator.

Getting system state information from the emulator (dumpstate)

You can access dumpstate information from the Dalvik Debug Monitor Service tool. See dumpsys and dumpstate 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 dumpsys and dumpstate 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 Running the Traceview Debugging Program 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 shell
logcat -b radio

Running 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 Using adb 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 util.Log and Debug for your convenience.

Building and Installing an Android Application

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.

Removing an Android Application

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.

Eclipse Tips

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 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 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).

 

——————————————————————————————————————————————

Hello, Android!

First impressions matter, and as a developer you know that the first impression you get of a development framework is how easy it is to write "Hello, World!" Well, in Android, it's pretty easy. Here's how it looks:

• Create the Project
• Construct the UI
• Run the Code: Hello, Android

The sections below spell it all out in detail.

• Upgrading the UI to an XML Layout
• Debugging Your Project
• Creating a Project without Eclipse

Let's jump in!

Create the Project

Creating the project is as simple as can be. An Eclipse plugin is available making Android development a snap.

You'll need to have a development computer with the Eclipse IDE installed (see System and Software Requirements), and you'll need to install the Android Eclipse Plugin (ADT). Once you have those ready, come back here.

First, here's a high-level summary of how to build "Hello, World!":

1. Create a new "Android Project" via the File > New > Project menu.
2. Fill out the project details in the New Android Project dialog.
3. Edit the auto-generated source code template to display some output.

That's it! Next, let's go through each step above in detail.

1. Create a new Android Project

   From Eclipse, select the File > New > Project menu item. If the Android Plugin for Eclipse has been successfully installed, the resulting dialog should have a folder labeled "Android" which should contain a single entry: "Android Project".

   

   Once you've selected "Android Project", click the Next button.

2. Fill out the project details

   The next screen allows you to enter the relevant details for your project. Here's an example:

   

   Here's what each field on this screen means:

   Project Name	This is the name of the directory or folder on your computer that you want to contain the project.
   Package Name	This is the package namespace (following the same rules as for packages in the Java programming language) that you want all your source code to reside under. This also sets the package name under which the stub Activity will be generated. The package name you use in your application must be unique across all packages installed on the system; for this reason, it's very important to use a standard domain-style package for your applications. In the example above, we used the package domain "com.android"; you should use a different one appropriate to your organization.
   Activity Name	This is the name for the class stub that will be generated by the plugin. This will be a subclass of Android's Activity class. An Activity is simply a class that can run and do work. It can create a UI if it chooses, but it doesn't need to.
   Application Name	This is the human-readable title for your application.

   The checkbox for toggling "Use default location" allows you to change the location on disk where the project's files will be generated and stored.

3. Edit the auto-generated source code

   After the plugin runs, you'll have a class named HelloAndroid that looks like this:

   public class HelloAndroid extends Activity {
       /** Called when the activity is first created. */
       @Override
       public void onCreate(Bundle icicle) {
           super.onCreate(icicle);
           setContentView(R.layout.main);
       }
   }

   The next step is to start modifying it!

Construct the UI

Once you've got the project set up, the obvious next step is to get some text up there on the screen. Here's the finished product — next we'll dissect it line by line:

package com.android.hello;

import android.app.Activity;
import android.os.Bundle;
import android.widget.TextView;

public class HelloAndroid extends Activity {
   /** Called when the activity is first created. */
   @Override
   public void onCreate(Bundle icicle) {
       super.onCreate(icicle);
       TextView tv = new TextView(this);
       tv.setText("Hello, Android");
       setContentView(tv);
   }
}

In Android, user interfaces are composed of hierarchies of classes called Views. A View is simply a drawable object, such as a radio button, an animation, or (in our case) a text label. The specific name for the View subclass that handles text is simply TextView.

Here's how you construct a TextView:

TextView tv = new TextView(this);

The argument to TextView's constructor is an Android Context instance. The Context is simply a handle to the system; it provides services like resolving resources, obtaining access to databases and preferences, and so on. The Activity class inherits from Context. Since our HelloAndroid class is a subclass of Activity, it is also a Context, and so we can pass the 'this' reference to the TextView.

Once we've constructed the TextView, we need to tell it what to display:

tv.setText("Hello, Android");

Nothing too surprising there.

At this point, we've constructed a TextView and told it what text to display. The final step is to connect this TextView with the on-screen display, like so:

setContentView(tv);

The setContentView() method on Activity indicates to the system which View should be associated with the Activity's UI. If an Activity doesn't call this method, no UI is present at all and the system will display a blank screen. For our purposes, all we want is to display some text, so we pass it the TextView we just created.

There it is — "Hello, World" in Android! The next step, of course, is to see it running.

Run the Code: Hello, Android

The Eclipse plugin makes it very easy to run your applications. Begin by selecting the Run > Open Run Dialog menu entry; you should see a dialog like this:

Next, highlight the "Android Application" entry, and then click the icon in the top left corner (the one depicting a sheet of paper with a plus sign in the corner) or simply double-click the "Android Application" entry. You should have a new launcher entry named "New_configuration".

Change the name to something expressive, like "Hello, Android", and then pick your project by clicking the Browse button. (If you have more than one Android project open in Eclipse, be sure to pick the right one.) The plugin will automatically scan your project for Activity subclasses, and add each one it finds to the drop-down list under the "Activity:" label. Since your "Hello, Android" project only has one, it will be the default, and you can simply continue.

Press the "Apply" button. Here's an example:

That's it — you're done! Press the Run button, and the Android Emulator should start. Once it's booted up your application will appear. When all is said and done, you should see something like this:

That's "Hello, World" in Android. Pretty straightforward, eh? The next sections of the tutorial offer more detailed information that you may find valuable as you learn more about Android.

Upgrading the UI to an XML Layout

The "Hello, World" example you just completed uses what we call "programmatic" UI layout. This means that you construct and build your application's UI directly in source code. If you've done much UI programming, you're probably familiar with how brittle that approach can sometimes be: small changes in layout can result in big source-code headaches. It's also very easy to forget to properly connect Views together, which can result in errors in your layout and wasted time debugging your code.

That's why Android provides an alternate UI construction model: XML-based layout files. The easiest way to explain this concept is to show an example. Here's an XML layout file that is identical in behavior to the programmatically-constructed example you just completed:

<?xml version="1.0" encoding="utf-8"?>
<TextView xmlns:android="http://schemas.android.com/apk/res/android"
  android:layout_width="fill_parent"
  android:layout_height="fill_parent"
  android:text="Hello, Android"/>

The general structure of an Android XML layout file is simple. It's a tree of tags, where each tag is the name of a View class. In this example, it's a very simple tree of one element, a TextView. You can use the name of any class that extends View as a tag name in your XML layouts, including custom View classes you define in your own code. This structure makes it very easy to quickly build up UIs, using a much simpler structure and syntax than you would in source code. This model is inspired by the web development model, where you can separate the presentation of your application (its UI) from the application logic used to fetch and fill in data.

In this example, there are also four XML attributes. Here's a summary of what they mean:

Attribute	Meaning
xmlns:android	This is an XML namespace declaration that tells the Android tools that you are going to refer to common attributes defined in the Android namespace. The outermost tag in every Android layout file must have this attribute.
android:layout_width	This attribute defines how much of the available width on the screen this View should consume. In this case, it's our only View so we want it to take up the entire screen, which is what a value of "fill_parent" means.
android:layout_height	This is just like android:layout_width, except that it refers to available screen height.
android:text	This sets the text that the TextView should contain. In this example, it's our usual "Hello, Android" message.

So, that's what the XML layout looks like, but where do you put it? Under the res/ directory in your project. The "res" is short for "resources" and that directory contains all the non-code assets that your application requires. This includes things like images, localized strings, and XML layout files.

The Eclipse plugin creates one of these XML files for you. In our example above, we simply never used it. In the Package Explorer, expand the folder res/layout, and edit the file main.xml. Replace its contents with the text above and save your changes.

Now open the file named R.java in your source code folder in the Package Explorer. You'll see that it now looks something like this:

public final class R {
    public static final class attr {
    };
    public static final class drawable {
        public static final int icon=0x7f020000;
    };
    public static final class layout {
        public static final int main=0x7f030000;
    };
    public static final class string {
        public static final int app_name=0x7f040000;
    };
};

A project's R.java file is an index into all the resources defined in the file. You use this class in your source code as a sort of short-hand way to refer to resources you've included in your project. This is particularly powerful with the code-completion features of IDEs like Eclipse because it lets you quickly and interactively locate the specific reference you're looking for.

The important thing to notice for now is the inner class named "layout", and its member field "main". The Eclipse plugin noticed that you added a new XML layout file and then regenerated this R.java file. As you add other resources to your projects you'll see R.java change to keep up.

The last thing you need to do is modify your HelloAndroid source code to use the new XML version of your UI, instead of the hard-coded version. Here's what your new class will look like. As you can see, the source code becomes much simpler:

package com.android.hello;

import android.app.Activity;
import android.os.Bundle;

public class HelloAndroid extends Activity {
    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle icicle) {
        super.onCreate(icicle);
        setContentView(R.layout.main);
    }
}

When you make this change, don't just copy-and-paste it in. Try out the code-completion feature on that R class. You'll probably find that it helps a lot.

Now that you've made this change, go ahead and re-run your application — all you need to do is click the green Run arrow icon, or select Run > Run History > Hello, Android from the menu. You should see.... well, exactly the same thing you saw before! After all, the point was to show that the two different layout approaches produce identical results.

There's a lot more to creating these XML layouts, but that's as far as we'll go here. Read the Implementing a User Interface documentation for more information on the power of this approach.

Debugging Your Project

The Android Plugin for Eclipse also has excellent integration with the Eclipse debugger. To demonstrate this, let's introduce a bug into our code. Change your HelloAndroid source code to look like this:

package com.android.hello;

import android.app.Activity;
import android.os.Bundle;

public class HelloAndroid extends Activity {
    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle icicle) {
        super.onCreate(icicle);
        Object o = null;
        o.toString();
        setContentView(R.layout.main);
    }
}

This change simply introduces a NullPointerException into your code. If you run your application again, you'll eventually see this:

Press "Force Quit" to terminate the application and close the emulator window.

To find out more about the error, set a breakpoint in your source code on the line Object o = null; (double-click on the marker bar next to the source code line). Then select Run > Debug History > Hello, Android from the menu to enter debug mode. Your app will restart in the emulator, but this time it will suspend when it reaches the breakpoint you set. You can then step through the code in Eclipse's Debug Perspective, just as you would for any other application.

Creating the Project without Eclipse

If you don't use Eclipse (such as if you prefer another IDE, or simply use text editors and command line tools) then the Eclipse plugin can't help you. Don't worry though — you don't lose any functionality just because you don't use Eclipse.

The Android Plugin for Eclipse is really just a wrapper around a set of tools included with the Android SDK. (These tools, like the emulator, aapt, adb, ddms, and others are documented elsewhere.) Thus, it's possible to wrap those tools with another tool, such as an 'ant' build file.

The Android SDK includes a Python script named "activityCreator.py" that can be used to create all the source code and directory stubs for your project, as well as an ant-compatible build.xml file. This allows you to build your project from the command line, or integrate it with the IDE of your choice.

For example, to create a HelloAndroid project similar to the one we just created via Eclipse, you'd use this command:

activityCreator.py --out HelloAndroid com.android.hello.HelloAndroid

To build the project, you'd then run the command 'ant'. When that command successfully completes, you'll be left with a file named HelloAndroid.apk under the 'bin' directory. That .apk file is an Android Package, and can be installed and run in your emulator using the 'adb' tool.

For more information on how to use these tools, please read the documentation cited above.

——————————————————————————————————————————————

Anatomy of an Android Application

There are four building blocks to an Android application:

• Activity
• Intent Receiver
• Service
• Content Provider

Not every application needs to have all four, but your application will be written with some combination of these.

Once you have decided what components you need for your application, you should list them in a file called AndroidManifest.xml. This is an XML file where you declare the components of your application and what their capabilities and requirements are. See the Android manifest file documentation for complete details.

Activity

Activities are the most common of the four Android building blocks. An activity is usually a single screen in your application. Each activity is implemented as a single class that extends the Activity base class. Your class will display a user interface composed of Views and respond to events. Most applications consist of multiple screens. For example, a text messaging application might have one screen that shows a list of contacts to send messages to, a second screen to write the message to the chosen contact, and other screens to review old messages or change settings. Each of these screens would be implemented as an activity. Moving to another screen is accomplished by a starting a new activity. In some cases an activity may return a value to the previous activity -- for example an activity that lets the user pick a photo would return the chosen photo to the caller.

When a new screen opens, the previous screen is paused and put onto a history stack. The user can navigate backward through previously opened screens in the history. Screens can also choose to be removed from the history stack when it would be inappropriate for them to remain. Android retains history stacks for each application launched from the home screen.

Intent and Intent Filters

Android uses a special class called an Intent to move from screen to screen. An intent describes what an application wants done. The two most important parts of the intent data structure are the action and the data to act upon. Typical values for action are MAIN (the front door of the application), VIEW, PICK, EDIT, etc. The data is expressed as a URI. For example, to view contact information for a person, you would create an intent with the VIEW action and the data set to a URI representing that person.

There is a related class called an IntentFilter. While an intent is effectively a request to do something, an intent filter is a description of what intents an activity (or intent receiver, see below) is capable of handling. An activity that is able to display contact information for a person would publish an IntentFilter that said that it knows how to handle the action VIEW when applied to data representing a person. Activities publish their IntentFilters in the AndroidManifest.xml file.

Navigating from screen to screen is accomplished by resolving intents. To navigate forward, an activity calls startActivity(myIntent). The system then looks at the intent filters for all installed applications and picks the activity whose intent filters best matches myIntent. The new activity is informed of the intent, which causes it to be launched. The process of resolving intents happens at run time when startActivity is called, which offers two key benefits:

• Activities can reuse functionality from other components simply by making a request in the form of an Intent
• Activities can be replaced at any time by a new Activity with an equivalent IntentFilter

Intent Receiver

You can use an IntentReceiver when you want code in your application to execute in reaction to an external event, for example, when the phone rings, or when the data network is available, or when it's midnight. Intent receivers do not display a UI, although they may use the NotificationManager to alert the user if something interesting has happened. Intent receivers are registered in AndroidManifest.xml, but you can also register them from code using Context.registerReceiver(). Your application does not have to be running for its intent receivers to be called; the system will start your application, if necessary, when an intent receiver is triggered. Applications can also send their own intent broadcasts to others with Context.broadcastIntent().

Service

A Service is code that is long-lived and runs without a UI. A good example of this is a media player playing songs from a play list. In a media player application, there would probably be one or more activities that allow the user to choose songs and start playing them. However, the music playback itself should not be handled by an activity because the user will expect the music to keep playing even after navigating to a new screen. In this case, the media player activity could start a service using Context.startService() to run in the background to keep the music going. The system will then keep the music playback service running until it has finished. (You can learn more about the priority given to services in the system by reading Life Cycle of an Android Application.) Note that you can connect to a service (and start it if it's not already running) with the Context.bindService() method. When connected to a service, you can communicate with it through an interface exposed by the service. For the music service, this might allow you to pause, rewind, etc.

Content Provider

Applications can store their data in files, an SQLite database, or any other mechanism that makes sense. A content provider, however, is useful if you want your application's data to be shared with other applications. A content provider is a class that implements a standard set of methods to let other applications store and retrieve the type of data that is handled by that content provider.

To get more details on content providers, see Accessing Content Providers.

————————————————————————————————————————————————

Tutorial: A Notepad Application

The tutorial in this section gives you a "hands-on" introduction to the Android framework and the tools you use to build applications on it. Starting from a preconfigured project file, it guides you through the process of developing a simple notepad application and provides concrete examples of how to set up the project, develop the application logic and user interface, and then compile and run the application.

The tutorial presents the notepad application development as a set of exercises (see below), each consisting of several steps. You can follow along with the steps in each exercise and gradually build up and refine your application. The exercises explain each step in detail and provide all the sample code you need to complete the application.

When you are finished with the tutorial, you will have created a functioning Android application and learned in depth about many of the most important concepts in Android development. If you want to add more complex features to your application, you can look at and use the code in the notepad application that is supplied in the sample code area of the Android SDK.

Contents

Who Should Use this Tutorial Preparing for the Exercises Exercises Other Resources and Further Learning

Who Should Use this Tutorial

This tutorial is designed for experienced developers, especially those with knowledge of the Java programming language. If you haven't written Java applications before, you can still use the tutorial, but you might need to work at a slower pace.

Also, the tutorial builds on the information provided in the Installing the SDK and Hello Android documents, which explain in detail how to set up your development environment for building Android applications. Before you start the tutorial, make sure that you have already downloaded the SDK and installed it according to the instructions.

Finally, this tutorial describes how to develop the notepad application in the Eclipse development environment, with the Android plugin installed. If you are not using Eclipse, you can follow the exercises and build the application, but you will need to determine how to accomplish the Eclipse-specific steps in your environment. If you want to add more complex features to your application, you can look at and use the code in the notepad application that is supplied in the sample code area of the Android SDK.

The tutorial assumes that you have some familiarity with the basic Android application concepts and terminology. If you aren't yet familiar with those, you should read Overview of an Android Application before continuing.

Preparing for the Exercises

Before you begin, it's important that you install the SDK and set up your Eclipse development. Once your environment is set up, locate and unpack the exercises archive, which is included in the SDK package. The archive includes a series of Eclipse project files that are used in the exercises. You can use these project files instead of creating and configuring your own project files.

To get the tutorial project files:

1. Download the project exercises archive (.zip)
2. Unpack the archive file to a suitable location on your machine
3. Open the NotepadCodeLab folder

Inside the NotepadCodeLab folder, you should see six project files: Notepadv1, Notepadv2, Notepadv3, Notepadv1Solution, Notepadv2Solution and Notepadv3Solution. The Notepadv* projects are the starting points for each of the exercises, while the Notepadv*Solution projects are the exercise solutions. If you are having trouble with a particular exercise, you can compare your current work against the exercise solution to try and track down the problem.

Exercises

The table below lists the tutorial exercises and describes the development areas that each covers. Each exercise assumes that you have completed the previous example (if any).

Exercise 1	Construct a simple notes list that lets the user add new notes but not edit them. Demonstrates the basics of ListActivities and creating and handling menu options. Uses a SQLite database to store the notes.
Exercise 2	Add a second activity to the application. Demonstrates constructing a new Activity, adding it to the Android manifest, passing data between the activities, and using more advanced screen layout. Also shows how to invoke another activity asynchronously using startSubActivity().
Exercise 3	Add handling of life-cycle events to the application, to let it maintain application state across the life cycle.
Extra Credit	Demonstrates how to use the Eclipse debugger and how you can use it to view life-cycle events as they are generated. This section is optional but highly recommended.

Other Resources and Further Learning

• For a lighter but broader introduction to concepts not covered in the tutorial, take a look at Common Android Tasks.
• The Android SDK includes a variety of fully functioning sample applications that make excellent opportunities for further learning. You can find the sample applications in the samples/ directory.
• This tutorial draws from the full Notepad application included in the samples/ directory of the SDK. When you are done with the tutorial, it is highly recommended that you take a closer look at the full Notepad application, as it demonstrates a variety of interesting additions for your application, such as:
  • Setting up a custom striped list for the list of notes.
  • Creating a custom text edit view that overrides the draw() method to make it look like a lined notepad.
  • Implementing a full ContentProvider for notes.
  • Reverting and discarding edits instead of just automatically saving them.

————————————————————————————————————————————————

Development Tools

The Android SDK includes a variety of custom tools that help you develop mobile applications on the Android platform. The most important of these are the Android Emulator and the Android Development Tools plugin for Eclipse, but the SDK also includes a variety of other tools for debugging, packaging, and installing your applications on the emulator.

Android Emulator

A virtual mobile device that runs on your computer. You use the emulator to design, debug, and test your applications in an actual Android run-time environment.

Android Development Tools Plugin for the Eclipse IDE

The ADT plugin adds powerful extensions to the Eclipse integrated environment, making creating and debugging your Android applications easier and faster. If you use Eclipse, the ADT plugin gives you an incredible boost in developing Android applications:

• • 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 — taking screenshots, managing port-forwarding, setting breakpoints, and viewing thread and process information — directly 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.

For more information about the ADT plugin, including installation instructions, see Installing the ADT Plugin for Eclipse. For a usage example with screenshots, see Hello Android.

Dalvik Debug Monitor Service (ddms)

Integrated with Dalvik, the Android platform's custom VM, this tool lets you manage processes on an emulator or device and assists in debugging. You can use it to kill processes, select a specific process to debug, generate trace data, view heap and thread information, take screenshots of the emulator or device, and more.

Android Debug Bridge (adb)

The adb tool lets you install your application's .apk files on an emulator or device and access the emulator or device from a command line. You can also use it to link a standard debugger to application code running on an Android emulator or device.

Android Asset Packaging Tool (aapt)

The aapt tool lets you create .apk files containing the binaries and resources of Android applications.

Android Interface Description Language (aidl)

Lets you generate code for an interprocess interface, such as what a service might use.

sqlite3

Included as a convenience, this tool lets you access the SQLite data files created and used by Android applications.

Traceview

This tool produces graphical analysis views of trace log data that you can generate from your Android application.

mksdcard

Helps you create a disk image that you can use with the emulator, to simulate the presence of an external storage card (such as an SD card).

dx

The dx tool rewrites .class bytecode into Android bytecode (stored in .dex files.)

activityCreator

A script that generates Ant build files that you can use to compile your Android applications. If you are developing on Eclipse with the ADT plugin, you won't need to use this script.

————————————————————————————————————————————————

Life Cycle of an Android Application

In most cases, every Android application runs in its own Linux process. This process is created for the application when some of its code needs to be run, and will remain running until it is no longer needed and the system needs to reclaim its memory for use by other applications.

An unusual and fundamental feature of Android is that an application process's lifetime is not directly controlled by the application itself. Instead, it is determined by the system through a combination of the parts of the application that the system knows are running, how important these things are to the user, and how much overall memory is available in the system.

It is important that application developers understand how different application components (in particular Activity, Service, and IntentReceiver) impact the lifetime of the application's process. Not using these components correctly can result in the system killing the application's process while it is doing important work.

A common example of a process life-cycle bug is an IntentReceiver that starts a thread when it receives an Intent in its onReceiveIntent() method, and then returns from the function. Once it returns, the system considers that IntentReceiver to be no longer active, and thus its hosting process no longer needed (unless other application components are active in it). Thus, it may kill the process at any time to reclaim memory, terminating the spawned thread that is running in it. The solution to this problem is to start a Service from the IntentReceiver, so the system knows that there is still active work being done in the process.

To determine which processes should be killed when low on memory, Android places them into an "importance hierarchy" based on the components running in them and the state of those components. These are, in order of importance:

1. A foreground process is one that is required for what the user is currently doing. Various application components can cause its containing process to be considered foreground in different ways. A process is considered to be in the foreground if any of the following conditions hold:

   • It is running an Activity at the top of the screen that the user is interacting with (its onResume() method has been called).
   • It has an IntentReceiver that is currently running (its IntentReceiver.nReceiveIntent() method is executing).
   • It has a Service that is currently executing code in one of its callbacks (Service.onCreate(), Service.onStart(), or Service.onDestroy()).

   There will only ever be a few such processes in the system, and these will only be killed as a last resort if memory is so low that not even these processes can continue to run. Generally at this point the device has reached a memory paging state, so this action is required in order to keep the user interface responsive.

2. A visible process is one holding an Activity that is visible to the user on-screen but not in the foreground (its onPause() method has been called). This may occur, for example, if the foreground activity has been displayed with a dialog appearance that allows the previous activity to be seen behind it. Such a process is considered extremely important and will not be killed unless doing so is required to keep all foreground processes running.

3. A service process is one holding a Service that has been started with the startService() method. Though these processes are not directly visible to the user, they are generally doing things that the user cares about (such as background mp3 playback or background network data upload or download), so the system will always keep such processes running unless there is not enough memory to retain all foreground and visible process.

4. A background process is one holding an Activity that is not currently visible to the user (its onStop() method has been called). These processes have no direct impact on the user experience. Provided they implement their activity life cycle correctly (see Activity for more details), the system can kill such processes at any time to reclaim memory for one of the three previous processes types. Usually there are many of these processes running, so they are kept in an LRU list to ensure the process that was most recently seen by the user is the last to be killed when running low on memory.

5. An empty process is one that doesn't hold any active application components. The only reason to keep such a process around is as a cache to improve startup time the next time a component of its application needs to run. As such, the system will often kill these processes in order to balance overall system resources between these empty cached processes and the underlying kernel caches.

When deciding how to classify a process, the system picks the most important level of all the components currently active in the process. See the Activity, Service, and IntentReceiver documentation for more detail on how each of these components contribute to the overall life cycle of a process. The documentation for each of these classes describes in more detail how they impact the overall life cycle of their application.

A process's priority may also be increased based on other dependencies a process has to it. For example, if process A has bound to a Service with the Context.BIND_AUTO_CREATE flag or is using a ContentProvider in process B, then process B's classification will always be at least as important as process A's.