Introduction: Unlocking Android Emulator Customization

The Android operating system, built upon the Android Open Source Project (AOSP), offers unparalleled flexibility for developers and enthusiasts. While flashing custom ROMs on physical devices is a well-trodden path, doing so on Android emulators – including advanced containerized solutions like Anbox and Waydroid – presents a unique set of challenges and opportunities. At the heart of this customization lies the system.img file, a crucial component representing the core Android filesystem. This expert-level guide will walk you through the process of reverse engineering, modifying, and reimplementing system.img to enable custom AOSP ROMs for debugging, feature development, and deep system analysis within an emulated environment.

Understanding and manipulating system.img empowers you to inject custom applications, modify system frameworks, alter boot behavior, and troubleshoot issues without risking a physical device. For Anbox and Waydroid users, this knowledge is particularly vital for tailoring the Android experience within their Linux-native container environments.

Understanding the Android system.img

The system.img file is essentially a disk image containing the read-only partition where the core Android operating system resides. It holds critical components such as the Android framework, system applications (like Settings, System UI), libraries, binaries, and configuration files. When an Android device or emulator boots, this image is mounted as the /system partition.

Key Characteristics:

• Filesystem Type: Historically ext4, newer Android versions often use erofs (Enhanced Read-Only File System) for better compression and performance. This guide will focus on ext4 as it’s more amenable to direct modification, but the principles extend.
• Read-Only Nature: Typically mounted as read-only to ensure system integrity. Modifications usually require flashing a new image or making runtime changes that may not persist.
• Sparse vs. Raw Images: Emulator images are often distributed in a sparse format (e.g., system.img). A sparse image contains only non-zero data blocks, making it smaller. For direct modification, it must first be converted to a raw, full-size image.

Prerequisites and Tools

To follow this guide, you’ll need a Linux-based development environment (Ubuntu, Debian, Fedora, etc.) and the following tools:

• simg2img / img2simg: Utilities for converting between sparse and raw Android images. These are typically found in AOSP build tools or can be compiled from source.
• mount / umount: Standard Linux utilities for mounting and unmounting filesystems.
• mkfs.ext4: For creating new ext4 filesystems.
• dd: For creating empty disk images.
• adb (Android Debug Bridge): For interacting with the running emulator.
• Root privileges: Many of these operations require sudo.

Step-by-Step Guide: Reverse Engineering and Modifying system.img

Step 1: Obtaining the system.img

Your system.img can come from several sources:

• AOSP Build Output: If you’re building AOSP, the image will be located in out/target/product/[your_device]/system.img.
• Android SDK Emulator: Located within your Android SDK installation, e.g., ~/.android/avd/[AVD_NAME].avd/system.img.
• Anbox/Waydroid: For Anbox, it’s typically /var/lib/anbox/android/data/system.img. For Waydroid, /var/lib/waydroid/images/system.img.

Copy the desired system.img to your working directory.

Step 2: Converting Sparse Images to Raw Format

If your system.img is a sparse image (most common for distribution), you must convert it to a raw ext4 image before you can mount and modify it. If you compiled AOSP yourself, it might already be raw.

cp /path/to/original/system.img ./system.img.sparse # Make a backup first!simg2img system.img.sparse system.img.raw

This command creates system.img.raw, which is a full-size, mountable EXT4 filesystem image.

Step 3: Mounting the Raw system.img

Now, mount the raw image to inspect its contents. Create a mount point first:

mkdir ./system_root_originalsudo mount -o loop system.img.raw ./system_root_original

You can now browse the full Android system partition:

ls -l ./system_root_original/

Explore directories like app, priv-app (system applications), bin (system binaries), etc (configuration files), and framework (Java framework libraries).

Step 4: Making Modifications and Rebuilding the Image

Directly modifying a mounted image and then simply unmounting it *may* work, but it’s often safer and more reliable to rebuild the image, especially if you need to resize it or ensure consistency. This process involves creating a new empty image, formatting it, copying the original contents, applying your changes, and then repacking.

Example Modification: Adding a Custom Application

Let’s say you want to inject a simple APK into the system partition.

1. Determine Required Size: Check the size of your original system.img.raw to ensure the new image is large enough. You might add a small buffer.

du -h system.img.raw

2. Create a New Empty Image:

