Android Development
Updated 20 days ago | GitHub

Contributing back to Android

Overview

The source code for Android is available at android.googlesource.com.

The Android Open Source Project (AOSP) consists of many separate Git repositories. While each Git repo can be cloned separately, Google provides the repo tool to download and manage all of them together, and all code changes are reviewed through the AOSP Gerrit server. You will need the repo tool both to download the source and to upload changes for review.

Be aware that a full AOSP checkout is large. Per the official requirements, you need a 64-bit x86 Linux machine with at least 400 GB of free disk space (roughly 250 GB for the checkout and 150 GB for the build) and a minimum of 64 GB of RAM. Building Android 11 or higher requires Ubuntu 18.04 or later, and as of Android 11 macOS is no longer a supported build environment. You do not need to install a JDK yourself — the source tree ships with prebuilt versions of OpenJDK, Make, and Python 3.

Sign a Contributor License Agreement

Before Google can accept any code change, you must have a Contributor License Agreement (CLA) on file, as described in the licenses and headers guide:

Note that changes to upstream projects that AOSP imports (such as the kernel or external libraries) should be contributed to those projects directly.

Install the repo tool

Many Linux distributions package the repo launcher:

sudo apt-get install repo

Alternatively, install it manually as described in the git-repo project README:

mkdir -p ~/.bin
PATH="${HOME}/.bin:${PATH}"
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/.bin/repo
chmod a+rx ~/.bin/repo

Downloading the source code

Follow the official download guide. Create a working directory, then initialize and sync the client:

mkdir aosp
cd aosp
repo init --partial-clone --no-use-superproject -b android-latest-release -u https://android.googlesource.com/platform/manifest
repo sync -c -j8

The android-latest-release branch is the one Google recommends for building and contributing to AOSP — it always references the most recent release pushed to AOSP. The --partial-clone and --no-use-superproject flags are part of Google’s recommended init command, and repo sync -c -j8 fetches only the current branch across eight parallel jobs. Even so, the official guide says the initial sync should take a little over an hour.

repo init will ask for your name and email address; these are attached to every commit you make and appear on any change you upload for review. If you want to work on a specific release instead of the latest one, the valid branch and tag names for -b are listed on the source code tags and builds page.

Building and testing

Per the official build guide, building AOSP takes three commands from the root of the checkout:

source build/envsetup.sh
lunch aosp_cf_x86_64_only_phone-aosp_current-userdebug
m

lunch selects a build target in the form product_name-release_config-build_variant. The example above builds a Cuttlefish virtual phone, which can be run without physical hardware. The three build variants are user (production), userdebug (used for performance and power analysis), and eng (fastest builds for day-to-day development).

When exploring the codebase to find the code you want to change, Android Code Search is the recommended tool — it indexes the entire AOSP tree with cross-references.

Submitting changes

The full workflow is documented in the submit code changes guide. The short version:

Start a local branch for your change using the repo command:

repo start BRANCH_NAME

The branch name can be any name you wish; it exists only locally and should refer to the set of changes for a particular fix or feature. Then edit the code, build, test, and commit inside the affected project directory:

git add -A
git commit -s

Write the commit message with a headline of at most 50 characters, a blank line, and then a body wrapped at 72 characters explaining what the change does and why. A Gerrit Change-Id is added to the message automatically by a commit hook.

Upload the change for review:

repo upload .

A successful upload prints a remote: SUCCESS message with a link to the change on android-review.googlesource.com. In the Gerrit web UI, click SUGGEST OWNERS to add the code owners for the files you touched as reviewers, then click SEND. All changes must be reviewed by the appropriate code owners, and only Google employees can approve a change for submission; once approved, an owner merges it into Google’s internal development branch, and it flows back out to AOSP in a later release.

To revise a change after review feedback, amend the same commit and upload again — Gerrit records it as a new patchset on the same change:

git add -A
git commit --amend
repo upload .

Contributing to Android Studio and the build tools

The old tools.android.com site that documented the Android Studio tools source is gone. The source for Android Studio, the Android Gradle plugin, and related tools now lives on the studio-main branch, documented in the Android Studio source readme:

repo init -u https://android.googlesource.com/platform/manifest -b studio-main
repo sync -c -j4 -q

The checkout includes tools/adt/idea (the IntelliJ-based IDE code) and tools/base (lint, the Gradle plugin, and other build tools). Build instructions for the IDE are in studio.md — on Linux, run ./build_studio.sh from tools/idea, or open the tools/idea project in IntelliJ IDEA and run the AndroidStudio configuration. Patches to the tools follow the same repo start / repo upload Gerrit process as the rest of AOSP.

References