How to build firmware on Android yourself: from source to ZIP

Assembling your own operating system for a smartphone is the highest aerobatics in the world of mobile modification, which opens the door to a world of complete freedom of action with your device. Unlike simply flashing ready-made images, creating firmware from scratch allows you to control every aspect of the work, remove unnecessary ones from the manufacturer and implement unique features not available in stock solutions. This process requires a deep understanding of the Linux architecture, working with the command line and patience, but the result in the form of a unique system optimized for your needs is worth it. hardware, delete unnecessary bloatware from the manufacturer and introduce unique features that are not available in stock solutions. This process requires a deep understanding of Linux architecture, command line work, and patience, but the end result is a unique system optimized for your needs.

Many enthusiasts stop at the stage of installing ready-made assemblies like LineageOS or Pixel Experience, not suspecting that they could create their own brand of firmware. However, the path from downloading the source code (Android Open Source Project) to obtaining a working file ready for installation through recovery is full of technical nuances. You'll have to deal with library dependencies, setting up cross-compilation, and resolving conflicts in device drivers. AOSP (Android Open Source Project) until working .zip file, ready for installation through recovery, is full of technical nuances. You will have to deal with library dependencies, setting up cross-compilation, and resolving conflicts in device drivers.

This guide is not a superficial overview, but rather a technical roadmap for those who are willing to dedicate the time to learning the inner workings of Android. We will analyze the key stages: from choosing a powerful server or PC to the final signature of the update package. Remember that experiments with low-level software always carry risks, so before starting any manipulations, make sure you have a working backup copy of the bootloader and data.

Hardware and software environment requirements

Building Android is a resource-intensive process that can take from several hours to a day, depending on the power of your computer and the type of build (full or incremental). For comfortable work, you will need a machine with a processor with at least 8 physical cores, although the presence of 16 threads will significantly speed up the compilation of kernel and system services. The amount of RAM is a critical factor: for building modern versions of Android (from 11 and higher), it is strongly recommended to have at least 32 GB RAMas the process of linking large binary files can consume a colossal amount of resources.

As for the host operating system, the de facto standard is distribution Ubuntu LTS (versions 20.04 or 22.04). Although it is theoretically possible to build on other Linux distributions or even on macOS, it is Ubuntu that guarantees compatibility with the Android Build System environment initialization scripts without having to dance with a tambourine. The hard drive must be type SSD or NVMe, since working with tens of thousands of small files in the repository repo on a mechanical HDD will turn the synchronization process into a torment that lasts for days.

⚠️ Attention: Versions compilers and system libraries in your OS must strictly comply with the requirements of the specific version of Android that you are going to build. Using a version that is too new gcc or clang can lead to compilation errors that are difficult for a beginner to debug.

File system preparation also plays an important role. It is recommended to use a file system ext4 with attribute support enabled casefoldif you are running the latest versions of Android, as this prevents errors when working with case-sensitive paths. Do not try to build inside virtual machines with disk forwarding or in the WSL2 subsystem without deep configuration - disk performance in such environments often becomes a bottleneck, negating the benefits of a powerful processor.

Initializing the repository and downloading the source code

