INTRODUCTION

Android is an open-source software stack created for a wide array of devices with different form
factors. The primary purposes of Android are to create an open software platform available for
carriers, OEMs, and developers to make their innovative ideas a reality and to introduce a
successful, real-world product that improves the mobile experience for users. We also wanted to
make sure there was no central point of failure, where one industry player could restrict or
control the innovations of any other. The result is a full, production-quality consumer product
with source code open for customization and porting.
Android was originated by a group of companies known as the Open Handset Alliance, led by
Google. Today, many companies -- both original members of the OHA and others -- have
invested heavily in Android. These companies have allocated significant engineering resources to
improve Android and bring Android devices to market.
The companies that have invested in Android have done so on its merits because we believe an
open platform is necessary. Android is intentionally and explicitly an open-source -- as opposed
to a free software -- effort; a group of organizations with shared needs has pooled resources to
collaborate on a single implementation of a shared product. The Android philosophy is
pragmatic, first and foremost. The objective is a shared product that each contributor can tailor
and customize.
Uncontrolled customization can, of course, lead to incompatible implementations. To prevent
this, the Android Open Source Project also maintains the Android Compatibility Program, which
spells out what it means to be "Android compatible" and what is required of device builders to
achieve that status. Anyone can (and will!) use the Android source code for any purpose, and we
welcome all legitimate uses. However, in order to take part in the shared ecosystem of
applications we are building around Android, device builders must participate in the Android
Compatibility Program.
The Android Open Source Project is led by Google, who maintains and further develops
Android. Although Android consists of multiple subprojects, this is strictly a project management
technique. We view and manage Android as a single, holistic software product, not a
"distribution", specification, or collection of replaceable parts. Our intent is that device builders
port Android to a device; they don't implement a specification or curate a distribution.
To work with the Android code, you will need to use both Git and Repo. In most situations, you
can use Git instead of Repo, or mix Repo and Git commands to form complex commands. Using
Repo for basic across-network operations will make your work much simpler, however.
Git is an open-source version-control system designed to handle very large projects that are
distributed over multiple repositories. In the context of Android, we use Git for local operations
such as local branching, commits, diffs, and edits. One of the challenges in setting up the

Android project was figuring out how to best support the outside community--from the hobbiest
community to large OEMs building mass-market consumer devices. We wanted components to
be replaceable, and we wanted interesting components to be able to grow a life of their own
outside of Android. We first chose a distributed revision control system, then further narrowed it
down to Git.
Repo is a repository management tool that we built on top of Git. Repo unifies the many Git
repositories when necessary, does the uploads to our revision control system, and automates parts
of the Android development workflow. Repo is not meant to replace Git, only to make it easier to
work with Git in the context of Android. The repo command is an executable Python script that
you can put anywhere in your path. In working with the Android source files, you will use Repo
for across-network operations. For example, with a single Repo command you can download
files from multiple repositories into your local working directory.
Gerrit is a web-based code review system for projects that use git. Gerrit encourages more
centralized use of Git by allowing all authorized users to submit changes, which are
automatically merged if they pass code review. In addition, Gerrit makes reviewing easier by
displaying changes side by side in-browser and enabling inline comments.

The Android Open Source Project (AOSP) maintains a complete software stack to be ported by
OEMs and other device implementors and run on their own hardware. To maintain the quality of
Android, Google has contributed full-time engineers, product managers, user interface designers,
quality assurance testers, and all the other roles required to bring modern devices to market.
Accordingly, we maintain a number of "code lines" to clearly separate the current stable version
of Android from unstable experimental work. We roll the open source administration and
maintenance of the Android code lines into the larger product development cycle.
The chart below depicts at a conceptual level how AOSP manages code and releases. We're
referring to these as "code lines" instead of "branches" simply because at any given moment
there may be more than one branch for a given "code line". For instance, when a release is cut, it
may or may not become a new branch based on the needs of the moment.
1. At any given moment, there is a current latest release of the Android platform. This
typically takes the form of a branch in the tree.
2. Device builders and contributors work with the current latest release, fixing bugs,
launching new devices, experimenting with new features, and so on.
3. In parallel, Google works internally on the next version of the Android platform and
framework according to the product's needs and goals. We develop the next version of

Android by working with a device partner on a flagship device whose specifications are
chosen to push Android in the direction we believe it should go.
4. When the "n+1"th version is ready, it will be published to the public source tree and
become the new latest release.

SOFTWARE REQUIREMENTS
1. A Linux or Mac system. It is also possible to build Android in a virtual machine on
unsupported systems such as Windows.
2. A 64-bit environment is required for Gingerbread (2.3.x) and newer versions, including
the master branch. You can compile older versions on 32-bit systems.
3. Python 2.6 -- 2.7, which you can download from python.org.
4. GNU Make 3.81 -- 3.82, which you can download from gnu.org.
5. Git 1.7 or newer. You can find it at git-scm.com.
6. JDK 7 to build the master branch of Android in the Android Open Source

Project (AOSP); JDK 6 to build Gingerbread through KitKat; JDK 5 for Cupcake
through Froyo.

HARDWARE REQUIREMENTS
1. 30GB of free disk space to complete a single build and up to 100GB or more
for a full set of build.
2. 2GB RAM
3. Optical Mouse
4. Keyboard

LITERATURE
ANDROID
Android is a mobile operating system (OS) based on the Linux kernel and currently developed
by Google. With a user interface based on direct manipulation, Android is designed primarily for
touchscreen mobile devices such as smartphones and tablet computers, with specialized user
interfaces for televisions (Android TV), cars (Android Auto), and wrist watches (Android Wear).
The OS uses touch inputs that loosely correspond to real-world actions, like swiping, tapping,
pinching, and reverse pinching to manipulate on-screen objects, and a virtual keyboard. Despite
being primarily designed for touchscreen input, it also has been used in game consoles, digital
cameras, regular PCs and other electronics.
Android's source code is released by Google under open source licenses, although most Android
devices ultimately ship with a combination of open source and proprietary software. Initially
developed by Android, Inc., which Google backed financially and later bought in 2005. Android
was unveiled in 2007 along with the founding of the Open Handset Alliancea consortium of
hardware, software, and telecommunication companies devoted to advancing open standards for
mobile devices.
Android is popular with technology companies which require a ready-made, low-cost and
customizable operating system for high-tech devices. Android's open nature has encouraged a
large community of developers and enthusiasts to use the open-source code as a foundation for
community-driven projects, which add new features for advanced user or bring Android to
devices which were officially released running other operating systems. The operating system's
success has made it a target for patent litigation as part of the so-called "smartphone wars"
between technology companies.
JAVA DEVELOPMENT KIT
The Java Development Kit (JDK) is an implementation of either one of the Java
SE, Java EE or Java ME platforms released by Oracle Corporation in the form of a
binary product aimed at Java developers on Solaris, Linux, Mac OS X or Windows.
The JDK includes a private JVM and a few other resources to finish the recipe to a
Java Application.[2] Since the introduction of the Java platform, it has been by far the
most widely used Software Development Kit (SDK). On 17 November 2006, Sun
announced that it would be released under the GNU General Public License (GPL),
thus making it free software. This happened in large part on 8 May 2007, when Sun
contributed the source code to the OpenJDK.

