Overlays

Deep Dive: Overlays

Resource Overlays allow device manufacturers (OEMs) and system builders to replace the resources of an application or the Android framework itself without modifying the original APK. This is the primary mechanism used for custom theming, carrier-specific branding, and hardware-specific configurations.

Static Overlays (Build-Time)

Historically, Android relied heavily on static, build-time overlays. These are defined in the AOSP build system using the PRODUCT_PACKAGE_OVERLAYS and DEVICE_PACKAGE_OVERLAYS variables in device makefiles.

During the build process, the aapt (Android Asset Packaging Tool) merges the overlay resources with the target package's resources. If an overlay defines a string or color that already exists in the target package, the overlay's value silently overwrites the original.

Because this happens at build time, static overlays are baked into the final system image and cannot be modified or disabled at runtime.

Overlay Package Structure

Modern overlays are typically structured as standalone, empty Android packages (APKs) that contain only resources and no executable code.

An overlay package manifest (AndroidManifest.xml) requires a specific tag:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.vendor.theme.dark">
    
    <overlay 
        android:targetPackage="android" 
        android:priority="10" 
        android:isStatic="true" />
</manifest>

• targetPackage: The package whose resources are being replaced (e.g., android for the framework).
• priority: Determines the order of application if multiple overlays target the same package.
• isStatic: If true, the overlay is enabled by default and cannot be disabled by the user or the OverlayManagerService.

Priority and Overlay Ordering

When multiple overlays target the same resource in the same package, priority rules determine which overlay wins.

1. Overlay priority attribute: Overlays with a higher android:priority integer take precedence.
2. Directory ordering: For build-time overlays, PRODUCT_PACKAGE_OVERLAYS overrides DEVICE_PACKAGE_OVERLAYS.

Understanding priority is crucial when an OEM applies a base theme, but a specific carrier requires a further customized accent color on top of that base theme. The carrier overlay must simply be assigned a higher priority value.