Customizing the Android OS sounds like a daunting task. It can be, and we’ve had our fair share of headaches.
First, the minimum requirements. A 64-bit system with 16GB RAM and 400GB disk space is needed for the build. We will build it in a Docker container to keep build configuration consistent.
It’s important that a case-sensitive filesystem be used. For some reason, Android has a handful of files in the same directory with the same filename but different case.
Although Docker will be used, we will map a local directory into the Docker container so we don’t loose the source code when the docker container is deleted. On Linux, most filesystems are case-sensitive. ext4 and btrfs come to mind. On a Mac, a case-sensitive APFS partition is fine.
This build will target a Google Pixel phone, but other phones follow a similar process.
The Android Open Source Project is commonly referred to as the AOSP.
On the build machine, install the pre-requisites:
apt install build-essential curl python git m4 zip
Download Google’s repo tool, which allows you to manage the multitude of git repos which constitute the AOSP.
curl https://storage.googleapis.com/git-repo-downloads/repo > repo
chmod 755 repo
mv repo /usr/local/bin/
Determine which branch to use
Before downloading the Android source code, you need to determine the correct branch to use.
Find a branch compatible with your device at https://source.android.com/setup/start/build-numbers.html#source-code-tags-and-builds.
Download the source code
Replace BRANCH_NAME in the code below with the one chosen above.
repo init -u https://android.googlesource.com/platform/manifest -b BRANCH_NAME
If this is your first time using ‘repo’ on your build server, you will be prompted for your Name, email, and color preference.
This info would be used if you contribute to the AOSP, but you can accept the defaults if you don’t intend to push code to Google’s server.
Once the repo is initialized, the files need to be downloaded. Run:
This will take some time.
repo will download all of the AOSP git repos (one per OS component).
While you’re waiting, you can browse the AOSP code at https://android.googlesource.com.
Grab the vendor-specific binaries from the phone
Make sure the existing image on your phone matches the branch being built.
Download the vendor files for your device and OS version from https://developers.google.com/android/drivers. The OS version is part of the branch used during ‘repo sync’. For example, If the branch was android-9.0.0_r20, the OS version is 9.0.0.
Copy these .sh files to your aosp directory.
For the Pixel, there are two files – extract-google_devices-sailfish.sh and extract-qcom-sailfish.sh.
Download and run the two files. For example:
chmod 755 extract-google_devices-sailfish.sh
chmod 755 extract-qcom-sailfish.sh
For each script, you will have to scroll through an agreement and accept it before the files can be extracted.
Both scripts extract their files under the vendor directory.
Build the OS
Load environment variables needed for building:
Setup the build for your device. For the Pixel (codename sailfish), use:
The parameter to ‘lunch’ is split in two parts by the dash ‘-‘.
The first part select the device, and the second select the build type.
aosp_sailfish chooses the aosp_sailfish.mk makefile under the devices directory.
eng instructs it to build full-os debug support. You could also replace eng with ‘userdebug’ or ‘release’.
Now it’s ready to build.
This will take a while.
Once the build completes, the images will be ready to flash. They are stored in out/target/product/generic.
Reboot your device into the bootloader. Connect your device and run
When it starts up, verify the device is recognized in recovery mode by running:
Unlock the device so the images can be flashed:
fastboot flashing unlock
Some of these commands may fail. Unless all of them fail, you can begin flashing your newly-built images.
Flash the images
fastboot flash vendor vendor.img
fastboot flash userdata userdata.img
fastboot flash system system.img
Secure the newly flashed partitions:
fastboot flashing lock
If the phone prompts to “Lock Bootloader?” select Yes by pressing the volume up/down buttons, and then press the power button to activate your selection. This will restart the phone into the bootloader screen again.
Once it reboots, you will see a green “Start” button. Press the power button to boot your newly flashed images.
The device will take some time to boot. This is normal.
Where to go from here
You can debug the OS using the images you just built.
You may also contribute to the AOSP.