PYTHON
Python is a widely used general-purpose, high-level programming language. Its design
philosophy emphasizes code readability, and its syntax allows programmers to express concepts
in fewer lines of code than would be possible in languages such as C++ or Java. The language
provides constructs intended to enable clear programs on both a small and large scale.
Python supports multiple programming paradigms, including object-oriented, imperative and
functional programming or procedural styles. It features a dynamic type system and automatic
memory management and has a large and comprehensive standard library.
Python interpreters are available for installation on many operating systems, allowing Python
code execution on a majority of systems. Using third-party tools, such as Py2exe or Pyinstaller,
Python code can be packaged into stand-alone executable programs for some of the most popular
operating systems, allowing for the distribution of Python-based software for use on those
environments without requiring the installation of a Python interpreter.
GIT
Git is an open-source version-control system designed to handle very large projects that are
distributed over multiple repositories. In the context of Android, we use Git for local operations
such as local branching, commits, diffs, and edits. One of the challenges in setting up the
Android project was figuring out how to best support the outside community--from the hobbiest
community to large OEMs building mass-market consumer devices. We wanted components to
be replaceable, and we wanted interesting components to be able to grow a life of their own
outside of Android. We first chose a distributed revision control system, then further narrowed it
down to Git.

SOFTWARE REQUIREMENT ANALYSIS

Android's purpose is to establish an open platform for developers to build innovative
apps. The Android Compatibility program defines the technical details of the Android
platform and provides tools used by OEMs to ensure that developers' apps run on a
variety of devices. The Android SDK provides built-in tools that developers use to
clearly state the device features their apps require. And Google Play shows apps
only to those devices that can properly run them.
A mobile phone is a highly personal, always-on, always-present gateway to the
Internet. We haven't met a user yet who didn't want to customize it by extending its
functionality. That's why Android was designed as a robust platform for running
aftermarket applications.
The current rom made by the google is sometimes laggy and hangs sometimes.By
using custom ROM we can make the os according to our use and make it fast and
efficient.The requirement of customising the source code is to have these features :

Install skins to customize how your entire Android operating system looks.

Customize the quick settings menu Android includes to add your own most-used settings
shortcuts.

Run apps in tablet mode on a phone, using a more full-featured tablet interface for certain
apps.

Easily overclock your device to make it run faster or underclock it to make it run slower
while squeezing out more battery life.

Disable the volume warning that Android constantly shows when you increase the system
volume while headphones are plugged in.

Hide the bottom navigation bar (on-screen buttons) to get more screen real estate.

Easily enable root access by toggling a system setting.

Initializing a Build Environment

In this document
1. Choosing a Branch
2. Setting up a Linux build environment
1. Installing the JDK
2. Installing required packages (Ubuntu 12.04)
3. Installing required packages (Ubuntu 14.04)
4. Installing required packages (Ubuntu 10.04 -- 11.10)
5. Configuring USB Access
6. Setting up ccache
7. Using a separate output directory
3. Setting up a Mac OS X build environment
1. Creating a case-sensitive disk image
2. Master branch
3. Branch 4.2.x and earlier branches
4. Branch 4.0.x and all earlier branches
4. Next: Download the source

This section describes how to set up your local work environment to build the Android source
files. You will need to use Linux or Mac OS. Building under Windows is not currently supported.
Note: The source download is approximately 8.5GB in size. You will need over 30GB free to
complete a single build, and up to 100GB (or more) for a full set of builds.
For an overview of the entire code-review and code-update process, see Life of a Patch.

Choosing a Branch

Some of the requirements for your build environment are determined by which version of the
source code you plan to compile. See Build Numbers for a full listing of branches you may
choose from. You may also choose to download and build the latest source code (called
"master"), in which case you will simply omit the branch specification when you initialize the
repository.
Once you have selected a branch, follow the appropriate instructions below to set up your build
environment.
Setting up a Linux build environment

These instructions apply to all branches, including master.

The Android build is routinely tested in house on recent versions of Ubuntu LTS (12.04), but
most distributions should have the required build tools available. Reports of successes or failures
on other distributions are welcome.
For Gingerbread (2.3.x) and newer versions, including the master branch, a 64-bit environment is
required. Older versions can be compiled on 32-bit systems.
Note: It is also possible to build Android in a virtual machine. If you are running Linux in a
virtual machine, you will need at least 16GB of RAM/swap and 30GB or more of disk space in
order to build the Android tree.
See the Downloading and Building page for the list of hardware and software requirements. Then
follow the detailed instructions for Ubuntu and MacOS below.
Installing the JDK

The master branch of Android in the Android Open Source Project (AOSP) requires Java 7. On
Ubuntu, use OpenJDK.
Java 7: For the latest version of Android
$ sudo apt-get update
$ sudo apt-get install openjdk-7-jdk

Optionally, update the default Java version by running:

$ sudo update-alternatives --config java

$ sudo update-alternatives --config javac

If you encounter version errors for Java, set its path as described in the Wrong Java Version
section.
To develop older versions of Android, download and install the corresponding version of the
Java JDK:
Java 6: for Gingerbread through KitKat
Java 5: for Cupcake through Froyo
Note: The lunch command in the build step will ensure that the Sun JDK is used instead of any
previously installed JDK.
Installing required packages (Ubuntu 12.04)

You will need a 64-bit version of Ubuntu. Ubuntu 12.04 is recommended. Building using an
older version of Ubuntu is not supported on master or recent releases.
$ sudo apt-get install git gnupg flex bison gperf build-essential \
zip curl libc6-dev libncurses5-dev:i386 x11proto-core-dev \
libx11-dev:i386 libreadline6-dev:i386 libgl1-mesa-glx:i386 \
libgl1-mesa-dev g++-multilib mingw32 tofrodos \
python-markdown libxml2-utils xsltproc zlib1g-dev:i386
$ sudo ln -s /usr/lib/i386-linux-gnu/mesa/libGL.so.1 /usr/lib/i386-linuxgnu/libGL.so

Installing required packages (Ubuntu 14.04)

Building on Ubuntu 14.04 is experimental at the moment but will eventually become the
recommended environment.
$ sudo apt-get install bison g++-multilib git gperf libxml2-utils

Installing required packages (Ubuntu 10.04 -- 11.10)

Building on Ubuntu 10.04-11.10 is no longer supported, but may be useful for building older
releases of AOSP.
$ sudo apt-get install git-core gnupg flex bison gperf build-essential \
zip curl zlib1g-dev libc6-dev lib32ncurses5-dev ia32-libs \
x11proto-core-dev libx11-dev lib32readline5-dev lib32z-dev \
libgl1-mesa-dev g++-multilib mingw32 tofrodos python-markdown \
libxml2-utils xsltproc

On Ubuntu 10.10:
$ sudo ln -s /usr/lib32/mesa/libGL.so.1 /usr/lib32/mesa/libGL.so

On Ubuntu 11.10:
$ sudo apt-get install libx11-dev:i386

Configuring USB Access

Under GNU/linux systems (and specifically under Ubuntu systems), regular users can't directly
access USB devices by default. The system needs to be configured to allow such access.
The recommended approach is to create a file /etc/udev/rules.d/51-android.rules (as the
root user) and to copy the following lines in it. <username> must be replaced by the actual
username of the user who is authorized to access the phones over USB.
# adb protocol on passion (Nexus One)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e12",
MODE="0600", OWNER="<username>"
# fastboot protocol on passion (Nexus One)
SUBSYSTEM=="usb", ATTR{idVendor}=="0bb4", ATTR{idProduct}=="0fff",
MODE="0600", OWNER="<username>"
# adb protocol on crespo/crespo4g (Nexus S)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e22",
MODE="0600", OWNER="<username>"
# fastboot protocol on crespo/crespo4g (Nexus S)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e20",
MODE="0600", OWNER="<username>"
# adb protocol on stingray/wingray (Xoom)
SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", ATTR{idProduct}=="70a9",
MODE="0600", OWNER="<username>"
# fastboot protocol on stingray/wingray (Xoom)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="708c",
MODE="0600", OWNER="<username>"
# adb protocol on maguro/toro (Galaxy Nexus)
SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", ATTR{idProduct}=="6860",
MODE="0600", OWNER="<username>"
# fastboot protocol on maguro/toro (Galaxy Nexus)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e30",
MODE="0600", OWNER="<username>"
# adb protocol on panda (PandaBoard)
SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d101",
MODE="0600", OWNER="<username>"
# adb protocol on panda (PandaBoard ES)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="d002",
MODE="0600", OWNER="<username>"
# fastboot protocol on panda (PandaBoard)
SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d022",
MODE="0600", OWNER="<username>"
# usbboot protocol on panda (PandaBoard)
SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d00f",
MODE="0600", OWNER="<username>"
# usbboot protocol on panda (PandaBoard ES)
SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d010",
MODE="0600", OWNER="<username>"
# adb protocol on grouper/tilapia (Nexus 7)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e42",
MODE="0600", OWNER="<username>"
# fastboot protocol on grouper/tilapia (Nexus 7)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e40",
MODE="0600", OWNER="<username>"
# adb protocol on manta (Nexus 10)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4ee2",

