Introduction to Anbox and Custom AOSP Images

Anbox (Android in a Box) provides a way to run a full Android system in a container on Linux. Unlike traditional emulators, Anbox integrates closely with the host operating system, offering near-native performance by sharing the kernel. While Anbox comes with a pre-built Android image, there are numerous reasons why a developer or enthusiast might want to build their own custom AOSP (Android Open Source Project) image:

• Custom Features: Integrate specific Android features, services, or patches not available in the default image.
• Reduced Footprint: Create a slimmer image by removing unnecessary applications and components.
• Debugging & Development: Gain full control over the Android system for advanced debugging, system-level development, or security research.
• Specific Android Versions: Target a particular Android version that might not be officially supported or easily available.

This guide will walk you through the process of compiling a custom Android image from AOSP, focusing on preparing it for use with Anbox. We’ll leverage a standard AOSP build process and adapt the output for Anbox’s unique containerized environment.

Prerequisites: Setting the Stage for Your AOSP Build

Building AOSP is a resource-intensive process. Ensure your system meets the following minimum requirements:

Hardware Requirements:

• RAM: 16 GB or more (32 GB recommended) for a smooth build process.
• CPU: A multi-core processor (8 cores or more recommended) to accelerate compilation.
• Storage: At least 200 GB of free SSD space (NVMe recommended) for the source code and build artifacts. Hard drives are significantly slower and will prolong the build time dramatically.

Software Requirements:

We recommend using a 64-bit Linux distribution like Ubuntu 20.04 LTS or newer. The following essential packages and tools are required:

sudo apt update && sudo apt upgrade -y
sudo apt install -y git-core gnupg flex bison build-essential zip curl zlib1g-dev gcc-multilib g++-multilib libc6-dev-i386 libncurses5 lib32ncurses5-dev x11proto-core-dev libx11-dev libgl1-mesa-dev libxml2-utils xsltproc fontconfig openjdk-11-jdk python3

Additionally, you’ll need the `repo` tool, which Android uses to manage its vast collection of Git repositories:

mkdir ~/bin
PATH=~/bin:$PATH
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo

Configure Git:

Set up your Git identity for committing local changes (though not strictly necessary for just building):

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Downloading the AOSP Source Code

The first major step is to download the Android Open Source Project. This can take several hours depending on your internet connection.

1. Create a Working Directory:

mkdir aosp-anbox
cd aosp-anbox

2. Initialize the Repo Client:

Choose a stable Android branch. For this guide, we’ll use a recent public branch (e.g., Android 12). You can find available branches at source.android.com.

repo init -u https://android.googlesource.com/platform/manifest -b android-12.0.0_r30

Replace `android-12.0.0_r30` with your desired branch.

3. Synchronize the Source Code:

This command will download the entire AOSP source tree. This is the longest step.

repo sync -j$(nproc)

Configuring and Building the Custom Android Image

Once the source code is downloaded, we can prepare for the build process. Anbox primarily utilizes the Android system image (system.img) and expects a specific kernel interface from the host. We will build a generic x86_64 target, which is suitable for Anbox running on an x86_64 host.

1. Set up the Build Environment:

Navigate to your AOSP directory and source the environment script:

cd aosp-anbox
source build/envsetup.sh

2. Choose a Build Target:

We’ll select a `userdebug` target for `aosp_x86_64`. `userdebug` builds are ideal for development as they include debugging tools and root access, while still being close to a `user` build.

lunch aosp_x86_64-userdebug

Other common targets include `aosp_arm64-userdebug` for ARM-based systems, or `aosp_x86_64-eng` for even more extensive development tools and minimal optimizations.

3. Start the Compilation:

This command kicks off the actual build. The `-j` flag specifies the number of parallel tasks; `$(nproc)` uses all available CPU cores. This step can take several hours.

make -j$(nproc)

Upon successful completion, the compiled images will be located in `out/target/product/generic_x86_64/`.

Preparing the Image for Anbox

Anbox requires its Android system image to be in a SquashFS format, typically named `android.img`. The AOSP build, however, produces an EXT4 `system.img`. We need to convert it.

1. Install SquashFS Tools:

sudo apt install squashfs-tools

2. Mount the Compiled System Image:

First, create a mount point, then mount your freshly built `system.img`:

mkdir -p /mnt/android_system
sudo mount -o loop out/target/product/generic_x86_64/system.img /mnt/android_system

3. Create the SquashFS Image:

Now, create the `android.img` using `mksquashfs`. We’ll use XZ compression for better size optimization, suitable for x86 architectures.

sudo mksquashfs /mnt/android_system anbox_custom_android.img -comp xz -Xbcj x86

After this, unmount the original system image:

sudo umount /mnt/android_system

Regarding the Kernel:

It’s crucial to understand that Anbox does *not* use the kernel built by AOSP. Instead, it relies on a specific set of kernel modules (`anbox-modules-dkms`) and the host system’s kernel. Therefore, you do not need to build a kernel within AOSP for Anbox, but ensure your host kernel supports the necessary modules.

Integrating Your Custom Image with Anbox

To use your new `anbox_custom_android.img` with Anbox, you typically replace the default image or specify its path.

1. Backup Existing Image (Optional but Recommended):

If you have an existing Anbox image you wish to preserve, back it up:

sudo mv /var/lib/anbox/android.img /var/lib/anbox/android.img.bak

2. Move Your Custom Image:

Place your newly created SquashFS image into Anbox’s data directory:

sudo mv anbox_custom_android.img /var/lib/anbox/android.img

3. Restart Anbox Services:

For the changes to take effect, restart the Anbox container manager service:

sudo systemctl restart anbox-container-manager

Now, when you launch Anbox, it should use your custom-compiled Android image.

Troubleshooting Common Issues

Build Failures:

• Disk Space: AOSP requires significant disk space. Ensure you have at least 200 GB free before starting.
• Memory (RAM): `make -j` can consume a lot of RAM. If your build crashes or slows down significantly, try reducing the number of parallel jobs (e.g., `make -j4`).
• Java Version: Ensure `openjdk-11-jdk` is correctly installed and configured as the default Java compiler.

Anbox Startup Issues:

• Kernel Modules: If Anbox fails to start, verify that the `anbox-modules-dkms` are correctly installed and loaded. Run `lsmod | grep anbox`.
• Image Corruption: If your `android.img` is corrupted or incorrectly formatted, Anbox might fail to launch. Double-check the `mksquashfs` command and ensure the source `system.img` was valid.
• Logging: Check Anbox logs for specific error messages: `journalctl -u anbox-container-manager`.

Conclusion

Building a custom Anbox AOSP image provides unparalleled control over your Android environment within Linux. While it’s a demanding process in terms of system resources and time, the ability to tailor Android to your exact specifications for development, testing, or specialized use cases is invaluable. By following this guide, you’ve gained the knowledge to compile your own Android system image and integrate it seamlessly with Anbox, unlocking a new level of customization and technical insight.