16

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

Yury
  • 20,618
  • 7
  • 58
  • 86
Bjarke Freund-Hansen
  • 28,728
  • 25
  • 92
  • 135

2 Answers2

11

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.

justfortherec
  • 1,590
  • 1
  • 13
  • 17
  • 1
    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. – Dean Dec 26 '22 at 21:35
9

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.

Yury
  • 20,618
  • 7
  • 58
  • 86
  • Okay, so this only works for resources, not java source I pressume? – Bjarke Freund-Hansen Feb 28 '12 at 08:04
  • I guess for Java also, but I did not check yet. – Yury Feb 28 '12 at 09:09
  • 2
    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? – Bjarke Freund-Hansen Mar 06 '12 at 08:01
  • I've just checked. You were right - it can be used only for the substitution of resource files. – Yury Mar 06 '12 at 09:01
  • 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? :) ) – Bjarke Freund-Hansen Mar 06 '12 at 09:05
  • 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? – Yury Mar 06 '12 at 09:10
  • 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. – Bjarke Freund-Hansen Mar 06 '12 at 10:25
  • 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. – Yury Mar 06 '12 at 11:58
  • You are right, this is not the right approach for a device. This is also what I concluded. But thanks for the answer. :) – Bjarke Freund-Hansen Mar 06 '12 at 13:09
  • is there any actual documentation for this ? – njzk2 Oct 30 '12 at 08:59
  • 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. – Yury Nov 02 '12 at 08:59
  • can we add new resource files using these overlays? – psykid Sep 20 '16 at 18:49
  • @Yury Is it possible to override java file now, do you have any update? – Shailendra Yadav May 07 '18 at 11:14
  • @ShailendraYadav, nope. I did not work in this area for a while. – Yury May 07 '18 at 11:20
  • Can we overlay complete layout? – AnAndroid Feb 17 '21 at 06:41
  • 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. – Dean Dec 26 '22 at 21:49
  • You can read about adding the abovemebtioned variable to a build file here: https://source.android.com/docs/setup/create/new-device – Dean Dec 26 '22 at 21:56