How to Build a Custom ROM from Android Open Source Project

When you build Android from AOSP, sometimes the process stops with errors like “soong bootstrap failed” or “ninja: job failed” after you sync the sources and start the build. This usually means the build system crashed, often because there isn’t enough memory, or some build settings are not set up correctly.

The most common reason is not enough RAM. Computers with less than 16GB of RAM often fail during the Soong step. Other reasons include setting the -j value too high, not having swap memory, or limits in Docker.

Some manufacturers provide open-source resources or developer tools, while others keep their code private. Here’s a brief list of open-source resources from some major manufacturers:

• Samsung Open Source Release Center
• Sony Developer World
• Lenovo Support
• Huawei Open Source Release Center
• Motorola Developers

With that introduction out of the way, let’s move forward under the assumption that we’re building a ROM for a basic, “vanilla” Android experience, specifically for a Google Pixel device. Once you learn the basics here, you’ll be ready to start creating customized versions for other manufacturers’ devices!

Requirements for this Guide:

• Android Open Source Project
• Pixel XL phone or an Android emulator for Linux
• 64-bit Linux Operating System – Ubuntu or Linux Mint are the most beginner-friendly, while BBQLinux was specifically created for Android developers.
• Python
• A powerful computer (compiling code requires a lot of memory and storage!)

Setting Up Your Build Environment

Let’s start by installing an Android emulator on your Linux computer. Even if you have a Google Pixel XL device, it’s safest to use an emulator to test your new ROM before trying it on your actual device. My personal recommendation is Genymotion, so I’ll guide you through that. However, you can browse other options in this “Best Android Emulators” guide, since many are also compatible with Linux.

First, go to the Genymotion website, create a free account, verify it via email, and download the appropriate installer for your Linux computer.

Open a terminal window and run these commands (replace “xxxxx” with the version in your file name):

chmod +x genymotion-xxxxx.bin
./genymotion-xxxxx.bin

When prompted, press Y to create the Genymotion directory. Then, type:

cd genymotion && ./genymotion

The installer will guide you through the remaining steps. When you reach the Add Virtual Devices window, select “Pixel XL” under Device Model, then complete the setup. You can launch this virtual device, which works much like having a Pixel XL on your desktop.

Next, let’s install Python:

sudo apt-get install python

Now you need to set up the Java Development Kit (JDK). In the terminal, enter:

sudo apt-get update
sudo apt-get install openjdk-8-jdk

At this point, you need to configure your Linux system to allow USB device access. This usually means adding a USB permissions file. Download the required 51-android.txt file, update it with your Linux username, and copy it to the appropriate folder as the root user. Now, plug in your device via USB for the new rules to take effect.

Place this updated file at:

Downloading the Android Source

The AOSP is stored on Git, so we use a tool called Repo to work with it.

First, set up a bin folder in your home directory by running:

mkdir ~/bin
PATH=~/bin:$PATH

Next, download the Repo tool:

curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo

Now, create a directory where you’ll do your work, and navigate to it:

mkdir WORKING_DIRECTORY
cd WORKING_DIRECTORY

Configure Git with your name and email – ideally use a Gmail address that you access often, since it’s needed for code review tools like Gerrit:

git config --global user.name "Your Name"
git config --global user.email you@gmail.com

Initialize Repo to pull the latest AOSP master manifest from Git:

repo init -u https://android.googlesource.com/platform/manifest

If that works, Repo will be initialized in your working directory, and you’ll see a “.repo” folder. Download the complete Android source tree by running:

repo sync

Building the Android Source

Now it’s time for those hardware binaries we mentioned before. Go to the AOSP drivers page and download the Pixel XL binaries for your Android version (for example, Android 7.1.0 NDE63P). Download both the vendor image and the hardware components. Extract the archives and run their self-extracting scripts from the root directory. Install the binaries at the root of the WORKING_DIRECTORY you created earlier.

In the Linux terminal, run:

make clobber
source build/envsetup.sh

Set your build target:

lunch aosp_marlin-userdebug
setpaths
make –j4

Congratulations, you’ve now built an Android ROM from source! To test it in the emulator, run:

emulator

Take some time to explore your new ROM in the emulator. As you’ll see, a pure “vanilla” AOSP experience is very basic—which is why manufacturers often add their own features and visual styles on top. While you can flash this ROM to a device, it probably won’t have many enhancements, and will look very plain.

Typically, manufacturers start with AOSP, add their own hardware files, change up the UI, add logos, and customize features. This will likely be your next step as well.

Stay tuned for the second part of this guide, where we’ll go through adding custom fonts, themes, and a boot animation to your new ROM!