1 This directory contains code, tools and data related to time zone rules data 2 and updates. 3 4 Directory structure 5 =================== 6 7 distro 8 - Code related to "distros", the collection of files that can be used to 9 update time zone rules on Android devices. See distro/README for details. 10 11 input_data 12 - Contains files that provide inputs to the time zone rules update process. 13 Some files come from external sources and some are mastered in Android. 14 See also download-iana-data.py. 15 16 output_data 17 - Contains some derived files from the time zone rules update process and 18 used in the Android system image and distros. Some files are also held by 19 ICU - see also update-tzdata.py 20 21 testing 22 - Contains tools and scripts related to testing time zone update code. See 23 testing/data/README for details. 24 25 tzdatacheck 26 - Source code for a binary executed during boot and used to ensure that a 27 device doesn't boot with incompatible/outdated time zone data installed 28 /data (as could happen if the device has just received an OTA upgrade). 29 It is also responsible for committing staged install/uninstalls. 30 31 zone_compactor 32 - Used to create Android's native tzdata file format from the files 33 produced by the zic tool. See also update-tzdata.py. 34 35 36 Data file update tools 37 ====================== 38 39 download-iana-data.py 40 - A helper script run before update-tzdata.py. 41 It downloads the latest tzdata update from IANA and puts it in 42 the system/timezone/input_data/iana directory for use by the 43 update-tzdata.py script. 44 45 update-tzdata.py 46 - Regenerates the external/icu and system/timezone/output_data timezone 47 data files. 48 49 See update instructions below for how these tools are used. 50 51 IANA rules data changes 52 ======================= 53 54 When IANA release new time zone rules, the update process is: 55 56 1) Run download-iana-data.py to update the system/timezone/input_data/iana 57 file. 58 2) Make manual modifications to system/timezone/input_data/android files as 59 needed. 60 3) There are sometimes code and metadata changes associated with tzdata updates 61 that should be applied to Android's copy of ICU. 62 e.g. see http://bugs.icu-project.org/trac/search?q=2015d 63 4) Run update-tzdata.py to regenerate the system/timezone/output_data, 64 system/timezone/testing/data, external/icu runtime files and testing equivalents. 65 5) Build/flash a device image with the changes and run CTS: 66 cts-tradefed 67 run cts -m CtsLibcoreTestCases 68 run cts -m CtsIcuTestCases 69 (And any others that you think may have been affected) 70 6) Upload, review, submit the changes from external/icu and system/timezone. 71 72 REMINDER: Any prebuilt apks of OEM-specific time zone data apps .apk files 73 (i.e. ones that that contain distro files) will also need to be regenerated 74 with a new version code / string and any OEM-specific tests should be run. 75 76 77 Distro Versioning 78 ================= 79 80 The Android time zone "distro" is a zip archive containing the files needed 81 to update a device's time zone rules by overlaying files into locations in / 82 data. See distro/ for details. 83 84 The distro format (i.e. the files contained within the zip file) can change 85 between major releases as Android evolves or makes updates to components that 86 use the time zone data. 87 88 Distros have a major and minor format version number: 89 90 - Major format version numbers are mutually incompatible. e.g. v2 is not 91 compatible with a v1 or a v3 device. 92 - Minor format version numbers are backwards compatible. e.g. a v2.2 distro 93 will work on a v2.1 device but not a v2.3 device. 94 - The minor version is reset to 1 when the major version is incremented. 95 96 The most obvious/common change that can occur between Android releases is an 97 ICU upgrade, which currently requires a major format version increment: Android 98 uses the ICU4C's native format for both ICU4C and ICU4J time zone code which is 99 tied to the ICU major version. The main .dat file used by ICU is held in 100 external/icu and will naturally be updated when ICU is updated. Less obviously, 101 the distro code and files must be updated as well. 102 103 Other examples of changes that affect format versioning: 104 105 Major version increment: 106 - A non-backwards compatible change to the tzdata or tzlookup.xml files used 107 by bionic / libcore. 108 - Removal of an existing file from the distro. 109 110 Minor version increment: 111 - Backwards compatible changes: 112 - A new file in the distro. 113 - Additional required data in an existing file (e.g. a backwards compatible 114 change to tzdata / tzlookup.xml). 115 116 117 Changing the distro format version 118 ---------------------------------- 119 120 1) Modify distro/core/src/main/com/android/timezone/distro/DistroVersion.java: 121 - CURRENT_FORMAT_MAJOR_VERSION, CURRENT_FORMAT_MINOR_VERSION 122 2) Modify: tzdatacheck/tzdatacheck.cpp 123 - SUPPORTED_DISTRO_MAJOR_VERSION, SUPPORTED_DISTRO_MINOR_VERSION 124 3) Run update-tzdata.py to regenerate the system/timezone/output_data, 125 system/timezone/testing/data, external/icu runtime files and testing equivalents. 126 4) Build/flash a device image with the changes and run CTS: 127 cts-tradefed 128 run cts -m CtsHostTzDataTests 129 run cts -m CtsLibcoreTestCases 130 5) Run non-CTS test cases: 131 make -j30 FrameworksServicesTests 132 adb install -r -g \ 133 "${ANDROID_PRODUCT_OUT}/data/app/FrameworksServicesTests/FrameworksServicesTests.apk" 134 adb shell am instrument -e package com.android.server.timezone -w \ 135 com.android.frameworks.servicestests \ 136 "com.android.frameworks.servicestests/android.support.test.runner.AndroidJUnitRunner" 137 6) Upload, review, submit the changes from system/timezone. 138 139 REMINDER: Any prebuilt apks of OEM-specific time zone data apps .apk files 140 (i.e. ones that that contain distro files) will also need to be regenerated 141 with a new version code / string and any OEM-specific tests should be run. 142 143
