How to build Android for your device: From source to firmware

Building your own Android operating system is a process that opens the door to a world of deep customization and understanding how your smartphone works from the inside. Many enthusiasts strive to create custom firmwareto remove unnecessary software, speed up the device, or add features not available in stock versions. However, the path from downloading the source code to a working image of the system is long and requires care.

In this article we will analyze the key stages of preparing the environment, selecting a branch AOSP (Android Open Source Project) and directly compiling the system for specific hardware. You will learn what tools are needed to work in the terminal and how to avoid common mistakes that can turn your device into a “brick.” Be prepared for the fact that the process will require significant resources of your computer and time.

Before you begin, it is worth realizing that building Android is not just a matter of pressing one button. This is a complex engineering task that requires an understanding of the file system structure and package dependencies. Android source code takes up more than 100 GB of disk spaceand the compilation process can last from 30 minutes to several hours depending on the power of your processor and the amount of RAM.

Preparing the working environment and system requirements

The first step is to select the operating system to build. Although it is theoretically possible to build Android on macOS or even Windows (via WSL), the industry standard remains Linux. The most compatible distributions are Ubuntu or Debian, since most scripts and tools are written specifically for them. Using an unsupported OS can lead to compilation errors in the early stages.

The computer hardware requirements are also high. To work comfortably, you will need a minimum of 16 GB of RAM, although 32 GB or more is highly recommended for large projects like LineageOS. The hard drive must be type SSD with at least 250 GB of free space, since the speed of reading and writing thousands of small files critically affects the build time.

You need to install a basic set of utilities for working with repositories and compiling code. In the Linux terminal, this is done using the package manager. For example, for Ubuntu the command will look like this:

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

