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