MODE="0600", OWNER="<username>"
# fastboot protocol on manta (Nexus 10)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4ee0",
MODE="0600", OWNER="<username>"

Those new rules take effect the next time a device is plugged in. It might therefore be necessary
to unplug the device and plug it back into the computer.
This is known to work on both Ubuntu Hardy Heron (8.04.x LTS) and Lucid Lynx (10.04.x
LTS). Other versions of Ubuntu or other variants of GNU/linux might require different
configurations.
Setting up ccache

You can optionally tell the build to use the ccache compilation tool. Ccache acts as a compiler
cache that can be used to speed-up rebuilds. This works very well if you do "make clean" often,
or if you frequently switch between different build products.
Put the following in your .bashrc or equivalent.
export USE_CCACHE=1

By default the cache will be stored in ~/.ccache. If your home directory is on NFS or some other
non-local filesystem, you will want to specify the directory in your .bashrc as well.
export CCACHE_DIR=<path-to-your-cache-directory>

The suggested cache size is 50-100GB. You will need to run the following command once you
have downloaded the source code:
prebuilts/misc/linux-x86/ccache/ccache -M 50G

When building Ice Cream Sandwich (4.0.x) or older, ccache is in a different location:
prebuilt/linux-x86/ccache/ccache -M 50G

This setting is stored in the CCACHE_DIR and is persistent.

Using a separate output directory

By default, the output of each build is stored in the out/ subdirectory of the matching source tree.
On some machines with multiple storage devices, builds are faster when storing the source files
and the output on separate volumes. For additional performance, the output can be stored on a
filesystem optimized for speed instead of crash robustness, since all files can be re-generated in
case of filesystem corruption.
To set this up, export the OUT_DIR_COMMON_BASE variable to point to the location where your
output directories will be stored.
export OUT_DIR_COMMON_BASE=<path-to-your-out-directory>

The output directory for each separate source tree will be named after the directory holding the
source tree.
For instance, if you have source trees as /source/master1 and /source/master2 and
OUT_DIR_COMMON_BASE is set to /output, the output directories will be /output/master1 and
/output/master2.
It's important in that case to not have multiple source trees stored in directories that have the
same name, as those would end up sharing an output directory, with unpredictable results.
This is only supported on Jelly Bean (4.1) and newer, including the master branch.
Setting up a Mac OS X build environment

In a default installation, OS X runs on a case-preserving but case-insensitive filesystem. This

