Introduction to Android Mainline Modules

Android’s modularity has seen a significant evolution, culminating in Project Mainline. Introduced with Android 10, Project Mainline allows Google to deliver crucial security and privacy updates directly to devices, bypassing traditional OEM update cycles for specific system components. These components, known as Mainline modules or APEX (Android Pony EXpress) modules, package critical system services like the ART runtime, Conscrypt, Media components, and more, as updateable units.

For developers, system integrators, or advanced users, understanding how to compile and flash these individual Mainline modules from source offers unprecedented control. It enables early testing of new features, applying custom patches, or debugging specific module behaviors without waiting for a full Android OS update. This guide will walk you through the expert-level process of building a Mainline module from the Android Open Source Project (AOSP) source and deploying it to an Android device.

Understanding Android Mainline Modules and APEX

Mainline modules are distributed as APEX files, which are a hybrid between APKs and traditional filesystem images. An APEX file can contain native shared libraries, executables, JAR files, and other resources. When installed, an APEX is mounted as a filesystem, making its contents available to the system. This design allows for atomic updates of system components, improving security and consistency.

• Self-contained: Each APEX holds all necessary files for its module.
• Updateable: New versions can be installed and activated on reboot.
• Signed: Cryptographically signed to ensure authenticity and integrity.
• Atomic: Either an update fully succeeds or the old version remains, preventing partial updates.

Common Mainline modules include:

• com.android.art (ART Runtime)
• com.android.conscrypt (Security Provider)
• com.android.media (Media Codecs)
• com.android.neuralnetworks (NNAPI Runtime)
• com.android.tzdata (Time Zone Data)

Prerequisites for Compilation and Flashing

Before diving into the build process, ensure you have the following:

1. A powerful Linux workstation: With ample RAM (32GB+ recommended) and disk space (300GB+).
2. AOSP Source Tree: Synced to the Android version corresponding to your target device.
3. Android SDK Platform Tools: Specifically adb and fastboot, installed and in your PATH.
4. Unlocked Android Device: A device with an unlocked bootloader and preferably running a userdebug or eng build to allow easier flashing of custom or debug-signed APEX modules.
5. Basic Linux Command Line Proficiency: Familiarity with shell commands.

Setting Up Your AOSP Build Environment

If you haven’t already, set up your AOSP build environment:

1. Sync AOSP: If your AOSP source is not current, update it:

   repo sync -j$(nproc)

2. Initialize Environment: Source the build environment script:

   source build/envsetup.sh

3. Select Target: Choose your device target. For example, if building for an AOSP Generic System Image (GSI) or Pixel device, you might use:

   lunch aosp_arm64-userdebug

It’s crucial that your AOSP source version closely matches or is compatible with the Android version on your target device, especially for core modules like ART.

Identifying a Mainline Module’s Source

Mainline modules are typically located in the packages/modules/ directory within your AOSP source tree. Each module has its own subdirectory containing its source code, build scripts (Android.bp or Android.mk), and manifests.

For this tutorial, we will use the ART Runtime module (com.android.art) as an example. Its source can be found under packages/modules/Art/.

Compiling a Specific Mainline Module

Compiling an individual Mainline module is straightforward once your environment is set up:

1. Navigate to AOSP Root: Ensure you are in the root directory of your AOSP source.
2. Build the Module: Use the m command followed by the module name. The module name often corresponds to the top-level target name defined in its Android.bp file. For ART, this is usually com.android.art.

   m com.android.art

   This command will compile the ART module and its dependencies. The output will include the APEX file and potentially other related artifacts (like JNI libraries, JARs).

3. Locate the Output APEX: After a successful build, the compiled APEX file will be located in your product’s output directory. For aosp_arm64-userdebug, it might be:

   out/target/product/generic_arm64/apex/com.android.art.apex

   Note that the exact path might vary slightly based on your lunch target.

Preparing Your Device for Flashing

Before flashing, prepare your Android device:

1. Enable Developer Options and USB Debugging: Go to Settings > About phone, tap Build number seven times. Then, in Settings > System > Developer options, enable USB debugging.
2. Connect Device: Connect your device to your workstation via USB.
3. Verify ADB Connection:

   adb devices

   You should see your device listed.

4. Root and Disable Verity (if needed for extensive testing): For advanced testing or if you encounter issues with signature validation on a userdebug build, it might be helpful to run adb root and disable dm-verity. Note that this compromises security and should only be done for development.

   adb rootadb disable-verityadb reboot

5. Check Current APEX Versions: Identify the currently active version of the module you intend to update.

   adb shell cmd apex list

   Look for the com.android.art entry and note its ActiveVersion.

Flashing the Compiled Mainline Module

The standard and recommended way to install an APEX module as an update is using pm install-apex. This command stages the APEX for activation on the next reboot, preserving system integrity.

1. Push the APEX to Device: Copy your compiled APEX file to the device’s temporary directory. Replace <AOSP_ROOT> and <DEVICE_TARGET> with your specific paths.

   adb push <AOSP_ROOT>/out/target/product/<DEVICE_TARGET>/apex/com.android.art.apex /data/local/tmp/

2. Stage the APEX for Installation: Use pm install-apex to stage the update.

   adb shell
   
           
           
           
   
               
   
                   
               
               
   
                   
   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 →