How to create an overlay?
This guide is only for Treble-enabled devices with stock firmware. For devices that were Treble-enabled via custom firmware, please coordinate directly with its developer.
You should also have your stock firmware on hand and a method to extract system files from it or have the stock firmware installed on your device. You can use 7-Zip ZS to extract system files inside your firmware file.
This procedure assumes that you use an Ubuntu or Linux Mint machine. If you are on another Linux distro, you can use Distrobox. If you are on Windows, you can use WSL.
Run the following commands:
sudo apt update
sudo apt upgrade
sudo apt install git xmlstarlet aapt apktoolGrab the APKs from the following locations. If you can't see the exact file, just take a similarly-named APK on the directory, or look at other related directories. Whatever you find, grab it and set it aside for the procedure. You can also extract them from your stock firmware file.
/system/product/overlay/framework-res__auto_generated_rro_product.apk/system/vendor/overlay/framework-res__auto_generated_rro_vendor.apk
system/framework folder. Those are extremely inaccurate generic information.
To grab the values from the overlay APKs, copy the APKs to your computer, cd into the directory where you copied them to, and run apktool d nameOfApk.apk -o ./nameOfThePartitionTheApkCameFrom.
Navigate to the product folder and get the power_profile.xml under res/xml. Do the same on the vendor folder. If there is no power profile on the product overlay or there is no difference between the power profile on the product and vendor overlays, then you don't need a power profile as it is on the vendor partition already. If there is a difference between the power profile on the product overlay and the vendor overlay, use the profile from the product overlay.
Also, under res/values, take the files named arrays.xml, bools.xml, dimens.xml, integers.xml, and strings.xml. Do this to both product and vendor.
The values on the product overlay are more accurate than the vendor partition. Also, flashing a GSI only overwrites the product partition and not the vendor partition. Therefore, the overlay you're creating only needs to include the overrides the product overlay has.
Compare the arrays.xml, bools.xml, dimens.xml, integers.xml, and strings.xml of the product and vendor partitions. Make a config.xml file and paste the following:
<?xml version="1.0" encoding="utf-8"?>
<resources>
</resources>Inside the <resources></resources> part, put in all the values that the product overlay has differences from the vendor overlay. You can use online text difference checkers for this part. Read all the examples carefully for guidance.
The vendor overlay is on the left, and the product overlay is on the right. The product overlay adds the following:
<string-array name="config_biometric_sensors">
<item>0:2:15</item>
<item>1:8:4095</item>
</string-array>Therefore, this is now our config.xml:
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string-array name="config_biometric_sensors">
<item>0:2:15</item>
<item>1:8:4095</item>
</string-array>
</resources>
The vendor overlay is on the left, and the product overlay is on the right. The product overlay does not have the following values even though the vendor overlay has those:
<bool name="config_carrier_volte_available">true</bool>
<bool name="config_carrier_volte_provisioned">true</bool>
<bool name="config_carrier_volte_tty_supported">false</bool>
<bool name="config_carrier_vt_available">true</bool>
<bool name="config_device_volte_available">true</bool>
<bool name="config_device_vt_available">true</bool>
<bool name="config_device_wfc_ims_available">true</bool>We are not gonna touch those values or add those to config.xml as it is not overridden by the product overlay.
Meanwhile, the product overlay has this value while the vendor does not have it:
<bool name="config_supportAudioSourceUnprocessed">false</bool>We are going to add it as it is not declared on the vendor overlay. This is now our config.xml:
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string-array name="config_biometric_sensors">
<item>0:2:15</item>
<item>1:8:4095</item>
</string-array>
<bool name="config_supportAudioSourceUnprocessed">false</bool>
</resources>Looking back, we have power_profile.xml and config.xml. This is what we are going to submit to the overlay repo.
Fork TrebleDroid/vendor_hardware_overlay and clone the fork to your computer.
Run the tests.sh script under the tests folder and take note of the suggested priority number it outputs.
Under the folder of your phone's brand, make a folder for your model. Inside, make a file named AndroidManifest.xml and paste this:
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="me.phh.treble.overlay.brandName.modelName"
android:versionCode="1"
android:versionName="1.0">
<overlay android:targetPackage="android"
android:requiredSystemPropertyName="ro.vendor.build.fingerprint"
android:requiredSystemPropertyValue="+*brandName/modelName*"
android:priority="yourSuggestedPriorityNumber"
android:isStatic="true" />
</manifest>Replace yourSuggestedPriorityNumber with the priority number you saw earlier. I got 553.
Replace the brandName and modelName with information from running getprop ro.vendor.build.fingerprint on a terminal on your phone. For example, if I get samsung/a03nnxx/a03:11/RP1A.200720.012/A035FXXU4CWI1:user/release-keys, my brandName is samsung and my modelName is a03. This is now my example AndroidManifest.xml:
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="me.phh.treble.overlay.samsung.a03"
android:versionCode="1"
android:versionName="1.0">
<overlay android:targetPackage="android"
android:requiredSystemPropertyName="ro.vendor.build.fingerprint"
android:requiredSystemPropertyValue="+*samsung/a03*"
android:priority="553"
android:isStatic="true" />
</manifest>Make another file named Android.mk and paste this:
LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE_TAGS := optional
LOCAL_PACKAGE_NAME := treble-overlay-brandName-modelName
LOCAL_MODULE_PATH := $(TARGET_OUT_PRODUCT)/overlay
LOCAL_IS_RUNTIME_RESOURCE_OVERLAY := true
LOCAL_PRIVATE_PLATFORM_APIS := true
include $(BUILD_PACKAGE)Just replace brandName and modelName with the values you used earlier.
Make a res folder beside the two previous files, and inside it make values and xml folders. Inside the xml folder, place the power_profile.xml from earlier. Delete the xml folder if you don't need a power profile.
Place the config.xml file from earlier in the values folder.
Open the overlay.mk file on the root of the repo you cloned and add the value of LOCAL_PACKAGE_NAME from your Android.mk to the list. Follow the alphabetical order, indentation, and don't forget the \ at the end of each item.
Go to the tests folder again and run tests.sh script once more. Look for errors for your overlay. Delete values that cause errors and run the test script again. Do this until there are no more errors for your overlay.
Go to the build folder and run the build.sh script. When it is done building, look for the treble-overlay-brandName-modelName.apk for your device. Place it on /system/product/overlay, preferably by making your own Magisk module. See if your device runs fine with the module and if all issues are fixed. If not, modify the overlay further until it works.
If the overlay works properly, you can now make a pull request to get your overlay included on TrebleDroid sources. Simply go to your fork on GitHub click Contribute then Open pull request. Fill up the necessary info and confirm the action.
Look out on your device's groups or forums if there are any issues with GSIs built after the time your pull request was approved. It may be related to your overlay. Feel free to fix it and send an updated overlay.
If you need any help, do not hesitate to ask on our Telegram group.