Android System Development Series (1): Downloading, Compiling, and Flashing A...

Word count: 1.2kReading time: 7 min

 2021/10/26

Android 12 has been officially released, and the source code is now available on the AOSP website. This article will guide you through the process of downloading and compiling the latest Android 12 code.

Compiling the code locally offers several advantages:

Direct Debugging: You can flash the build onto a physical device for local debugging and import the code into Android Studio.
Userdebug Builds: You can compile a userdebug version, which allows for root and remount access. This is invaluable for debugging both the system and apps, as it reveals information hidden in standard user builds—useful for competitive analysis and behavioral studies.
Deep Learning: It facilitates a deeper understanding of Android source code by allowing you to enable system-level debug logs, add your own logs, or even modify system workflows.

If you don’t need to compile or debug and just want to browse the code, I recommend using cs.android.com. For those who want to dive deep into the Android system, I suggest the following hardware setup:

A used, unlocked Google Pixel 3 or newer (Android 12 supports Pixel 3 and up).
A Linux desktop (preferably Ubuntu) with a large SSD, at least 32GB of RAM (or equivalent swap space), and a decent CPU to minimize compilation time.

1. Downloading the Code

Due to network restrictions in some regions, downloading directly from Google’s official site can be slow. This tutorial uses a domestic mirror as an example. If you have unrestricted internet access, you can follow the Official Google Tutorial.

USTC AOSP Mirror: https://mirrors.ustc.edu.cn/help/aosp.html

The following steps can be run on Ubuntu, WSL, WSL2, or macOS. However, since the actual compilation requires Linux, I strongly recommend using a Linux system like Ubuntu for the entire process.

1.1 Step 1: Download the Repo Tool

mkdir ~/bin
PATH=~/bin:$PATH
curl -sSL 'https://gerrit-googlesource.proxy.ustclug.org/git-repo/+/master/repo?format=TEXT' | base64 -d > ~/bin/repo
chmod a+x ~/bin/repo

1.2 Step 2: Configure Personal Information

If you haven’t installed Git yet, do so first. then configure your identity:

1 2	git config --global user.name "Your Name" git config --global user.email "you@example.com"

1.3 Step 3: Create a Working Directory

1 2	mkdir Android_12_AOSP cd Android_12_AOSP

1.4 Step 4: Initialize the Repository

There are two ways to initialize: downloading everything (the master branch) or targeting a specific Tag. Note: Your choice here will affect which driver you need to download later.

1.4.1 Option A: Download All (Recommended)

This downloads the entire source tree, defaulting to the master branch. Use this if disk space is not a major concern.

1	repo init -u git://mirrors.ustc.edu.cn/aosp/platform/manifest

If you encounter connection issues with gerrit.googlesource.com, edit ~/bin/repo or your shell configuration (.bashrc or .zshrc) to set:
REPO_URL="https://gerrit-googlesource.proxy.ustclug.org/git-repo"

1.4.2 Option B: Download a Specific Tag

This is faster as it only downloads code for a single Tag. You can find a list of Build Numbers and Tags here. For example, for my Pixel 3 XL, the relevant Android 12 Tags are android-12.0.0_r3 and android-12.0.0_r1.

1	repo init -u git://mirrors.ustc.edu.cn/aosp/platform/manifest -b android-12.0.0_r3

1.5 Step 5: Sync the Code

After initialization, download the actual files. It’s recommended to use -j4 to avoid overwhelming mirror connections.

1	repo sync -j4

Since syncing can fail due to network hiccups, you can use a simple loop script:

#!/bin/bash
repo sync -j4
while [ $? -ne 0 ]
do
    echo "====== sync failed, retrying ======"
    sleep 3
    repo sync -j4
done

2. Downloading Drivers (Proprietary Binaries)

Before compiling for a physical device, you must download proprietary driver files. Refer to the Official Documentation.

The driver you need depends on whether you synced the master branch or a specific Tag.

2.1 Drivers for the Master Branch

If you synced from master, download drivers from the AOSP Preview Page.

2.2 Drivers for a Specific Tag

If you used the -b flag with a Tag like android-12.0.0_r3, you must find the driver matching that Tag’s Build ID (e.g., SP1A.210812.016.A1). Download them from the Full Driver Page.

2.3 Extracting Drivers

Extract the downloaded files into your source root. You will get two .sh scripts. Run them, scroll through the license (using D), and type I ACCEPT.

1
2
3

# Example for Pixel 3 XL
./extract-google_devices-crosshatch.sh
./extract-qcom-crosshatch.sh

3. Compiling the Code

Now that the source and drivers are ready, let’s start the build. As a reminder, macOS is no longer supported for building newer Android versions; use Ubuntu.

3.1 Initializing the Build Environment

Run this on Ubuntu 18.04+:

sudo apt-get install git-core gnupg flex bison build-essential zip curl zlib1g-dev gcc-multilib g++-multilib libc6-dev-i386 libncurses5 lib32ncurses5-dev x11proto-core-dev libx11-dev lib32z1-dev libgl1-mesa-dev libxml2-utils xsltproc unzip fontconfig

3.2 Setting Up the Shell Environment

Every time you open a new terminal, you must run:

1	source build/envsetup.sh

3.3 Selecting a Target

lunch

Select the target corresponding to your device. For Pixel 3 XL, the codename is crosshatch. Choose aosp_crosshatch-userdebug.

3.4 Starting the Build

Use m to build the entire system. It automatically handles parallel tasks, though you can specify them with -jN.

m droid: Standard build.
m all: Builds everything, including modules not marked for the device image.
m clean: Deletes all output and intermediate files (same as rm -rf out/).

Wait for the build to finish. Total time depends on your CPU and RAM (32GB+ is highly recommended). Once completed, you’ll see a success message.

4. Flashing the Device

A local userdebug build is perfect for debugging the Framework or apps. To flash your device (using Pixel 3 XL as an example):

adb reboot fastboot

# Once in fastboot mode
fastboot flashall -w

# After flashing
fastboot reboot

The device will reboot into your custom Android 12 build. Note that the AOSP Launcher is quite basic compared to the official Pixel Launcher because it lacks Google’s proprietary enhancements.

If you encounter issues during flashing, you can always restore your device using Official Google Factory Images.

5. What’s Next?

This guide focused on downloading, compiling, and flashing. I will cover how to import code into an IDE, modify modules, and debug in a follow-up article.

About Me && Blog

Below are my personal details and links. I look forward to connecting and sharing knowledge with fellow developers!

About Me: Includes my WeChat and WeChat group links.
Blog Navigation: A guide to the content on this blog.
Curated Android Performance Articles: A collection of must-read performance optimization articles. Self-nominations/recommendations are welcome!
Android Performance Knowledge Planet: Join our community for more insights.