Debugging Runtime Resource Overlay in AOSP

This article covers debugging techniques for implementing run-time resource overlay and also possible problems or issues you may face while implementing it.

Photo by Randy Fath on Unsplash

What is Runtime Resource Overlay?

AOSP UI Customization: Runtime Resource Overlay

How to implement RRO?

How to implement Runtime resource Overlay in AOSP source.

Possible issues may come with Overlays

While implementing Runtime resource overlay the general issue occurs that RRO may not be reflected as expected. There might be several reasons for that which can not be directly detected.

We can find the issue with RRO this way!!

Debugging RRO

Debugging RRO is very simple when they are not functioning, we need to connect our target device with ADB and start an ADB terminal.

First of all, we can capture ADB logcat and filter out the device logs by tag “idmap”

$ adb logcat -b all | grep -iE "idmap"

List all RROs available:

To check if the RROs are available and installed in the target device.

$ adb shell cmd overlay list --user current

# --user current or <User ID> Using user ID we can check the RRO is installed
#   with which user. 

Output: The list of RROs packages will be shown like this

com.example.[package names]
[ ] <package namespace>
[ ] <package namespace>
[ ] <package namespace>

Implemented RRO packages should be listed in this list. If RRO is not listed
within in above output that means the RRO is not installed with the device. In this case, you are building the RROs with an AOSP source we need to check our Android.bp configuration probably. There might be a chance you have not included the RRO module name with .mk in the build configuration.

Status of RRO on running device:

If RRO is listed in the above list then you can notice the current status of RRO.

[ ] <package namespace>

[ ]Installed & deactivated.

[X]Installed & activated.

---Installed with errors.

How to activate and deactivate RROs

# To Enable RRO
adb shell cmd overlay enable --user current {RRO package name}

# To Disable RRO
adb shell cmd overlay disable --user current {RRO package name}

Note: Static RRO should be enabled by default at boot time and Dynamic RRO will not.

Log RROs Information by package name: You can also see the RROs package full information using this command.

adb shell cmd overlay dump {RRO package}

Output: The output of the above command will show the following pieces of information about your RRO package supplied with the command.

mPackageName → The RRO package name.

mUserId → User id [0 or 10]

mTargetPackageName → Target package for which the RRO is implemented.

mTargetOverlayableName → Module name for RRO is implemented.

mBaseCodePath → RRO package APK file location.

mState → Current State of RRO

mIsEnabled → [true or false]

mIsMutable → [true or false]

mPriority → A number configured in RRO AndroidManifest.xml

mCategory → Category of RRO.

According to the above information we can take our next step to move further in debugging.

mIsEnabled is true and mIsMutable is not false which means we should probably check the mState parameter.

mState generally comes with different outputs:

mState ---> 

STATE_ENABLED 
STATE_ENABLED_IMMUTABLE
STATE_MISSING_TARGET
STATE_NO_IDMAP
STATE_UNKNOWN

If mState is showing STATE_ENABLED or STATE_ENABLED_IMMUTABLE then RRO is successfully applied and activated with the current target device.

If mState is showing STATE_MISSING_TARGET then there might be some issue with the target package either it is not installed or something else.

If mState is showing STATE_NO_IDMAP then there might be some issue with overlayable.xml or overlays.xml or maybe with RRO package AndroidManifest.xml.

If mState is showing STATE_UNKNOWN then something wrong with OverlayManagerService at the system level.

I found that STATE_NO_IDMAP is the most common issue that occurs in RRO implementation and to resolve that we should always look into the Androidmanifest.xml if overlays.xml is correctly added with the tag “ ”

android:resourcesMap="@xml/overlays"

Next, we should check the Overlay.xml and Overlable.xml entries. The resources we have added in Overlay.xml should be present in Overlable.xml.

In case we included layout.xml in RRO packages we should be careful to add all resource IDs into overlays.xml which the layout.xml file contains.

One common human error we may leave with the type of resource like the resource type should be the same while defining the resource mapping IDs in overlays.xml.

See full ID mapping of the RRO package and target package

# Step 1:
adb shell
su
ls data/resource-cache

# step 2:
idmap2 dump --idmap-path [path RRO idmap file]

Output: the output will show complete dumps of the id mapping of both packages.

target apk path : ..............
overlay apk path : ..............
0x7f000000 -> 0x7f000000 type(id/string/bool)/id of resource 

We can dump this file to any text editor and analyze if is there any issue with the resource mapping of the RRO package and target package.

Thanks for Reading! If this article was helpful. Please hit the clap!

Follow on medium https://medium.com/@narendra147h

Connect on Linked In: linkedin.com/in/narendraharny

Please Follow & subscribe to Make Android Publication by Narendra K H for prompt updates on Android platform-related blogs.

Make Android

Thank you!