NEW_IMG_SIZE_MB=2048 # e.g., 2GB, ensure it's larger than original + your additionsdd if=/dev/zero of=custom_system.img bs=1M count=$NEW_IMG_SIZE_MB

3. Format the New Image as EXT4:

sudo mkfs.ext4 custom_system.img

4. Mount the New Empty Image:

mkdir ./system_root_customsudo mount -o loop custom_system.img ./system_root_custom

5. Copy Original System Contents: Transfer everything from the original mounted image to your new, empty image. This is crucial for maintaining the base system.

sudo cp -a ./system_root_original/* ./system_root_custom/

6. Apply Your Changes: Now, add your custom APK or modify files. For example, to add an APK:

sudo mkdir -p ./system_root_custom/system/app/MyCustomAppsudo cp /path/to/your/MyCustomApp.apk ./system_root_custom/system/app/MyCustomApp/MyCustomApp.apk# Ensure correct permissionssudo chown -R root:root ./system_root_custom/system/app/MyCustomAppsudo chmod -R 0755 ./system_root_custom/system/app/MyCustomApp

You could also modify configuration files in ./system_root_custom/system/etc/ or replace system binaries in ./system_root_custom/system/bin/.

7. Unmount Both Images:

sudo umount ./system_root_customsudo umount ./system_root_original

Step 5: Converting Back to Sparse (Optional, but recommended for emulators)

Many emulators prefer sparse images. Convert your custom_system.img back to sparse format:

img2simg custom_system.img custom_system.img.sparse

Step 6: Flashing and Testing on Emulator/Anbox/Waydroid

For Standard Android Emulator (AVD):

You can specify your custom image when launching the emulator:

emulator -avd [YOUR_AVD_NAME] -system ./custom_system.img.sparse

Alternatively, replace the system.img file directly within your AVD directory (make a backup first!):

cp ./custom_system.img.sparse ~/.android/avd/[YOUR_AVD_NAME].avd/system.img

For Anbox:

Anbox typically uses /var/lib/anbox/android/data/system.img. You would replace this file (after stopping the anbox container manager):

sudo systemctl stop anbox-container-managersudo cp ./custom_system.img.sparse /var/lib/anbox/android/data/system.imgsudo systemctl start anbox-container-manager

For Waydroid:

Waydroid uses images in /var/lib/waydroid/images/. You’d replace the relevant system.img there. You might also be able to perform runtime modifications if you remount /system as read-write from within a Waydroid shell:

sudo waydroid shellmount -o remount,rw /system

However, these runtime changes will likely not persist across reboots. For persistent changes, replacing the image in /var/lib/waydroid/images/ is necessary after stopping Waydroid:

sudo systemctl stop waydroid-container # Or waydroid session stop; waydroid container stopsudo cp ./custom_system.img.sparse /var/lib/waydroid/images/system.imgsudo systemctl start waydroid-container # Or waydroid session start

Debugging and Verification:

Once your emulator or container starts, use adb to connect and verify your changes:

adb shell ls /system/app/MyCustomApp # Verify your APK is thereadb logcat # Check for any boot errors or app crashes

Advanced Considerations

• dm-verity and `AVB` (Android Verified Boot): Modern Android systems use dm-verity to cryptographically verify the integrity of partitions. If the system image is modified, dm-verity will prevent booting or flag it as corrupt. For development, you often need to build AOSP with BOARD_AVB_ENABLE := false or similar flags in your BoardConfig.mk, or use specific emulator kernel command-line arguments to disable verification.
• SELinux Policies: Android’s security relies heavily on SELinux. If you add new binaries or applications, you might need to write custom SELinux policies (.te files) and compile them into your sepolicy to avoid permission denial errors. This is a complex topic beyond this guide’s scope but essential for system-level modifications.
• Differences in Virtualization: Full AOSP emulators simulate hardware more completely, while Anbox/Waydroid containerize Android on a Linux host kernel. This means some deep system changes might behave differently or require specific host kernel modules for Anbox/Waydroid (e.g., custom Binder drivers).

Conclusion

Reverse engineering and modifying the Android system.img is a powerful technique for custom ROM development, deep debugging, and extending the functionality of Android emulators, Anbox, and Waydroid. By understanding its structure, mastering image manipulation tools, and carefully applying your changes, you can unlock a new level of control over your Android development and testing environments. This detailed process provides the foundation for building truly custom Android experiences tailored to your specific needs.