type of filesystem is not supported by git and will cause some git commands (such as "git
status") to behave abnormally. Because of this, we recommend that you always work with the
AOSP source files on a case-sensitive filesystem. This can be done fairly easily using a disk
image, discussed below.
Once the proper filesystem is available, building the master branch in a modern OS X
environment is very straightforward. Earlier branches, including ICS, require some additional
tools and SDKs.
Creating a case-sensitive disk image

You can create a case-sensitive filesystem within your existing OS X environment using a disk
image. To create the image, launch Disk Utility and select "New Image". A size of 25GB is the
minimum to complete the build, larger numbers are more future-proof. Using sparse images
saves space while allowing to grow later as the need arises. Be sure to select "case sensitive,
journaled" as the volume format.
You can also create it from a shell with the following command:
# hdiutil create -type SPARSE -fs 'Case-sensitive Journaled HFS+' -size 40g
~/android.dmg

This will create a .dmg (or possibly a .dmg.sparsefile) file which, once mounted, acts as a drive
with the required formatting for Android development. For a disk image named "android.dmg"
stored in your home directory, you can add the following to your ~/.bash_profile to mount the
image when you execute "mountAndroid":

# mount the android file image

function mountAndroid { hdiutil attach ~/android.dmg
-mountpoint /Volumes/android; }

Once mounted, you'll do all your work in the "android" volume. You can eject it (unmount it) just
like you would with an external drive.
Master branch

To build the latest source in a Mac OS environment, you will need an Intel/x86 machine running
MacOS 10.8 (Mountain Lion), along with Xcode 4.5.2 and Command Line Tools.
You will also need the Java 7 JDK. Select the file: jdk-7u51-macosx-x64.dmg
To develop for versions of Android Gingerbread through KitKat, download and install the Java 6
version of the Java JDK.
Branch 4.2.x and earlier branches

To build 4.2.x and earlier source in a Mac OS environment, you will need an Intel/x86 machine
running MacOS 10.6 (Snow Leopard) or MacOS 10.7 (Lion), along with Xcode 4.2 (Apple's
Developer Tools). Although Lion does not come with a JDK, it should install automatically when
you attempt to build the source.
The remaining sections for Mac OS X only apply to those who wish to build earlier branches.
Branch 4.0.x and all earlier branches

To build android-4.0.x and earlier branches in a Mac OS environment, you need an Intel/x86
machine running MacOS 10.5 (Leopard) or MacOS 10.6 (Snow Leopard). You will need the
MacOS 10.5 SDK.
Installing required packages

Install Xcode from the Apple developer site. We recommend version 3.1.4 or newer, i.e.
gcc 4.2. Version 4.x could cause difficulties. If you are not already registered as an Apple
developer, you will have to create an Apple ID in order to download.

Install MacPorts from macports.org.

Note: Make sure that /opt/local/bin appears in your path BEFORE /usr/bin. If not,
add
export PATH=/opt/local/bin:$PATH
to your ~/.bash_profile.

Get make, git, and GPG packages from MacPorts:

$ POSIXLY_CORRECT=1 sudo port install gmake libsdl git-core gnupg

If using Mac OS 10.4, also install bison:

$ POSIXLY_CORRECT=1 sudo port install bison

Reverting from make 3.82

For versions of Android before ICS, there is a bug in gmake 3.82 that prevents android from
building. You can install version 3.81 using MacPorts by taking the following steps:

Edit /opt/local/etc/macports/sources.conf and add a line that says

file:///Users/Shared/dports

above the rsync line. Then create this directory:

$ mkdir /Users/Shared/dports
In the new dports directory, run
$ svn co --revision 50980
http://svn.macports.org/repository/macports/trunk/dports/devel/gmake/
devel/gmake/

Create a port index for your new local repository:

$ portindex /Users/Shared/dports

Finally, install the old version of gmake with

$ sudo port install gmake @3.81

Setting a file descriptor limit

On MacOS the default limit on the number of simultaneous file descriptors open is too low and a
highly parallel build process may exceed this limit.
To increase the cap, add the following lines to your ~/.bash_profile:
# set the number of open files to be 1024
ulimit -S -n 1024

SOFTWARE DESIGN

CLASS DIAGRAMS

To work with the Android code, you will need to use both Git and Repo. In most situations, you
can use Git instead of Repo, or mix Repo and Git commands to form complex commands. Using
Repo for basic across-network operations will make your work much simpler, however.
Git is an open-source version-control system designed to handle very large projects that are
distributed over multiple repositories. In the context of Android, we use Git for local operations
such as local branching, commits, diffs, and edits. One of the challenges in setting up the
Android project was figuring out how to best support the outside community--from the hobbiest
community to large OEMs building mass-market consumer devices. We wanted components to
be replaceable, and we wanted interesting components to be able to grow a life of their own
outside of Android. We first chose a distributed revision control system, then further narrowed it
down to Git.
Repo is a repository management tool that we built on top of Git. Repo unifies the many Git
repositories when necessary, does the uploads to our revision control system, and automates parts
of the Android development workflow. Repo is not meant to replace Git, only to make it easier to
work with Git in the context of Android. The repo command is an executable Python script that
you can put anywhere in your path. In working with the Android source files, you will use Repo
for across-network operations. For example, with a single Repo command you can download
files from multiple repositories into your local working directory.
Gerrit is a web-based code review system for projects that use git. Gerrit encourages more
centralized use of Git by allowing all authorized users to submit changes, which are
automatically merged if they pass code review. In addition, Gerrit makes reviewing easier by
displaying changes side by side in-browser and enabling inline comments.

Basic Workflow

The basic pattern of interacting with the repositories is as follows:

1. Use repo start to start a new topic branch.
2. Edit the files.
3. Use git add to stage changes.
4. Use git commit to commit changes.
5. Use repo upload to upload changes to the review server.

Task reference
The task list below shows a summary of how to do common Repo and Git tasks. For information
about using repo to download source, see Downloading the Source and Using Repo.

Synchronizing your client

To synchronize the files for all available projects:
$ repo sync

To synchronize the files for selected projects:

$ repo sync PROJECT0 PROJECT1 PROJECT2 ...

Creating topic branches

Start a topic branch in your local work environment whenever you begin a change, for example
when you begin work on a bug or new feature. A topic branch is not a copy of the original files;
it is a pointer to a particular commit. This makes creating local branches and switching among

them a light-weight operation. By using branches, you can isolate one aspect of your work from
the others. For an interesting article about using topic branches, see Separating topic branches.
To start a topic branch using Repo, navigate into the project to be modified and issue:
$ repo start BRANCH_NAME .

Please note, the period represents the project in the current working directory. To verify your new
branch was created:
$ repo status .

Using topic branches

To assign the branch to a particular project:
$ repo start BRANCH_NAME PROJECT_NAME

To switch to another branch that you have created in your local work environment:
$ git checkout BRANCH_NAME

To see a list of existing branches:

$ git branch

or
$ repo branches

The name of the current branch will be preceded by an asterisk.

Note: A bug might be causing repo sync to reset the local topic branch. If git branch shows *
(no branch) after you run repo sync, then run git checkout again.

Staging files
By default, Git notices but does not track the changes you make in a project. In order to tell git to
preserve your changes, you must mark them for inclusion in a commit. This is also called
"staging".
You can stage your changes by running
git add

which accepts as arguments any files or directories within the project directory. Despite the
name, git add does not simply add files to the git repository; it can also be used to stage file
modifications and deletions.

Viewing client status

To list the state of your files:
$ repo status

To see uncommitted edits:

$ repo diff

The repo diff command shows every local edit that you have made that would not go into the
commit, if you were to commit right now. To see every edit that would go into the commit if you
were to commit right now, you need a Git command, git diff. Before running it, be sure you
are in the project directory:
$ cd ~/WORKING_DIRECTORY/PROJECT
$ git diff --cached

Committing changes
A commit is the basic unit of revision control in git, consisting of a snapshot of directory
structure and file contents for the entire project. Creating a commit in git is as simple as typing
git commit

You will be prompted for a commit message in your favorite editor; please provide a helpful
message for any changes you submit to the AOSP. If you do not add a log message, the commit
will be aborted.

Uploading changes to Gerrit

Before uploading, update to the latest revisions:
repo sync

Next run
repo upload

This will list the changes you have committed and prompt you to select which branches to
upload to the review server. If there is only one branch, you will see a simple y/n prompt.

Recovering sync conflicts

If a repo sync shows sync conflicts:

View the files that are unmerged (status code = U).

Edit the conflict regions as necessary.

Change into the relevant project directory, run git add and git commit for the files in
question, and then "rebase" the changes. For example:
$ git add .
$ git commit
$ git rebase --continue

When the rebase is complete start the entire sync again:

$ repo sync PROJECT0 PROJECT1 ... PROJECTN

Cleaning up your client files

To update your local working directory after changes are merged in Gerrit:
$ repo sync

To safely remove stale topic branches:

$ repo prune

Deleting a client
Because all state information is stored in your client, you only need to delete the directory from
your filesystem:
$ rm -rf WORKING_DIRECTORY

Deleting a client will permanently delete any changes you have not yet uploaded for review.

DEPLOYMENT DIAGRAM

CODING
Android Build System

Android uses a custom build system to generate tools, binaries, and documentation. This
document provides an overview of Android's build system and instructions for doing a simple
build.
Android's build system is make based and requires a recent version of GNU Make (note that
Android uses advanced features of GNU Make that may not yet appear on the GNU Make web
site). Before continuing, check your version of make by running % make -v. If you don't have
version 3.80 or greater, you need to upgrade your version of make.
Understanding the makefile

A makefile defines how to build a particular application. Makefiles typically include all of the
following elements:
1. Name: Give your build a name (LOCAL_MODULE := <build_name>).
2. Local Variables: Clear local variables with CLEAR_VARS ( include $
(CLEAR_VARS)).
3. Files: Determine which files your application depends upon
(LOCAL_SRC_FILES := main.c).
4. Tags: Define tags, as necessary (LOCAL_MODULE_TAGS := eng development).
5. Libraries: Define whether your application links with other libraries
(LOCAL_SHARED_LIBRARIES := cutils).
6. Template file: Include a template file to define underlining make tools for a
particular target (include $(BUILD_EXECUTABLE)).

The following snippet illustrates a typical makefile.

