How does the Android source overlays work?

Question

In the android source in the device/sample folder there is a folder called overlays. You see the same overlay folder in e.g. the cyanogen mods.

What is this overlay folder? How does it work? What is it used for? Where can I read more about it?

Thanks in advance

Tiffie

Answer 1

For instance, imagine that you want to modify some files in Android source for your device (for instance, you want to add additional string to Launcher resources). It is not recommended to modify the actual sources of Android.

Instead of this you create overlay that mimics the actual filesystem path layout of Android and put there your changed file. In case of string in Laucher, you create directories that corresponds to the path: packages/apps/Launcher2/res/values and put there modified strings.xml

Thus, when you build your device this file will be substituted.

Tomtoma

Okay, so this only works for resources, not java source I pressume? – Tiffie

I guess for Java also, but I did not check yet. – Tomtoma

From what I have been able to gather, it only works for resources, not for Java source files. Thus the usability is pretty limited IMO. @Yury: Do you have any examples of the use with Java source or any references where I can read more? – Tiffie

I've just checked. You were right - it can be used only for the substitution of resource files. – Tomtoma

Thanks, please, did you check by testing it, or do you have any source on this information? (I want a link to where you get your information? :) ) – Tiffie

I've checked at first all the examples in this folder and did not find any reference to java files. And then checked in the book "Embedded Android" - from which I know what does this folder means. And in this book I've found a clear reference that it is only possible for res files. However, it's not very difficult to check. Meanwhile, why are you interesting in this question? – Tomtoma

Thanks a lot for the reference to the book, I did not know about it previously. Porting and customising Android is something there is very little information about out there. I am interested in this question because I am working on a device running Android where we have to modify/customize the built-in apps. And I need to figure out the best way to do that. – Tiffie

Not at all ) I've discovered it not long time ago. And it is still not published. There are also several books in Korean and they want to publish these books in English but they have troubles with publishers in the USA (I asked them when the books would be available because I cannot read Korean). As for me, I'm working on research prototypes so we just modify framework classes. But for real devices this is not a right approach. – Tomtoma

You are right, this is not the right approach for a device. This is also what I concluded. But thanks for the answer. :) – Tiffie

is there any actual documentation for this ? – Logue

Try to check folders device and vendor. In the folder device there is a subdirectory called sample. This an example and there is some information. – Tomtoma

can we add new resource files using these overlays? – Lazarolazaruk

@Tomtoma Is it possible to override java file now, do you have any update? – Kenney

@ShailendraYadav, nope. I did not work in this area for a while. – Tomtoma

Can we overlay complete layout? – Discrown

You should also add PRODUCT_PACKAGE_OVERLAYS variable to your device's respective build file (which should be determined by the argument supplied to lunch command), for example: PRODUCT_PACKAGE_OVERLAYS :=vendor/foo/overlay. – Douala

You can read about adding the abovemebtioned variable to a build file here: source.android.com/docs/setup/create/new-device – Douala

Answer 2

Overlays are a way to customize resource files and do not work for source files.

Replacement works on string granularity. That means, that for strings that do not exist in the overlay file, the corresponding string from the original is used.

From the documentation:

The Android build system uses resource overlays to customize a product at build time. Resource overlays specify resource files that are applied on top of the defaults. To use resource overlays, modify the project buildfile to set PRODUCT_PACKAGE_OVERLAYS to a path relative to your top-level directory. That path becomes a shadow root searched along with the current root when the build system searches for resources.

The most commonly customized settings are contained in the file frameworks/base/core/res/res/values/config.xml.

To set up a resource overlay on this file, add the overlay directory to the project buildfile using one of the following:

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/values/config.xml

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

Issy

A very precise and technically strict answer. May I suggest you add a short and simple practical example? So that less experienced developers will have easier time learning from it. – Douala