RRO (Runtime Resource Overlay) in Android AOSP

Hello Guys hope you all doing well.  !!!!

Today I am going to discuss a very important android resource framework.

Run-time Resource Overlay as it name suggest, it is resource overlay and it can be applied at run-time. I may guess not many of you know about it and google never advertise this AOSP resource framework. Android operating system has had this theming framework (RRO) built into AOSP for a few years now. With the help of RRO, we can quickly create themes that can change the look and feel of almost every app that's installed on an Android device.
As for example: - system user interface components, including navigation bar, status bar, notifications tray, and quick settings tray, themselves belong to an app, you can change their looks too. And the best part about it is that you don't have to write any Java code whatsoever for this RRO. 
What's the catch, you ask? Well, this framework(RRO) can be used only by privileged apps i.e. apps that are installed in a location that can be accessed only by the root user, or by someone who's (like us 😎) creating a custom ROM.
RRO work Mechanisms

• Android app's business logic is written in Java or Kotlin and its user interface is primarily created using XML files. 
• A well-written Android app will have separate XML resources that define its layouts, colors, strings, and attributes.
• The RRO framework, as its name suggests, lets us overlay those XML resources with your own custom XML resources. 
• It's not limited to just XML resources, It also allows you to change an app's drawables and fonts.

RRO Project Contain

• An app that uses the RRO framework usually doesn't contain any Java code. 
• It is composed only of XML files and, if necessary, fonts and images.
• Like all Android apps, it must be a valid and signed APK.

Customize the Build with RRO
By using RRO or say resource overlays, we can customize android os product at build time. So that same same Android OS behave differently in different device. Resource overlays specify resource files that are applied on top of the defaults.  To use resource overlays, we have to modify the project buildfile to set PRODUCT_PACKAGE_OVERLAYS to a path relative to our top-level directory. The most commonly customized settings are contained in the file frameworks/base/core/res/res/config.xml. To set up a resource overlay on this file, add the overlay directory to the project buildfile, as follows:
PRODUCT_PACKAGE_OVERLAYS := device/DEVICE_IMPLEMENTER/DEVICE_NAME/overlay

or

PRODUCT_PACKAGE_OVERLAYS := vendor/VENDOR_NAME/overlay

Then, add an overlay file to the directory, for example:

vendor/foobar/overlay/frameworks/base/core/res/res/config.xml

Any strings or string arrays found in the overlay config.xml file replace those found in the original file.

Build a Product with overlay
for organizing the source files for our device(custom ROM), generally we have to deal with makesfile as for example 

• device.mk
• device-vendor.mk
• AndroidProducts.mk
• BoardConfig.mk and 
• vendorsetup.sh. 

For more detail we can take Android Developer site as reference.

Example project to modify Quick setting tray

Step 1. Create a new project

I am using Linux(ubuntu) system and CLI is my favorite . So run the following command to create a new project 

mkdir MyOverlays && cd MyOverlays

touch AndroidManifest.xml

• manifest file must contain the package name of our application
• we are creating overlays for quick setting, so we must use com.android.systemui as the target package name

<?xml version="1.0" encoding="utf-8"?>

<manifest

    xmlns:android="http://schemas.android.com/apk/res/android"

    package="com.tutsplus.myoverlays">

    <overlay android:targetPackage="com.android.systemui"

             android:priority="1"/>

</manifest>

Step 2. Create a Theme
Actually we are creating a overlay for existing quick setting. Here is some point to keep in mind:-

• To overlay a resource of the target application, our application must have a resource with the same name. 
• To change the colors of the target application, we have to overlay its colors.xml file with our own colors.xml file.
• We can keep only those details that we want to change
• In this example we want to change the background color of the quick settings tray from the default blue-grey to a deep orange.
• The value of the color is specified in the res/values/colors.xml file of the system UI app. 
• you can take a look at the file on the official Android Git repository or androidxref

To change the color, we must now create a res/values/colors.xml file in our project.

mkdir -p res/values

touch res/values/colors.xml

Inside the colors.xml file, to change the background color of the tray, we must target a color named system_primary_color. Therefore, add the following XML to the file:

<?xml version="1.0" encoding="utf-8"?>

<resources>

    <color name="system_primary_color">#FFBF360C</color>

                                <!-- deep orange 900 -->

</resources>

Our simple theme is ready! If you want to, you can add more <color> tags to the file to change other colors of the system UI.

Step 3. Generate an APK
This is the last step, in this step we have to create .apk file. Android Studio automatically create .apk file for your application. But for our command line project we use AAPT(Android Asset Packaging Tool) which is a part of the Android SDK.

aapt package -M AndroidManifest.xml -S res/ \

    -I ~/Android/Sdk/platforms/android-23/android.jar \

    -F myoverlays.apk.u

In the above command, you can see that I've chosen to name the APK file myoverlays.apk.u.  That's because our APK is currently both unsigned and unaligned.

To sign our generated .apk, We use the jarsigner tool. For now, we are signing it with the default Android debug keystore. But for custom ROM development we use platform key for signing.

jarsigner -keystore ~/.android/debug.keystore \

        myoverlays.apk.u androiddebugkey

Finally, we must align—and thus optimize—the APK using the zipalign tool. As inputs, the tool expects the names of the unaligned and aligned APKs, along with a number that specifies the alignment boundaries. As of 2017, the number can be nothing else but 4.

zipalign 4 myoverlays.apk.u myoverlays.apk

Step 4. Install the APK

• To install an APK that uses the RRO framework, we must simply place it inside the /system/vendor/overlay directory. 
• The directory, by default, belongs to a read-only filesystem and is only accessible to the root user. 
• If you are a custom ROM developer(😎), or have rooted your Android device, you should have no trouble installing the APK.

however, I'll be showing you how to install the APK on an emulator. Start an emulator in the writable filesystem mode using the emulator command-line tool.

emulator -avd Nexus_5X_API_23 -writable-system
adb tool to gain root privileges on the emulator
adb root
adb remount

The /system/vendor/overlay directory doesn't exist on the emulator. We must create it manually

adb shell

mkdir -p /system/vendor/overlay

exit

Finally, push the APK to the directory using adb
adb push myoverlays.apk /system/vendor/overlay
Wait for a few seconds for Android to detect and install the APK, and then restart the emulator for the theme to take effect. After the restart, if you pull down the quick settings tray, you should be able to see the theme in action.This is the way we can create a new resource overlay or edit existing one. 

Happy Coding!!!!!