LOCAL_PATH := $(my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE := <buil_name>
LOCAL_SRC_FILES := main.c
LOCAL_MODULE_TAGS := eng development
LOCAL_SHARED_LIBRARIES := cutils
include $(BUILD_EXECUTABLE)
(HOST_)EXECUTABLE, (HOST_)JAVA_LIBRARY, (HOST_)PREBUILT,
(HOST_)SHARED_LIBRARY,
(HOST_)STATIC_LIBRARY, PACKAGE, JAVADOC, RAW_EXECUTABLE, RAW_STATIC_LIBRARY,
COPY_HEADERS, KEY_CHAR_MAP

The snippet above includes artificial line breaks to maintain a print-friendly document.

Layers

The build hierarchy includes the abstraction layers described in the table below.
Each layer relates to the one above it in a one-to-many relationship. For example, an arch can
have more than one board and each board can have more than one device. You may define an
element in a given layer as a specialization of an element in the same layer, thus eliminating
copying and simplifying maintenance.
Layer

Example

Description

Produ myProduct,
The product layer defines a complete specification of a
ct
myProduct_eu,
shipping product, defining which modules to build and
myProduct_eu_fr, j2, how to configure them. You might offer a device in
sdk
several different versions based on locale, for
example, or on features such as a camera.
Devic myDevice,
e
myDevice_eu,
myDevice_eu_lite

The device layer represents the physical layer of

plastic on the device. For example, North American
devices probably include QWERTY keyboards whereas
devices sold in France probably include AZERTY
keyboards. Peripherals typically connect to the device
layer.

Board sardine, trout,

goldfish

The board layer represents the bare schematics of a

product. You may still connect peripherals to the board
layer.

Arch

The arch layer describes the processor running on

your board.

arm (arm5te)
(arm6), x86, 68k

Building the Android Platform

This section describes how to build the default version of Android. Once you are comfortable
with a generic build, then you can begin to modify Android for your own target device.
Device Code

To do a generic build of android, source build/envsetup.sh, which contains necessary variable

and function definitions, as described below.
% cd $TOP
% . build/envsetup.sh
# pick a configuration using choosecombo
% choosecombo

% make -j4 PRODUCT-generic-user

You can also replace user with eng for a debug engineering build:
% make -j4 PRODUCT-generic-eng

These Build Variants differ in terms of debug options and packages installed.
Cleaning Up

Execute % m clean to clean up the binaries you just created. You can also execute % m clobber
to get rid of the binaries of all combos. % m clobber is equivalent to removing the //out/
directory where all generated files are stored.
Speeding Up Rebuilds

The binaries of each combo are stored as distinct sub-directories of //out/, making it possible to
quickly switch between combos without having to recompile all sources each time.
However, performing a clean rebuild is necessary if the build system doesn't catch changes to
environment variables or makefiles. If this happens often, you should define the USE_CCACHE
environment variable as shown below:
% export USE_CCACHE=1

Doing so will force the build system to use the ccache compiler cache tool, which reduces
recompiling all sources.
ccache

binaries are provided in //prebuilt/... and don't need to get installed on your system.

Troubleshooting

The following error is likely caused by running an outdated version of Java.

device Dex: core UNEXPECTED TOP-LEVEL ERROR:
java.lang.NoSuchMethodError: method java.util.Arrays.hashCode with
signature ([Ljava.lang.Object;)I was not found.
at com.google.util.FixedSizeList.hashCode(FixedSizeList.java:66)
at com.google.rop.code.Rop.hashCode(Rop.java:245)
at java.util.HashMap.hash(libgcj.so.7)
[...]
dx is a Java program that uses facilities first made available in Java version 1.5. Check

your
version of Java by executing % java -version in the shell you use to build. You should see
something like:
java version "1.5.0_07"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_07-164)
Java HotSpot(TM) Client VM (build 1.5.0_07-87, mixed mode, sharing)

If you do have Java 1.5 or later and your receive this error, verify that you have properly updated
your PATH variable.

Building the Android Kernel

This section describes how to build Android's default kernel. Once you are comfortable with a
generic build, then you can begin to modify Android drivers for your own target device.
To build the kernel base, switch to the device directory (/home/joe/android/device) in order
to establish variables and run:
% . build/envsetup.sh
% partner_setup generic

Then switch to the kernel directory /home/joe/android/kernel.

Checking Out a Branch

The default branch is always android. To check out a different branch, execute the following:
% git checkout --track -b android-mydevice origin/android-mydevice
//Branch android-mydevice set up to track remote branch
% refs/remotes/origin/android-mydevice.
//Switched to a new branch "android-mydevice"

To simplify code management, give your local branch the same name as the remote branch it is
tracking (as illustrated in the snippet above). Switch between branches by executing % git
checkout <branchname>.
Verifying Location

Find out which branches exist (both locally and remotely) and which one is active (marked with
an asterisk) by executing the following:
% git branch -a
android
* android-mydevice
origin/HEAD
origin/android
origin/android-mydevice
origin/android-mychipset

To only see local branches, omit the -a flag.

Building the Kernel

To build the kernel, execute:

% make -j4

Build Variants

When building for a particular product, it's often useful to have minor variations on what is
ultimately the final release build. These are the currently-defined build variants:
eng

This is the default flavor. A plain make is the same as make eng.

Installs modules tagged with: eng, debug, user, and/or development.

Installs non-APK modules that have no tags specified.

Installs APKs according to the product definition files, in addition to

tagged APKs.

ro.secure=0

ro.debuggable=1

ro.kernel.android.checkjni=1

adb is enabled by default.

make user

This is the flavor intended to be the final release bits.

user

Installs modules tagged with user.

Installs non-APK modules that have no tags specified.

Installs APKs according to the product definition files; tags are

ignored for APK modules.

ro.secure=1

ro.debuggable=0

adb is disabled by default.

make userdebug

The same as user, except:

userdebug

Also installs modules tagged with debug.

ro.debuggable=1

adb is enabled by default.

Customization
Boot Screen Customization

At startup, Android displays a splashscreen image while booting the device. Do the following if
you wish to modify the default splash screen:
1. Create a 320x480 image, splashscreen.jpg in this example.
2. Using ImageMagick, convert your .jpg file to .r format:
3.
4. convert screen.jpg screen.r

5. Use the rgb2565 application to convert the image to 565 format:

6.
7. rgb2565 < screen.rgb > screen.565

8. Use fastboot to flash the image to the device:

9.
10. fastboot flash splash1 screen.565

Network Customization Platform

Network Configuration

Android stores network configurations as a resource that gets compiled into binary at form at
build time. The XML representation of this resource is located at
//android/frameworks/base/core/res/res/xml/apns.xml. This file does not include any
configured APNs. You should not modify this file, but instead configure APNs by product at
build time (see Build-time APN Configuration below).
Each network configuration is stored in an XML element following this syntax:
<apn carrier="T-Mobile US"
mcc="310"
mnc="260"
apn=" wap.voicestream.com"
user="none"
server="*"
password="none"
proxy=" 216.155.165.50"
port="8080"
mmsc="http://216.155.174.84/servlets/mms"
/>

Build-time APN configuration

To set the APN configuration for a particular product target, add an apns-conf.xml file to the
product configuration (do not modify the default platform APNs). This allows multiple products,
all with different APNs, to be built off the same code base.
To configure APNs at the product level, add a line to the product configuration file like the
example below (vendor/<vendor_name>/products/myphone-us.mk):
PRODUCT_COPY_FILES := vendor/acme/etc/apns-conf-us.xml:system/etc/apnsconf.xml

APN configuration at run time

At runtime, the Android reads APNs from the following file:

system/etc/apns-conf.xml

Android supports the following run-time network configuration methods to choose the
appropriate APN from the list of configured APNs:

Automatic Configuration: At boot time, Android determines the correct

network configuration based on the MCC and MNC from the SIM card and
automatically configure all network settings.

Manual Configuration: The platform will also support runtime (user)

manual selection of network settings by name, for example, "Company Name
US," and will support manual network configuration entry.

WAP / SMS Push Configuration: The network configurations are standard

Android resources. You can upgrade a resource at runtime by installing a new
system resource APK package. It will be possible to develop a network
configuration service which listens to a specific binary SMS port for binary
SMS messages containing the network configurations. NOTE: The
implementation will likely be network operator dependent due to inconsistent
SMS ports, binary SMS formats, etc.

Customizing pre-loaded applications

To customize the list of Android packages for a particular product (applications, input methods,
providers, services, etc.), set PRODUCT_PACKAGES property in the product configuration, as
illustrated below:
PRODUCT_PACKAGES := \
<company_name>Mail \
<company_name>IM \
<company_name>HomeScreen \
<company_name>Maps \
<company_name>SystemUpdater

Package names should correspond to the LOCAL_PACKAGE_NAME specified for each package's
build target. For example, the Android.mk build target for <company_name>Mail, referenced
above, could look like this:
# Build the <company_name>Mail application
LOCAL_PATH:= $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE_TAGS := user development
LOCAL_SRC_FILES := $(call all-java-files-under,src,tests)
LOCAL_STATIC_JAVA_LIBRARIES := <company_name>login-client
# Specify the package name
LOCAL_PACKAGE_NAME := <company_name>Mail
# Specify the certificate used to sign the application
LOCAL_CERTIFICATE := vendor/<company_name>/certs/app
include $(BUILD_PACKAGE)
# Build the login client static library
include $(LOCAL_PATH)/client/Android.mk

Note that the home screen is just an Android application that can be replaced entirely or
customized by changing source code and application resources (Java source, layouts, etc.).
Customizing browser bookmarks

Browser bookmarks are stored as string resources in the Browser application:

//android/packages/apps/Browser/res/values/strings.xml. Bookmarks are defined as
simple value string arrays called "bookmarks". Each bookmark entry is stored as a pair of array
values; the first represents the bookmark name and the second the bookmark URL. For example:
<!-- Bookmarks -->
<string-array name="bookmarks">
<item>Google</item>
<item>http://www.google.com/</item>
<item>Yahoo!</item>
<item>http://www.yahoo.com/</item>
<item>MSN</item>
<item>http://www.msn.com/</item>
<item>MySpace</item>
<item>http://www.myspace.com/</item>
<item>Facebook</item>
<item>http://www.facebook.com/</item>
<item>Wikipedia</item>
<item>http://www.wikipedia.org/</item>
<item>eBay</item>
<item>http://www.ebay.com/</item>
<item>CNN</item>

<item>http://www.cnn.com/</item>
<item>New York Times</item>
<item>http://www.nytimes.com/</item>
<item>ESPN</item>
<item>http://espn.go.com/</item>
<item>Amazon</item>
<item>http://www.amazon.com/</item>
<item>Weather Channel</item>
<item>http://www.weather.com/</item>
<item>BBC</item>
<item>http://www.bbc.co.uk/</item>
</string-array>

Like and Android application resource, the platform will load alternate resources based on the
platform configuration values. See Resources and Internationalization in the Android SDK for
details. To configure bookmarks for a specific mobile network operator, place your customized
bookmarks in a separate strings.xml file and place it under a Mobile Network Code (MNO)
specific resource folder. For example, Browser/res/values-mccXXX-mncYYY/strings.xml
where XXX and YYY represent the three-digit MCC and two to three digit MNC values.
Android loads any configuration-specific resources as override values for the default values, so it
is only necessary to include the bookmarks string-array values in this file.
Email Provider Customization

The default email provider settings are stored as string resources in the Email application
(//android/packages/apps/Email/res/xml/providers.xml) as illustrated below.
<providers>
<!-- Gmail variants -->
<provider id="gmail" label="Gmail" domain="gmail.com">
<incoming uri="imap+ssl+://imap.gmail.com" username="$email"/>
<outgoing uri="smtp+ssl+://smtp.gmail.com" username="$email"/>
</provider>
<provider id="googlemail" label="Google Mail" domain="googlemail.com">
<incoming uri="imap+ssl+://imap.googlemail.com" username="$email"/>
<outgoing uri="smtp+ssl+://smtp.googlemail.com" username="$email"/>
</provider>
<provider id="google" label="Google" domain="google.com">
<incoming uri="imap+ssl+://imap.gmail.com" username="$email"/>
<outgoing uri="smtp+ssl+://smtp.gmail.com" username="$email"/>
</provider>
<provider id="android" label="Android" domain="android.com">
<incoming uri="imap+ssl+://imap.gmail.com" username="$email"/>
<outgoing uri="smtp+ssl+://smtp.gmail.com" username="$email"/>
</provider>
<!-- Common US providers -->
<provider id="aim" label="AIM" domain="aim.com">

<incoming uri="imap://imap.aim.com" label="IMAP" username="$email"/>

<outgoing uri="smtp://smtp.aim.com:587" username="$email"/>
</provider>
<provider id="aol" label="AOL" domain="aol.com">
<incoming uri="imap://imap.aol.com" label="IMAP" username="$email"/>
<outgoing uri="smtp://smtp.aol.com:587" username="$email"/>
</provider>
<provider id="comcast" label="Comcast" domain="comcast.net">
<incoming uri="pop3+ssl+://mail.comcast.net" username="$user"/>
<outgoing uri="smtp+ssl+://smtp.comcast.net" username="$user"/>
</provider>
<provider id="compuserve" label="CompuServe" domain="cs.com">
<incoming uri="imap://imap.cs.com" username="$user"/>
<outgoing uri="smtp://smtp.cs.com" username="$user"/>
</provider>
<provider id="dotmac" label=".Mac" domain="mac.com">
<incoming uri="imap+tls://mail.mac.com" username="$email"/>
<outgoing uri="smtp+tls://smtp.mac.com" username="$email"/>
</provider>
<provider id="earthlink" label="Earthlink" domain="earthlink.net">
<incoming uri="pop3://pop.earthlink.net" username="$email"/>
<outgoing uri="smtp://smtpauth.earthlink.net:587" username="$email"/>
</provider>
<provider id="juno" label="Juno" domain="juno.com">
<incoming uri="pop3://pop.juno.com" username="$user"/>
<outgoing uri="smtp://smtp.juno.com" username="$user"/>
</provider>
<provider id="live" label="Windows Live Hotmail Plus" domain="live.com"
note="@string/provider_note_live">
<incoming uri="pop3+ssl+://pop3.live.com" username="$email"/>
<outgoing uri="smtp+tls+://smtp.live.com" username="$email"/>
</provider>
<provider id="hotmail" label="Windows Live Hotmail Plus"
domain="hotmail.com" note="@string/provider_note_live">
<incoming uri="pop3+ssl+://pop3.live.com" username="$email"/>
<outgoing uri="smtp+tls+://smtp.live.com" username="$email"/>
</provider>
<provider id="msn" label="Windows Live Hotmail Plus" domain="msn.com"
note="@string/provider_note_live">
<incoming uri="pop3+ssl+://pop3.live.com" username="$email"/>
<outgoing uri="smtp+tls+://smtp.live.com" username="$email"/>
</provider>
<provider id="mobileme" label="MobileMe" domain="me.com">
<incoming uri="imap+tls://mail.me.com" username="$email"/>
<outgoing uri="smtp+tls://smtp.me.com" username="$email"/>
</provider>
<provider id="netzero" label="NetZero" domain="netzero.com">
<incoming uri="pop3://pop.netzero.com" username="$user"/>
<outgoing uri="smtp://smtp.netzero.com" username="$user"/>
</provider>
<provider id="sbcglobal" label="SBC Global" domain="sbcglobal.net">
<incoming uri="pop3://pop.sbcglobal.yahoo.com" username="$email"/>
<outgoing uri="smtp://smtp.sbcglobal.yahoo.com" username="$email"/>
</provider>
<provider id="verizon" label="Verizon" domain="verizon.net">
<incoming uri="pop3://incoming.verizon.net" username="$user"/>
<outgoing uri="smtp://outgoing.verizon.net" username="$user"/>

</provider>
<provider id="yahoo" label="Yahoo Plus" domain="yahoo.com"
note="@string/provider_note_yahoo">
<incoming uri="pop3+ssl+://plus.pop.mail.yahoo.com" username="$user"/>
<outgoing uri="smtp+ssl+://plus.smtp.mail.yahoo.com"
username="$user"/>
</provider>
<!-- Common UK providers -->
<provider id="aol-uk" label="AOL" domain="aol.co.uk">
<incoming uri="imap+ssl+://imap.uk.aol.com" label="IMAP"
username="$user"/>
<outgoing uri="smtp+ssl+://smtp.uk.aol.com" username="$user"/>
</provider>
<provider id="bt" label="BT Internet" domain="btinternet.com">
<incoming uri="pop3://mail.btinternet.com" username="$email"/>
<outgoing uri="smtp://mail.btinternet.com" username=""/>
</provider>
<provider id="tiscali" label="Tiscali" domain="tiscali.co.uk">
<incoming uri="pop3://pop.tiscali.co.uk" username="$email"/>
<outgoing uri="smtp://smtp.tiscali.co.uk" username="$email:wq"/>
</provider>
<provider id="yahoo-uk" label="Yahoo" domain="yahoo.co.uk"
note="@string/provider_note_yahoo_uk">
<incoming uri="pop3+ssl+://pop.mail.yahoo.co.uk" username="$user"/>
<outgoing uri="smtp+ssl+://smtp.mail.yahoo.co.uk" username="$user"/>
</provider>
<!-- Common Germany providers -->
<provider id="freenet" label="Freenet" domain="freenet.de">
<incoming uri="pop3://mx.freenet.de" username="$user"/>
<outgoing uri="smtp+ssl://mx.freenet.de" username="$email"/>
</provider>
<provider id="gmx" label="GMX" domain="gmx.de">
<incoming uri="pop3+tls://pop.gmx.net" username="$email"/>
<outgoing uri="smtp+tls://mail.gmx.net" username="$email"/>
</provider>
<provider id="T-Online" label="T-Online" domain="t-online.de"
note="@string/provider_note_t_online">
<incoming uri="pop3://popmail.t-online.de" username="$email"/>
<outgoing uri="smtp://smtpmail.t-online.de" username="$email"/>
</provider>
<provider id="web.de" label="Web.de" domain="web.de">
<incoming uri="pop3+tls://pop3.web.de" username="$user"/>
<outgoing uri="smtp+tls://smtp.web.de" username="$user"/>
</provider>
</providers>

As with all Android application resources, the platform will load alternate resources based on the
platform configuration values. See Resources and Internationalization in the Android SDK for
details. To configure email providers for a specific mobile network operator, place the
customized providers in a separate providers.xml file and place it under a Mobile Network
Code (MNO) specific resource folder. For example, Email/res/xml-mccXXX-

mncYYY/providers.xml

where XXX and YYY represent the three-digit MCC and two to three

digit MNC values.

Platform Themes
Themes and Styles

System level styles are defined in

//android/framework/base/core/res/res/values/styles.xml.

Animations

Android supports configurable animations for window and view transitions. System-level
animations are defined in XML in global resource files located in
//android/framework/base/core/res/res/anim/

TESTING
Instrumentation Testing

This document describes how to use the Instrumentation Framework to write test cases.
Instrumentation testing allows you to verify a particular feature or behavior with an automated
JUnit TestCase. You can launch activities and providers within an application, send key events,
and make assertions about various UI elements.
You should have a working knowledge of the following:

Android Application Framework

Using adb, am and various logging functionality

A brief understanding of the application of interest, that is, the names of the
classes which handle the intents etc.

JUnit testing.

Each Android application runs in its own process. Instrumentation kills the application process
and restarts the process with Instrumentation. Instrumentation gives a handle to the application
context used to poke around the application to validate test assertions, allowing you to write test
cases to test applications at a much lower level than UI screen shot tests. Note that
Instrumentation cannot catch UI bugs.
Instrumentation Framework
Classes

The following classes help glue together Instrumentation with JUnit testing.
Class
InstrumentationTestCase

Description

This extends the standard JUnit TestCase and offers access to an

Instrumentation class. Write tests inside your instrumentation
class any way you see fit. For example, your test might launch
activities and send key events. For this to work properly, the
instrumentation needs to be injected into the test case.

InstrumentationTestRunner The instrumentation test runner is an instrumentation

that runs instrumentation test cases and injects itself

into each test case. Instrumentation test cases need to
be grouped together with an instrumentation test

runner with the appropriate target package.

InstrumentationTestSuite The instrumentation test suite is a simple extension of
the standard JUnit TestSuite that keeps a member
Instrumentation variable on hand to inject into each
TestCase before running them. It is used by
InstrumentationTestRunner.

Three additional base classes extend InstrumentationTestCase to allow you to test Activity
and Provider classes:
Class

Description

ActivityTestCase

This class can be used to write tests for a specific activity. An

activity is launched in its setUp() method and finished with
tearDown. If you write a test case that extends
ActivityTestCase, you can write tests that access the
activity using getActivity() and assume it has been set up
properly.

ServiceTestCase

This test case provides a framework in which you can

test Service classes in a controlled environment. It
provides basic support for the lifecycle of a Service,
and hooks by which you can inject various
dependencies and control the environment in which
your Service is tested.

SingleLaunchActivityTestCase This class is similar to ActivityTestCase except that

the activity is launched once per class instead of

every time the test case calls setup.
ProviderTestCase

This class is similar to ActivityTestCase except that

it will setup, tear down, and provide access to the
Provider of your choice.

Understanding the am Command

The am command is a command-line interface to the ActivityManager (see

http://code.google.com/android/reference/android/app/ActivityManager.html for details). am is
used to start and instrument activities using the adb shell command, as shown in the snippet
below:
> adb shell am
usage: am [start|instrument]
am start [-a <ACTION>] [-d <DATA_URI>] [-t <MIME_TYPE>]
[-c <CATEGORY> [-c <CATEGORY>] ...]

[-e <EXTRA_KEY> <EXTRA_VALUE> [-e <EXTRA_KEY>

<EXTRA_VALUE> ...]
[-n <COMPONENT>] [-D] [<URI>]
am instrument [-e <ARG_NAME> <ARG_VALUE>] [-p <PROF_FILE>]
[-w] <COMPONENT>
For example, to start the Contacts application you can use
> adb shell am start -n com.google.android.contacts/.ContactsActivity

Platform Test Suites

This section provides an overview for various unit and functional test cases that can be executed
through the instrumentation framework.
Framework Tests

Framework test cases test the Android application framework or specific Android application
functionality that requires an Android runtime context. These tests can be found in
//device/tests and //device/apps/AndroidTests.
Core Library

Core library test cases test the Android library functionality that does not require an Android
runtime context. These tests are split into Android library (android.* package space) tests at
//device/java/tests and Java library (java.*, javax.*, etc. packages) tests at
//device/dalvik/libcore/.../tests.
Running Tests

Each instrumentation test case is similar to an Android application with the distinction that it
starts another application. For example, have a look in the tests/Contacts directory.

There should be a Makefile and an Android Manifest file.

Tests are located in tests/Contacts/src/com/google/android/contactstests.

The Instrumentation Test Runner is located at

tests/Contacts/src/com/google/android/contactstests/functional/ContactsI
nstrumentationTestRunner.java.

Suppose you have a makefile with Contactstests as the target.

make Contactstests: Compiles the test cases.

adb install Contactstests.apk: Installs the apk on the device.

Use the adb shell am command to run them.

To run your tests, use the am instrument command with your InstrumentationTestRunner as
its argument. Results are printed as a result of the instrumentation. For example, the following

snippet displays the output after running the framework tests with one test failing (note the
unusual syntax caused by how instrumentations are run via am):
$ adb shell am instrument -w
com.google.android.frameworktest/.tests.FrameworkInstrumentationTestRunner
INSTRUMENTATION_RESULT: test results:=.......F.......
Time: 6.837
There was 1 failure:
1)
testSetUpConditions(com.google.android.frameworktest.tests.focus.RequestFocusT
est)junit.framework.AssertionFailedError: requestFocus() should work from
onCreate.
at
com.google.android.frameworktest.tests.focus.RequestFocusTest.testSetUpConditi
ons(RequestFocusTest.java:66)
at java.lang.reflect.Method.invokeNative(Native Method)
at
android.test.InstrumentationTestSuite.runTest(InstrumentationTestSuite.java:73
)
at
android.test.InstrumentationTestSuite.runTest(InstrumentationTestSuite.java:73
)
at
android.test.InstrumentationTestRunner.onStart(InstrumentationTestRunner.java:
151)
at
android.app.Instrumentation$InstrumentationThread.run(Instrumentation.java:108
8)
FAILURES!!!
Tests run: 14,

Failures: 1,

Errors: 0

<RETURN> to continue
INSTRUMENTATION_CODE: -1
$

All Tests with Default TestRunner behavior

If no class or package is passed in to run, InstrumentationTestRunner will automatically find and

run all tests under the package of the test application (as defined by the
android:targetPackage attribute of the instrumentation defined in its manifest file).
$ adb shell am instrument -w \
com.android.samples.tests/android.test.InstrumentationTestRunner
INSTRUMENTATION_RESULT: Test results for InstrumentationTestRunner=..........
Time: 2.317
OK (10 tests)
INSTRUMENTATION_CODE: -1

Running all Tests Under Single Package

If you have many tests under one package, use the -e package <packagename> option to run
all tests under that package without having to manually create a test suite.
$ adb shell am instrument -w \
-e package com.android.samples.view \
com.android.samples.tests/android.test.InstrumentationTestRunner
INSTRUMENTATION_RESULT: Test results for InstrumentationTestRunner=........
Time: 1.587
OK (8 tests)

Running a Single Test Suite

If you prefer to explicitly state which tests comprise all of your tests, you can define a test suite
and run that directly. By convention, all test packages in your system should have at least one
suite called AllTests (see AllTests.java). To run all of the tests using the AllTests suite for
the api demos test app:
$ adb shell am instrument -w \
-e class com.android.samples.AllTests \
com.android.samples.tests/android.test.InstrumentationTestRunner
INSTRUMENTATION_RESULT: Test results for AllTests=..........
Time: 2.286
OK (10 tests)
INSTRUMENTATION_CODE: -1

A Single Test Case

$ adb shell am instrument -w \
-e class com.android.samples.view.Focus2ActivityTest \
com.android.samples.tests/android.test.InstrumentationTestRunner
INSTRUMENTATION_RESULT: Test results for Focus2ActivityTest=....
Time: 1.359
OK (4 tests)
INSTRUMENTATION_CODE: -1

A Single Test
$ adb shell am instrument -w \
-e class
com.android.samples.view.Focus2ActivityTest#testGoingLeftFromRightButtonGoesTo
Center \
com.android.samples.tests/android.test.InstrumentationTestRunner

INSTRUMENTATION_RESULT: Test results for Focus2ActivityTest=.

Time: 0.51
OK (1 test)
INSTRUMENTATION_CODE: -1

Attaching a debugger to your test

In order to debug your test code, instruct the controller to stop and wait for the debugger by
adding -e debug true to your command line. This causes the test runner to stop and wait for
the debugger just before calling your setUp() method. For example,
$ adb shell am instrument -w \
-e debug true \
com.android.samples.tests/android.test.InstrumentationTestRunner

Writing Tests

When writing tests, refer to the ApiDemos tests as models (located at

//device/samples/ApiDemos). This section provides an overview of the test structure with
ApiDemos.
Location of Files

Test packages should use the following structure and include Android.mk,
AndroidManifest.xml, AllTests.java, and a src directory that mirrors the src directory of the
tested application.
Files are located within a tests directory found in the root directory:
$ find samples/ApiDemos/tests
samples/ApiDemos/tests
samples/ApiDemos/tests/Android.mk
samples/ApiDemos/tests/AndroidManifest.xml
samples/ApiDemos/tests/src
samples/ApiDemos/tests/src/com
samples/ApiDemos/tests/src/com/google
samples/ApiDemos/tests/src/com/google/android
samples/ApiDemos/tests/src/com/google/android/samples
samples/ApiDemos/tests/src/com/google/android/samples/AllTests.java
samples/ApiDemos/tests/src/com/google/android/samples/ApiDemosTest.java
samples/ApiDemos/tests/src/com/google/android/samples/os
samples/ApiDemos/tests/src/com/google/android/samples/os/MorseCodeConverterTes
t.java
samples/ApiDemos/tests/src/com/google/android/samples/view
samples/ApiDemos/tests/src/com/google/android/samples/view/Focus2ActivityTest.
java
samples/ApiDemos/tests/src/com/google/android/samples/view/Focus2AndroidTest.j
ava

Contents of makefile

The contents of the makefile are similar to a normal application with the addition of a
LOCAL_INSTRUMENTATION_FOR declaration.
# Add appropriate copyright banner here
LOCAL_PATH:= $(call my-dir)
include $(CLEAR_VARS)
# We only want this apk build for tests.
LOCAL_MODULE_TAGS := tests
# Include all test java files.
LOCAL_SRC_FILES := $(call all-java-files-under, src)
# Notice that we don't have to include the src files of ApiDemos because, by
# running the tests using an instrumentation targeting ApiDemos, we
# automatically get all of its classes loaded into our environment.
LOCAL_PACKAGE_NAME := ApiDemosTests
LOCAL_INSTRUMENTATION_FOR := ApiDemos
include $(BUILD_PACKAGE)

Content of Manifest

Use the following example to create an AndroidManifest.xml file that declares the
instrumentation. Specify that the framework supplied Instrumentation TestRunner targest the
package of your application, allowing the tests that are run with the instrumentation to get access
to all of the classes of your application without having to build the source into the test app. The
name of the test application is typically the same as your target application with .tests
appended.
# Add appropriate copyright banner here
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.android.samples.tests">
<uses-permission android:name="android.permission.RUN_INSTRUMENTATION" />
<!-This declares that this app uses the instrumentation test runner targeting
the package of com.android.samples. To run the tests use the command:
"adb shell am instrument -w
com.android.samples.tests/android.test.InstrumentationTestRunner"
-->
<instrumentation android:name="android.test.InstrumentationTestRunner"
android:targetPackage="com.android.samples"
android:label="Tests for Api Demos."/>
</manifest>

The following snippet will prefix the /android.test.InstrumentationTestRunner when

running tests from the command line:
$ adb shell am instrument -w \
com.android.samples.tests/android.test.InstrumentationTestRunner

New Instrumentation TestRunner

Create a class that derives from this class. You must override two abstract methods; one that
returns the class loader of the target package, and another that defines all of the tests within the
package. For example, the snippet below displays the test runner for the framework tests.
public class FrameworkInstrumentationTestRunner extends
InstrumentationTestRunner {

OUTPUT SCREENS
Create an Android Virtual Device (AVD):

Configure the ASE:

 Select the ASE icon. This will launch the Android Scripting Environment, and
give you a screen saying Start adding scripts and Interpreters by pressing the
menu button. We need to install the Python interpreter, so, press MENU.
Along the bottom of the UI three buttons will pop up. Press the middle one
Interpreters.
This will clear the screen with only one option; Shell. Press the MENU button
again.
New buttons along the bottom, press Add
AH, a big list of stuff to install! Scroll down to Python 2.6.2 and press it.
This will start an extraction process, and you should see it extract the various
Python .zip files you had put on the virtual SD card earlier.

 Now the UI has two options, Shell and Python 2.6.2. Press Python

This launches a Python shell. Success!

OPEN THE EDIT MODE

 Hitting the return button twice will take you to another menu that has all the
default Python modules previously installed: notify_weather.py, saychat.py, etc.
Press test.py':
This will run that module, executing a variety of test suites on the emulated
device.
Pressing menu can take you into a module edit mode as well:

REFERENCES

1. https://source.android.com/source
2. https://source.android.com/source/using-repo.html
3. www.kandroid.org/online-pdk/customization.html