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