After installing the packages, you need to configure user rights to work with USB devices so that in the future you can easily transfer the firmware to your smartphone. It is also recommended to create a separate file system for the partition where the code will be stored, since the file system does not support Linux access rights, which will cause errors when working with Attention: Make sure that your system is configured to use UTF-8 encoding and the locale is installed correctly (for example, ext4 or xfs for the partition where the code will be stored, since the file system NTFS does not support Linux permissions, which will cause errors when working with repo And git.

⚠️ Attention: Make sure that your system is configured to use UTF-8 encoding and the locale is set correctly (for example, en_US.UTF-8), otherwise the build scripts may fail due to incorrect processing of file paths.

Initializing the repositories and selecting the Android version

After preparing the environment, you need to download the tool repothat manages the many Git repositories that make up Android. This script automatically clones the required projects and synchronizes their versions according to the manifest. You can create a working directory and download the script using the following commands:

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

Next comes the most important stage - choosing the source of the code. You can use pure AOSP from Google if you are building a system for Pixel devices, or choose a popular custom project such as LineageOS, PixelExperience or Paranoid Android. Each of them has its own manifesto and a set of patches adapted for specific hardware.

To initialize the repository, use the command repo init, where the repository URL and Android branch are indicated. For example, to download Android 13 (Tiramisu) from LineageOS, the command will look like this:

repo init -u https://github.com/LineageOS/android.git -b lineage-20.0

It is important to understand the difference between the branches. A branch master usually contains unstable code for development, while numbered branches (for example android-13.0.0_r1) represent stable releases. An error in choosing a branch may result in your device drivers simply not being compiled.

Adding device drivers (Device Tree and Vendor)

The Android source code itself does not contain proprietary drivers or specific settings for your specific smartphone. In order for the system to “see” the screen, camera, modem and sensors, you need to add Device Tree (device tree) and Vendor Blobs (binary drivers). Typically, these files are posted by developers on GitHub in separate repositories.

You need to find repositories with the name of your device (codename, for example guacamole for OnePlus 7 Pro) and add them to the local manifest configuration. This is done by creating a file .repo/local_manifests/roomservice.xml. This file contains the paths to the kernel, device, and vendor repositories.

The structure of the manifest file must strictly comply with the requirements of the build system. Example of correct filling:

Component type	Path in the repository	Source (Remote)	Branch
Kernel	kernel/manufacturer/device	github	lineage-20.0
Device tree	device/manufacturer/device	github	lineage-20.0
Vendor files	vendor/manufacturer/device	github	lineage-20.0
Configuration	device/manufacturer/config	github	master

After editing the file, you need to start synchronization with the command repo sync -c -j$(nproc --all). The flag -c loads only the current branch, saving space, and -j$(nproc --all) uses all processor cores to speed up loading. This stage may take a long time depending on the speed of your Internet connection.

⚠️ Attention: Binary drivers (Vendor Blobs) must strictly correspond to the version of Android for which the assembly is being carried out. Using drivers from Android 11 in an Android 13 build often leads to a cyclic reboot (bootloop).

Where to look for Device Tree?

Usually repositories are located on GitHub or GitLab. Search for "device manufacturer codename" or "kernel manufacturer codename". Also check the XDA Developers forums in the section of your device - there are often links to current sources from the community.

Setting up the environment and starting compilation

When all the sources are downloaded, the stage of setting up environment variables begins. The script source build/envsetup.sh loads assembly functions into the current terminal session. After this, you need to select the target device using the command lunch. You will be offered a list of available configurations, where you need to select the option with the suffix userdebug or eng for debugging, or user for the final version.

The choice of build type affects the access level and the availability of debugging tools. Type userdebug allows you to receive logs via adb logcat and has root access by default, which is critical during the first build to find errors. The final assembly of the type user is optimized for size and speed, but limits access to the system.

The compilation process itself is launched by the command mka bacon (for projects based on CyanogenMod/LineageOS) or simply make -j$(nproc) for pure AOSP. The utility mka works faster than the standard one makeas it automatically determines the number of available cores. During the process, you will see a stream of messages about module compilation:

[  5% 124/2300] Building C++ object ...
[  6% 125/2300] Linking C++ executable ...
...
Target system fs image: out/target/product/device/system.img

Compilation times vary greatly. On a powerful workstation with 16 cores this can take 40 minutes, while on a laptop with 4 cores the process will take 3-4 hours. It is not recommended to interrupt the process, as this will require clearing the cache and starting again.

Debugging errors and solving compilation problems

It’s rare that the first build goes perfectly. Most often, you will encounter compilation errors related to incompatible compiler versions or missing dependencies. Errors like error: 'string_view' in namespace 'std' does not name a type indicate problems with versions Clang or GCC. In such cases, you may need to switch to a different version of the toolchain specified in the device tree.

Another common problem is lack of memory when linking large modules, such as the browser or system libraries. If the assembly fails with an error Killed, it means that it worked OOM Killer (Out Of Memory). The solution is to increase the swap file or close unnecessary applications.

To analyze the causes of the failure, use the logs that are output to the terminal. It is often useful to redirect the output to a file for later examination:

mka bacon 2>&1 | tee build_log.txt

When examining the log, look for the last lines before the process stops. It usually contains an indication of the file that caused the error and the line number of the code. Searching for this error on the Internet or on specialized forums often leads to a ready-made solution or patch.

⚠️ Attention: The build tool interfaces (Soong, Make) and compiler requirements change with each new Android release. What worked for Android 12 may not work for Android 14 without updating the scripts.

Firmware installation and initial launch

After successful completion of the build, the following image files will appear in the folder out/target/product/device/ and others. To install them on the device, the easiest way is to use the system.img, boot.img, vendor.img and others. To install them on the device, the easiest way is to use the mode Fastbootmode. Put your smartphone into bootloader mode (usually by holding down the volume and power buttons) and connect it to the PC.

There are two installation methods: quick flashing of only modified partitions or complete wipe of the device. For the purity of the experiment, it is recommended to perform a full reset. Commands for firmware look like this:

fastboot flash boot boot.img
fastboot flash system system.img
fastboot flash vendor vendor.img
fastboot erase userdata
fastboot reboot

The first launch after installing custom firmware always takes longer than usual - the system optimizes applications (ART compilation). The screen can hang on the logo from 5 to 15 minutes. If the download lasts more than 20 minutes or the device goes into reboot, you need to analyze the logs through adb logcat in recovery mode.

What to do if the device went into Bootloop?

If the smartphone reboots cyclically, try going into Recovery mode (custom, for example, TWRP) and wipe Data and Cache sections. If this does not help, connect the phone to the PC in ADB mode (if it is detected) and remove the log: adb logcat > error_log.txt. Analysis of the log will show which service is causing the failure.

Is it possible to build Android on a weak laptop?

Technically it is possible, but the process will be extremely slow. To save resources, disable the graphical shell (use a server version of Linux without GUI) and be sure to configure ccache. You can also build only specific modules, and not the entire system, if you only need small changes.

Where to download ready-made Device Trees?

Source codes for popular devices are published on GitHub by organizations like LineageOS, PixelExperience, or individual developers. Enter your device's codename (for example, "kenzo" for Redmi Note 3) and the word "android" into the GitHub search.

Do you need an unlocked bootloader?

Yes, this is a prerequisite. Without an unlocked bootloader (Bootloader), you will not be able to flash a custom boot.img or recovery image. The unlocking procedure is different for each manufacturer and often leads to loss of warranty.