The first step after installing all the necessary dependency packages (such as git, curl, python3, openjdk-11-jdkis to initialize the tool repo. Written in Python, this tool wraps Git and allows you to manage the hundreds of individual repositories that make up Android as a single entity. You need to create a working directory, for example ~/android/source, and execute the initialization command, specifying the URL of the remote repository and the desired development branch.

The choice of branch determines the version of Android that you will end up with. For stable builds, you usually choose release tags, such as android-13.0.0_r1, while for experiments you can use a branch master or main, containing the latest, but potentially unstable developments. The initialization command looks like this:

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

After successful initialization, the longest stage begins - synchronization. The command repo sync will begin downloading all the necessary projects. This process is extremely sensitive to the quality of the Internet connection; any breaks may require a restart or the use of keys to continue the interrupted download. Experienced builders often use arguments -j4 or -c (to download only the current branch) to optimize traffic and time, especially if the full commit history is not required.

• 🚀 Use repository mirrors if download speeds from official Google servers are unsatisfactory.
• 💾 Regularly take snapshots of the repository state so as not to download hundreds of gigabytes again in case of an error.
• ⚙️ Configure global git parameters (username and email) before synchronization.
• 🔍 Check the integrity of downloaded packages if you use third-party ones mirrors.

It is important to understand the directory structure after synchronization. The source code is divided into logical parts: frameworks/base contains the main code of the interface and system services, packages/apps stores system applications, and device and kernel contains drivers and kernel configurations specific to your device. Understanding this hierarchy is necessary for subsequent changes and customization.

Device configuration and device tree (Device Tree)

The most difficult part of self-assembly is adapting the universal AOSP code to the specific hardware of your smartphone. This problem is solved by the so-called Device Tree (device tree) - a set of configuration files that tells the system which processor, screen, camera and sensors are used in the gadget. Without the correct Device Tree, the assembled firmware will either not start at all (bootloop), or will work with critical errors, such as lack of communication or a non-working touchscreen.

Usually developers take the Device Tree from the manufacturer’s stock firmware or an existing custom build for a given model as a basis. These files are located in the device/<vendor>/<codename> and kernel/<vendor>/<device>directories. The key file here is BoardConfig.mk, where the parameters of memory sections, kernel addressing and compilation flags are written. An error in calculating the partition size system or vendor will result in the image simply not being written to the device’s flash memory.

⚠️ Attention: Never use Device Tree from a device with a different processor or architecture. Trying to run a configuration from Snapdragon on a device with MediaTek or Exynos is guaranteed to result in a “brick”, requiring recovery via EDL or SP Flash Tool.

In addition, you need to correctly configure the files product.mkthat determine which applications and features will be included in the build by default. This is where you decide whether your firmware will come pre-installed with a browser, a calculator, or specific Google services (GApps). To integrate Google services, you will need to add the appropriate inheritance scripts, since pure AOSP does not have them due to licensing restrictions.

What are Vendor Blobs?

These are proprietary binary drivers (closed code) that the processor manufacturer provides for the operation of specific equipment (modem, ISP cameras, DSP audio). Without them, the system will not be able to interact with the hardware, even if the kernel is assembled correctly. They need to be extracted from the stock firmware and placed in the vendor folder.

Compilation process and optimization of parameters

When the environment is configured and the sources are downloaded and configured, the moment of truth comes - starting the compilation. Before this, you need to initialize the build script execution environment by running the command source build/envsetup.sh, and then select the target device with the command lunch. Selecting a target (for example, aosp_-userdebug) determines the type of build: user for release (optimized, without debugging), userdebug for testing (with root access and debugging) or eng for developers.

The compilation itself is started by the command mka (Make Kotlin Android), which is a faster and smarter version of the standard make. It automatically determines the number of available processor cores and distributes tasks in parallel. The process of compiling the kernel and user space can take from 30 minutes to several hours. At this time, the terminal will be filled with a stream of logs, and it is critical to monitor the appearance of error messages that can stop the process.

Build type	Optimization	Debugging	Purpose
user	Full (O2/O3)	Disabled	Final release for users
userdebug	Partial	Enabled (adb root)	Testing and Function debugging
eng	Minimal	Full	Development of drivers and kernel
target-files	Depends on the purpose	Depends on the purpose	Creating an OTA package for updating

To speed up re-builds, the mechanism ccache (compiler cache) is used. It saves the results of object compilation and, when restarted, if the code has not changed, it substitutes ready-made binaries from the cache. Correctly setting the cache size (for example, to 50-100 GB) can reduce the rebuild time after making minor edits from hours to minutes.

Creating an OTA package and signing the firmware

After successful compilation you will have a set of raw images on your disk (boot.img, system.img, vendor.img and others). However, for convenient installation via custom recovery (for example, TWRP), these images need to be packaged in a single ZIP archive, called an OTA package (Over-The-Air). For this, a utility brass or target-files generation scripts are used, which assemble all components into a structure understandable to the installer.

A critically important step is the cryptographic signature of the received package. Android verifies the digital signature when installing updates to ensure that the firmware has not been modified by third parties. If you are building firmware for personal use and installing it via custom recovery, signature verification is often disabled or requires disabling verification in vbmeta. However, to create a full release, you need to generate your signing keys using openssl and register them in the build configuration.

The command for generating the final ZIP package usually looks like mka otatools followed by running the script sign_target_files_apks. The result will be a file like ota.zip, which can be copied to the device and flashed. Do not forget that the size of the final archive depends on the number of included applications and resource compression.

⚠️ Attention: When signing the firmware, the keys are stored in the source folder. Never give your private keys (.pk8 and .x509.pem) to third parties, as an attacker will be able to sign a malicious update with the name of your project.

If you plan to distribute your firmware publicly, it is worth setting up automatic signing on a dedicated build server (CI/CD) so that the keys are not stored on the developer’s local machine. This increases the security of the entire project and user confidence in your product.

Debugging errors and analyzing logs

It’s rare that the first build goes perfectly. Most often you will encounter compilation errors (C++, Java or kernel build errors) or problems during the boot loop. To diagnose compilation problems, you need to carefully analyze the terminal output, paying attention to the files that caused the error and missing dependencies. Often the problem is solved by installing a missing library in the system or correcting a syntax error in Android.mk or Android.bp.

If the firmware is assembled, but the phone does not boot, logcatbecomes the main debugging tool. By connecting the device to the PC in recovery mode or via ADB (if the system is partially booted), you can display the system log with the command:

adb logcat -b all > crash_log.txt

In the logs you should look for tags FATAL, AndroidRuntime or messages from initthat indicate the reason for the loss of system services. A common problem is incompatibility of library versions libc or errors in the configuration fstabresponsible for mounting partitions. It is also useful to use dmesg to analyze kernel logs, especially if the problem is related to hardware drivers.

• 🐛 Look for "Process died" or "Exception" lines in the logs to quickly find a failure.
• 🔧 Check permissions in configuration files system.
• 💡 Use an emulator for initial testing of the code before flashing the real device.
• 📚 Documentation Source.android.com is your best friend when looking for changes in the API.

The debugging process can be cyclical: making edits, rebuilding only the changed modules (so as not to wait full compilation), firmware and testing. Patience and the ability to read documentation for the Linux kernel and Android framework are key skills for a successful builder.

FAQ: Frequently asked questions about assembly

Is it possible to build firmware on a weak laptop?

Technically possible, but highly not recommended. The process will take a very long time (possibly more than 24 hours), and the risk of overheating and CPU throttling is high. In addition, if there is not enough RAM, the assembly may simply fail with an error Out of memory. For educational purposes, you can try to build a stripped-down version (GSI), but for a full-fledged Device Tree you need a powerful PC.

Where can I get drivers for my smartphone?

Drivers (proprietary binaries) are usually extracted from the official stock firmware of your device using scripts extract-files.shwhich can often be found in Device Tree repositories on GitHub for your model. It is almost impossible to write drivers from scratch without documentation from the vendor.

What is the difference between GSI and custom firmware?

GSI (Generic System Image) is a universal system image that can run on any device that supports Project Treble. Custom firmware is assembled specifically for a specific device (Device Specific) and contains optimized drivers, which provides better stability and performance than the universal GSI.

How much disk space is needed for a complete build?

Minimum 250-300 GB of free space. The source code takes up about 150 GB, but the compilation process creates temporary files, object files, and final images that require significant additional space. Using an SSD is mandatory for acceptable operating speeds.

Does assembling the firmware violate the warranty?

Assembling the firmware on your computer itself does not violate the warranty. However, unlocking the bootloader and installing custom firmware on the device will almost always void the manufacturer's warranty. In addition, some functions (for example, banking applications or Widevine L1) may stop working without additional security settings.