Creating firmware on Android: a complete guide

Developing your own operating system for a mobile device is the highest level of modding in the world, requiring a deep understanding of Linux and Android architecture. The process of creating firmware is radically different from simply flashing a finished image, since here you act as an architect assembling a system from thousands of source codes. Many users confuse installing a custom recovery or a ready-made ZIP archive with a real build, but we are talking specifically about compiling a system from scratch or based on AOSP.

You have to plunge into the world of console utilities, scripts and dependencies, where every syntax error can lead to bootloop or complete inoperability of the device. This is not just fun, but a serious engineering task that requires a powerful computer running Linux and a stable Internet connection. If you are willing to spend hours at the terminal, studying logs and fixing driver conflicts, then creating your own build will be an exciting journey for you.

The modern Android ecosystem is based on a project Android Open Source Projectthat provides open access to the code, but requires enormous computing resources from the developer. You will have to manage gigabytes of source code, configure the environment and understand how the kernel, HAL level and frameworks interact. Only after successfully completing all stages will you receive a working .img file ready for installation on the device.

Preparing the working environment and tools

The first and most critical stage is selecting and configuring the operating system for assembly. Although it is theoretically possible to build Android on macOS or even Windows (via WSL), the distribution remains the industry standard Ubuntu or Debian. All Google scripts are tailored for these systems, and any deviations can lead to compilation errors at later stages. You will need a computer with at least 16 GB of RAM, although 32 GB is highly recommended for comfortable work with Android 12 and higher.

You must install a package of necessary libraries and dependencies, without which the compiler will simply refuse to work. The list of packages may vary depending on the distribution, but the basic set includes compilers, Git utilities, and image tools. The installation process is as follows:

sudo apt-get install git-core gnupg flex bison gperf 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 basic tools, you need to configure environment variables and access rights. Particular attention should be paid to the version Java Development Kit (JDK)as different versions of Android require strictly defined versions of Java. For example, older versions of Android may require JDK 8, while new builds need JDK 11 or 17. Version mismatches are one of the most common reasons why builds fail with mysterious errors.

⚠️ Warning: Use a clean Linux installation or virtual machine. Trying to set up a building environment on the main working system can lead to library conflicts and disruption of other apps.

Working with repositories and obtaining source code

The basis of any custom firmware is the source code, which is distributed through the Git version control system. Google uses a special tool called repothat manages many Git repositories at the same time. You need to download this script, put it in PATH and make it executable. This is the bridge between your computer and the giant AOSP code repositories.

The source download process (sync) can take from several hours to a day depending on the speed of your Internet channel, since the data volume often exceeds 100-200 GB. The initialization command looks like this:

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

Here it is important to correctly specify the branch (-b) corresponding to the desired version of Android. After initialization, the direct download of packages is started with the command repo sync. At this point, a local copy of the entire project structure is created, including the kernel, drivers, frameworks and system applications. Interrupting this process may require restarting it, so it is recommended to use a stable connection.

• 📂 Manifest — An XML file describing the project structure and links to all necessary Git repositories.
• 🔗 Remote —a remote code repository from which data is downloaded.
• 🌿 Branch —a specific version of the code (branch) corresponding to a specific release Android.
• 📱 Device tree - a set of configuration files specific to specific smartphone hardware.

However, “naked” AOSP will not work on your device without proprietary blobs and device-tree. These files are usually provided by manufacturers or by the community on forums like XDA Developers. You need to find a device-tree repository specifically for your model (for example Xiaomi Mi 9 or Samsung Galaxy S10) and integrate it into the local project structure, often replacing standard manifest files with local links.

Adaptation of Device Tree and Vendor Blobs

The most difficult part of creating the firmware is adapting the Device Tree to the version of Android being built. Device Tree contains information about how the operating system should interact with the hardware: processor, camera, screen and sensors. If you take the tree from Android 10 and try to build Android 13 on top of it, you will find a lot of API conflicts and changes in the kernel structure.

You will have to manually edit configuration files such as BoardConfig.mk and device.mk. These files contain paths to proprietary libraries (Vendor Blobs), which the device manufacturer does not make publicly available. These binaries are necessary for the operation of proprietary components such as the modem or graphics accelerator. Without them, the system either will not boot or will work with critical errors.

Configuration file	Purpose	Criticality
BoardConfig.mk	Defines compilation parameters and architecture	High
device.mk	List of copied files and installed APK	High
Android.mk	Build rules for specific modules	Medium
fstab.qcom	File system partition table	Critical

