How does the Android source overlays work?

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 advanc开发者_C百科e

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.

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.