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

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.

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