Often developers have to use hex editors to analyze binary files or patch the kernel to make old drivers work with new versions of Android. This requires knowledge of the C language and an understanding of the Linux Kernel. Errors at this stage result in the phone turning on, but the touchscreen, sound or communication does not work.

⚠️ Attention: Never use Device Tree from a different device model, even if they have the same processor. Differences in the wiring of components can lead to physical damage to the smartphone (for example, burning out the power controller).

What are Vendor Blobs?

These are proprietary binary files (drivers) that device manufacturers are not required to make publicly available. They are necessary for the operation of specific equipment. Without them, Android will not be able to control the camera, modem or GPU.

The process of compiling and building the image

When all the sources are downloaded and configured, the compilation process begins. This is the point where text code turns into machine instructions. To start the build, a script is used lunch, which allows you to select the target configuration. You must select the correct build target that matches your device, for example, aosp_device_codename-userdebug.

After selecting the target, the build command is launched. Depending on the version of Android and the tools used, it may look like make or mka bacon (in the case of using scripts from projects like LineageOS). The process can last from 20 minutes to several hours, loading the processor at 100%. At this time, the system compiles thousands of files in the correct order, taking into account the dependencies.

source build/envsetup.sh
lunch aosp_device-userdebug
mka bacon -j16

The parameter -j16 indicates the number of compilation threads. Its value is usually chosen equal to the number of processor threads plus one. A value that is too large can lead to a lack of RAM and a build failure, while a value that is too small can lead to an unreasonably long wait. At the end of a successful build, a ready-made ZIP archive or IMG file will appear in the folder. out/target/product/ The finished ZIP archive or IMG file will appear.

Debugging, logging and error elimination

It is rare when the first assembled firmware works perfectly. Most often you will encounter a “bootlap” (cyclical reboot) or a black screen. For diagnostics, the tool logcat i dmesgis used. By connecting the device in debug mode, you can read the system log in real time, observing the moment of failure.

Log analysis is a skill that comes with experience. You need to look for lines marked FATAL, CRASH or AndroidRuntime. Often the error lies in an incorrect file path, a missing library, or an incompatible encryption format. Having corrected the error in the Device Tree or script, you again start the compilation process, but only the changed modules, which is much faster than a complete rebuild.

• 🔍 Bootanimation — checking whether the boot animation is at least loading, which indicates the successful operation of the kernel.
• 📟 ADB Shell — access to the command line of the running system to check the mounting of partitions.
• 💾 Partition Table —checking the size of partitions in the firmware and the device for compliance.

There are specialized utilities for analyzing logs that highlight critical errors in color. If the system crashes during the initialization of services (bootanim), most likely the problem is in system settings or access rights (SELinux). If the phone turns off immediately after the manufacturer's logo, the problem is in the kernel or drivers.

Installation and initial launch of a custom assembly

After successful compilation and basic checking of the logs, it is time to install the firmware on the device. To do this, the smartphone must have an unlocked bootloader and a custom recovery installed, for example TWRP or OrangeFox. The finished firmware ZIP file is copied to the internal memory of the device or to an SD card.

The installation process requires a complete data wipe (Wipe Data/Factory Reset), especially if you change the Android version or partition structure. In the recovery menu, you need to wipe the Dalvik, Cache, System and Data partitions. After this, the ZIP file installation is selected. If the installation is successful, the system will prompt you to reboot.

⚠️ Attention: Before downloading the new build for the first time, be sure to make a full backup (Nandroid Backup) through recovery. This is the only way to quickly return to a working state if the new system turns out to be unstable.

The first launch (Cold Boot) can last up to 10-15 minutes, as the system optimizes applications and creates caches. If the download takes longer or involves a reboot, you need to analyze the logs again. Successful login, connection availability, Wi-Fi and fingerprint sensor working means that you have created a working firmware.

Is it possible to create firmware without programming experience?

Theoretically, you can follow the instructions for porting ready-made assemblies, but to create firmware from scratch (AOSP), in-depth knowledge of Linux and Android structure is required. Without understanding the code, you will not be able to fix critical errors.

Do you need root access to build the firmware?

No, root access on the device is not needed for the build process on a PC. However, to debug and make changes to the system partitions of the already assembled firmware on the phone, superuser rights may be required.

How much disk space is needed for Android sources?

One ​​version of Android requires about 250-300 GB of free space. If you plan to build multiple versions or store history, it is recommended to have an SSD of at least 1 TB.

What to do if the build aborts with an error?

You need to read the last lines of the terminal output. Often the error indicates a missing dependency or syntax error. Searching for the error text on Google or on the XDA forums usually helps to find a solution.