From Source to UKI: Compiling a Custom Android Kernel and Integrating with Systemd-boot

Introduction: The Power of Custom Kernels and Unified Boot

For advanced users and developers, the ability to compile a custom Android kernel offers unparalleled control over device performance, security, and feature set. Beyond mere compilation, integrating this custom kernel into a modern boot environment like systemd-boot via a Unified Kernel Image (UKI) provides a streamlined, secure, and vendor-agnostic boot experience. This guide delves deep into the process, from preparing your build environment and compiling a generic Android kernel to crafting its initial ramdisk and finally encapsulating everything into a systemd-boot compatible UKI.

A Unified Kernel Image (UKI) bundles the Linux kernel, its initial ramdisk (initramfs), the kernel command line, and optionally a Device Tree Blob (DTB) and other components into a single EFI executable. This self-contained approach simplifies boot management, enhances security by allowing signed images, and ensures consistency across various bootloaders that support EFI executables. Coupled with systemd-boot, which is a simple yet powerful UEFI boot manager, you gain a robust and transparent boot chain for your custom Android environment.

Prerequisites for Your Journey

Before embarking on this intricate journey, ensure you have the following:

A Linux development machine (Ubuntu/Debian recommended) with ample storage (at least 200GB free) and RAM (16GB+).
Familiarity with the Linux command line and basic shell scripting.
Understanding of Android’s boot process and kernel configurations.
Git, Repo, and essential build tools (GCC/Clang, Make, etc.).
An EFI-capable target device (e.g., an x86_64 single-board computer or VM) where you intend to boot Android.

Setting Up the Android Kernel Build Environment

First, we need to set up the environment and download the Android kernel source. We’ll use AOSP’s generic kernel for demonstration, but the principles apply to device-specific kernels too.

1. Install Essential Tools

sudo apt update && sudo apt install -y git repo bc bison flex libssl-dev make gcc build-essential libncurses-dev python3 libelf-dev clang lld device-tree-compiler

2. Initialize and Sync AOSP Kernel Source

We’ll use a prebuilt Android toolchain for simplicity. Choose a recent Android version’s kernel branch, e.g., android-13-5.15 for a Linux 5.15 kernel on Android 13.

mkdir android-kernel-src && cd android-kernel-src repo init -u https://android.googlesource.com/kernel/manifest -b android-13-5.15 --depth=1 repo sync -j$(nproc)

This will download the kernel source tree and the necessary toolchains.

Configuring and Compiling the Android Kernel

Now, let’s configure and compile the kernel. For UKI compatibility, several kernel configuration options are critical.

1. Set Up Build Environment Variables

Identify your target architecture and cross-compiler. For x86_64, it’s typically:

export ARCH=x86_64 export SUBARCH=x86_64 export CROSS_COMPILE=$(pwd)/prebuilts/clang/host/linux-x86/clang-r450784d/bin/x86_64-linux-android- export PATH=$(pwd)/prebuilts/clang/host/linux-x86/clang-r450784d/bin:$(pwd)/prebuilts/gcc/linux-x86/host/x86_64-linux-glibc2.17-4.8/bin/:$PATH

Adjust the `clang-rXXXXXXd` path to match your downloaded toolchain version.

2. Configure the Kernel

Select a `defconfig` suitable for your target. For x86_64, `x86_64_defconfig` is a good starting point.

make x86_64_defconfig

Next, invoke `menuconfig` to customize and ensure UKI readiness. Pay close attention to these settings:

General setup --> Initial RAM filesystem and RAM disk (initramfs/initrd) support (CONFIG_BLK_DEV_INITRD=y) – Essential for loading the initramfs.
Processor type and features --> EFI runtime service support (CONFIG_EFI=y) – Crucial for EFI environments.
Processor type and features --> EFI stub support (CONFIG_EFI_STUB=y) – Allows the kernel to be directly executable by UEFI firmware.
Device Drivers --> Generic Driver Options --> Support for additional firmware blobs (CONFIG_EXTRA_FIRMWARE_DIR) – Useful if you need to embed firmware.
Ensure necessary drivers for your hardware (storage controllers, network, display) are built into the kernel or as modules.

make menuconfig

3. Compile the Kernel

After saving your configuration, compile the kernel and its modules.

make -j$(nproc) make modules_install INSTALL_MOD_PATH=./out/modules

Upon successful compilation, your kernel image (bzImage for x86_64) will be in `arch/x86/boot/bzImage`, and modules will be in `out/modules`.

Crafting the Initial Ramdisk (initramfs)

The initramfs is a small root filesystem loaded into memory before the real root filesystem is mounted. For Android, it contains critical early userspace components and scripts for device initialization.

1. Obtain a Base Android Ramdisk

The easiest way is to extract an existing `ramdisk.img` from an Android build or a device’s boot partition. For a generic AOSP setup, you can often find one in the `out/target/product/generic_x86_64/ramdisk.img` if you’ve built Android previously, or download a prebuilt one.

# Assuming you have ramdisk.img cp /path/to/ramdisk.img . mkdir initramfs_extracted gunzip -c ramdisk.img | cpio -idm -D initramfs_extracted

2. Customize (Optional)

Navigate into `initramfs_extracted`. You might want to:

Add `busybox` for debugging utilities.
Modify `init.rc` or other startup scripts if specific early boot behavior is required.
Ensure necessary modules are present or linked correctly.

3. Repack the Initramfs

cd initramfs_extracted find . -print0 | cpio --null -ov --format=newc > ../new_ramdisk.cpio cd .. gzip new_ramdisk.cpio mv new_ramdisk.cpio.gz new_ramdisk.img

Now `new_ramdisk.img` is your custom initramfs.

Building the Unified Kernel Image (UKI)

We’ll use `systemd-ukify`, a tool from systemd, to create the UKI. It simplifies the process by correctly bundling the kernel, initramfs, command line, and optionally a DTB.

1. Install systemd-ukify

sudo apt install systemd-ukify # Or build from systemd source

2. Define Kernel Command Line

The kernel command line is crucial. For Android, it often includes specific `androidboot.*` parameters. Example for a minimal setup:

echo
        
        
        
            
                
            
            
                Android Mobile Specs & Compare Directory
                Are you researching mobile hardware properties, processor SoCs, GPU chipsets, or RAM configurations? Access our complete specs catalog to compare up to 5 devices side-by-side!
                Compare Devices Specs →