ROM Packaging

The Android Build Output and ROM Packaging

After successfully compiling AOSP, the output is a collection of raw partition images (boot.img, system.img, vendor.img, etc.) located in out/target/product/<codename>/. While these images can be flashed individually via Fastboot, end users typically expect a single, flashable ZIP file that can be installed via custom recovery or applied as an Over-The-Air (OTA) update.

The process of packaging these images into a deployable format is handled by the AOSP release tools.

The make otapackage Command

The most common method for generating a flashable zip is the otapackage make target.

# Generate a complete OTA update zip
source build/envsetup.sh
lunch aosp_codename-userdebug
mka otapackage

This command orchestrates several steps:

1. It builds all necessary target images.
2. It generates a target-files-package.
3. It invokes ota_from_target_files to create the final zip.

The resulting zip (usually named something like aosp_codename-ota-eng.username.zip) contains the partition payloads (often in .dat or .dat.br format for Block-Based OTA) and an updater-script (or payload.bin for A/B devices).

Understanding the target-files-package

The target-files-package is an intermediate zip file containing everything needed to build the final OTA, generate signed images, or build factory images. It includes uncompressed filesystem directories, kernel binaries, and build properties.

You can build just the target files using:

# Build target files package only
mka target-files-package

This package is crucial for release engineering because it allows you to sign the release build without recompiling the entire OS.

Signing the ROM for Release

By default, AOSP builds are signed with publicly known "test keys" located in build/target/product/security/. Shipping a production device with test keys is a massive security vulnerability, as anyone could sign and install a malicious OTA update or system app.

For release, you must generate your own release keys and use the sign_target_files_apks script to re-sign the target-files-package.

1. Generating Release Keys

AOSP provides a script to generate the necessary keys (releasekey, platform, shared, media, networkstack).

# Generate custom release keys
development/tools/make_key releasekey '/C=US/ST=CA/L=Mountain View/O=Android/OU=Android/CN=Android/emailAddress=android@android.com'
# Repeat for platform, shared, media, networkstack

2. Signing the Target Files

Once you have your private keys, you use them to sign the APKs and APEX modules within the target files package.

# Sign the target files
build/tools/releasetools/sign_target_files_apks \
    -o \
    -d vendor/mykeys \
    out/target/product/codename/obj/PACKAGING/target_files_intermediates/*-target_files-*.zip \
    signed-target-files.zip

3. Generating the Signed OTA

Finally, you generate the OTA package from the newly signed target files.

# Generate the signed OTA zip
build/tools/releasetools/ota_from_target_files \
    -k vendor/mykeys/releasekey \
    signed-target-files.zip \
    signed-ota-update.zip

Distributing the ROM Zip

When distributing the ROM, it is vital to provide users with instructions and verification methods.

A/B vs. Non-A/B Devices

Modern Android devices use A/B (Seamless) updates. Instead of an updater-script, A/B OTA zips contain a payload.bin file. The update_engine daemon applies this payload to the inactive slot while the user continues to use the device.

If you are packaging for an A/B device, the otapackage command automatically handles the generation of payload.bin using the brillo_update_payload tool.

Fastboot Images

For developers or recovery scenarios, distributing raw Fastboot images is often preferred. You can use the img_from_target_files tool to generate a flashable image-codename.zip containing system.img, vendor.img, etc.

# Generate fastboot image zip
build/tools/releasetools/img_from_target_files \
    signed-target-files.zip \
    signed-fastboot-images.zip

By mastering the packaging and signing processes, you ensure that your custom AOSP build is secure, verifiable, and easily deployable to end users.