1Android Utility Function Library
2================================
3
4
5If you need a feature that is native to Linux but not present on other
6platforms, construct a platform-dependent implementation that shares
7the Linux interface.  That way the actual device runs as "light" as
8possible.
9
10If that isn't feasible, create a system-independent interface and hide
11the details.
12
13The ultimate goal is *not* to create a super-duper platform abstraction
14layer.  The goal is to provide an optimized solution for Linux with
15reasonable implementations for other platforms.
16
17
18
19Resource overlay
20================
21
22
23Introduction
24------------
25
26Overlay packages are special .apk files which provide no code but
27additional resource values (and possibly new configurations) for
28resources in other packages. When an application requests resources,
29the system will return values from either the application's original
30package or any associated overlay package. Any redirection is completely
31transparent to the calling application.
32
33Resource values have the following precedence table, listed in
34descending precedence.
35
36 * overlay package, matching config (eg res/values-en-land)
37
38 * original package, matching config
39
40 * overlay package, no config (eg res/values)
41
42 * original package, no config
43
44During compilation, overlay packages are differentiated from regular
45packages by passing the -o flag to aapt.
46
47
48Background
49----------
50
51This section provides generic background material on resources in
52Android.
53
54
55How resources are bundled in .apk files
56~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
57Android .apk files are .zip files, usually housing .dex code,
58certificates and resources, though packages containing resources but
59no code are possible. Resources can be divided into the following
60categories; a `configuration' indicates a set of phone language, display
61density, network operator, etc.
62
63 * assets: uncompressed, raw files packaged as part of an .apk and
64           explicitly referenced by filename. These files are
65           independent of configuration.
66
67 * res/drawable: bitmap or xml graphics. Each file may have different
68                 values depending on configuration.
69
70 * res/values: integers, strings, etc. Each resource may have different
71               values depending on configuration.
72
73Resource meta information and information proper is stored in a binary
74format in a named file resources.arsc, bundled as part of the .apk.
75
76Resource IDs and lookup
77~~~~~~~~~~~~~~~~~~~~~~~
78During compilation, the aapt tool gathers application resources and
79generates a resources.arsc file. Each resource name is assigned an
80integer ID 0xppttiii (translated to a symbolic name via R.java), where
81
82 * pp: corresponds to the package namespace (details below).
83
84 * tt: corresponds to the resource type (string, int, etc). Every
85       resource of the same type within the same package has the same
86       tt value, but depending on available types, the actual numerical
87       value may be different between packages.
88
89 * iiii: sequential number, assigned in the order resources are found.
90
91Resource values are specified paired with a set of configuration
92constraints (the default being the empty set), eg res/values-sv-port
93which imposes restrictions on language (Swedish) and display orientation
94(portrait). During lookup, every constraint set is matched against the
95current configuration, and the value corresponding to the best matching
96constraint set is returned (ResourceTypes.{h,cpp}).
97
98Parsing of resources.arsc is handled by ResourceTypes.cpp; this utility
99is governed by AssetManager.cpp, which tracks loaded resources per
100process.
101
102Assets are looked up by path and filename in AssetManager.cpp. The path
103to resources in res/drawable are located by ResourceTypes.cpp and then
104handled like assets by AssetManager.cpp. Other resources are handled
105solely by ResourceTypes.cpp.
106
107Package ID as namespace
108~~~~~~~~~~~~~~~~~~~~~~~
109The pp part of a resource ID defines a namespace. Android currently
110defines two namespaces:
111
112 * 0x01: system resources (pre-installed in framework-res.apk)
113
114 * 0x7f: application resources (bundled in the application .apk)
115
116ResourceTypes.cpp supports package IDs between 0x01 and 0x7f
117(inclusive); values outside this range are invalid.
118
119Each running (Dalvik) process is assigned a unique instance of
120AssetManager, which in turn keeps a forest structure of loaded
121resource.arsc files. Normally, this forest is structured as follows,
122where mPackageMap is the internal vector employed in ResourceTypes.cpp.
123
124mPackageMap[0x00] -> system package
125mPackageMap[0x01] -> NULL
126mPackageMap[0x02] -> NULL
127...
128mPackageMap[0x7f - 2] -> NULL
129mPackageMap[0x7f - 1] -> application package
130
131
132
133The resource overlay extension
134------------------------------
135
136The resource overlay mechanism aims to (partly) shadow and extend
137existing resources with new values for defined and new configurations.
138Technically, this is achieved by adding resource-only packages (called
139overlay packages) to existing resource namespaces, like so:
140
141mPackageMap[0x00] -> system package -> system overlay package
142mPackageMap[0x01] -> NULL
143mPackageMap[0x02] -> NULL
144...
145mPackageMap[0x7f - 2] -> NULL
146mPackageMap[0x7f - 1] -> application package -> overlay 1 -> overlay 2
147
148The use of overlay resources is completely transparent to
149applications; no additional resource identifiers are introduced, only
150configuration/value pairs. Any number of overlay packages may be loaded
151at a time; overlay packages are agnostic to what they target -- both
152system and application resources are fair game.
153
154The package targeted by an overlay package is called the target or
155original package.
156
157Resource overlay operates on symbolic resources names. Hence, to
158override the string/str1 resources in a package, the overlay package
159would include a resource also named string/str1. The end user does not
160have to worry about the numeric resources IDs assigned by aapt, as this
161is resolved automatically by the system.
162
163As of this writing, the use of resource overlay has not been fully
164explored. Until it has, only OEMs are trusted to use resource overlay.
165For this reason, overlay packages must reside in /system/overlay.
166
167
168Resource ID mapping
169~~~~~~~~~~~~~~~~~~~
170Resource identifiers must be coherent within the same namespace (ie
171PackageGroup in ResourceTypes.cpp). Calling applications will refer to
172resources using the IDs defined in the original package, but there is no
173guarantee aapt has assigned the same ID to the corresponding resource in
174an overlay package. To translate between the two, a resource ID mapping
175{original ID -> overlay ID} is created during package installation
176(PackageManagerService.java) and used during resource lookup. The
177mapping is stored in /data/resource-cache, with a @idmap file name
178suffix.
179
180The idmap file format is documented in a separate section, below.
181
182
183Package management
184~~~~~~~~~~~~~~~~~~
185Packages are managed by the PackageManagerService. Addition and removal
186of packages are monitored via the inotify framework, exposed via
187android.os.FileObserver.
188
189During initialization of a Dalvik process, ActivityThread.java requests
190the process' AssetManager (by proxy, via AssetManager.java and JNI)
191to load a list of packages. This list includes overlay packages, if
192present.
193
194When a target package or a corresponding overlay package is installed,
195the target package's process is stopped and a new idmap is generated.
196This is similar to how applications are stopped when their packages are
197upgraded.
198
199
200Creating overlay packages
201-------------------------
202
203Overlay packages should contain no code, define (some) resources with
204the same type and name as in the original package, and be compiled with
205the -o flag passed to aapt.
206
207The aapt -o flag instructs aapt to create an overlay package.
208Technically, this means the package will be assigned package id 0x00.
209
210There are no restrictions on overlay packages names, though the naming
211convention <original.package.name>.overlay.<name> is recommended.
212
213
214Example overlay package
215~~~~~~~~~~~~~~~~~~~~~~~
216
217To overlay the resource bool/b in package com.foo.bar, to be applied
218when the display is in landscape mode, create a new package with
219no source code and a single .xml file under res/values-land, with
220an entry for bool/b. Compile with aapt -o and place the results in
221/system/overlay by adding the following to Android.mk:
222
223LOCAL_AAPT_FLAGS := -o com.foo.bar
224LOCAL_MODULE_PATH := $(TARGET_OUT)/overlay
225
226
227The ID map (idmap) file format
228------------------------------
229
230The idmap format is designed for lookup performance. However, leading
231and trailing undefined overlay values are discarded to reduce the memory
232footprint.
233
234
235idmap grammar
236~~~~~~~~~~~~~
237All atoms (names in square brackets) are uint32_t integers. The
238idmap-magic constant spells "idmp" in ASCII. Offsets are given relative
239to the data_header, not to the beginning of the file.
240
241map          := header data
242header       := idmap-magic <crc32-original-pkg> <crc32-overlay-pkg>
243idmap-magic  := <0x706d6469>
244data         := data_header type_block+
245data_header  := <m> header_block{m}
246header_block := <0> | <type_block_offset>
247type_block   := <n> <id_offset> entry{n}
248entry        := <resource_id_in_target_package>
249
250
251idmap example
252~~~~~~~~~~~~~
253Given a pair of target and overlay packages with CRC sums 0x216a8fe2
254and 0x6b9beaec, each defining the following resources
255
256Name          Target package  Overlay package
257string/str0   0x7f010000      -
258string/str1   0x7f010001      0x7f010000
259string/str2   0x7f010002      -
260string/str3   0x7f010003      0x7f010001
261string/str4   0x7f010004      -
262bool/bool0    0x7f020000      -
263integer/int0  0x7f030000      0x7f020000
264integer/int1  0x7f030001      -
265
266the corresponding resource map is
267
2680x706d6469 0x216a8fe2 0x6b9beaec 0x00000003 \
2690x00000004 0x00000000 0x00000009 0x00000003 \
2700x00000001 0x7f010000 0x00000000 0x7f010001 \
2710x00000001 0x00000000 0x7f020000
272
273or, formatted differently
274
2750x706d6469  # magic: all idmap files begin with this constant
2760x216a8fe2  # CRC32 of the resources.arsc file in the original package
2770x6b9beaec  # CRC32 of the resources.arsc file in the overlay package
2780x00000003  # header; three types (string, bool, integer) in the target package
2790x00000004  #   header_block for type 0 (string) is located at offset 4
2800x00000000  #   no bool type exists in overlay package -> no header_block
2810x00000009  #   header_block for type 2 (integer) is located at offset 9
2820x00000003  # header_block for string; overlay IDs span 3 elements
2830x00000001  #   the first string in target package is entry 1 == offset
2840x7f010000  #   target 0x7f01001 -> overlay 0x7f010000
2850x00000000  #   str2 not defined in overlay package
2860x7f010001  #   target 0x7f010003 -> overlay 0x7f010001
2870x00000001  # header_block for integer; overlay IDs span 1 element
2880x00000000  #   offset == 0
2890x7f020000  #   target 0x7f030000 -> overlay 0x7f020000
290