1This directory contains code, tools and data related to time zone rules data 2and updates. 3 4Directory structure 5=================== 6 7apex 8 - Code related to the Android time zone update APEX file that can be used 9 to update time zone rules on Android devices. 10 11debug_tools 12 - Contains tools useful for debugging time zone issues on Android devices. 13 14distro 15 - Code related to "distros", the collection of files that can be used to 16 update time zone rules on Android devices. See distro/README for details. 17 18input_data 19 - Contains files that provide inputs to the time zone rules update process. 20 Some files come from external sources and some are mastered in Android. 21 See also download-iana-data.py. 22 23input_tools 24 - Contains tools that generate Android time zone files. 25 26output_data 27 - Contains some derived files from the time zone rules update process and 28 used in the Android system image, distros and APEX files. Some files are 29 also held by ICU - see also update-tzdata.py 30 31testing 32 - Contains tools and scripts related to testing time zone update code. See 33 testing/data/README for details. 34 35tzdatacheck 36 - This is for the "time zone updates via APK" feature. 37 Source code for a binary executed during boot and used to ensure that a 38 device doesn't boot with incompatible/outdated time zone data installed 39 in /data (as could happen if the device has just received an OTA upgrade). 40 It is also responsible for committing staged install/uninstalls. 41 42 43 44Data file update tools 45====================== 46 47download-iana-files.py 48 - A helper script run before update-tzdata.py. 49 It downloads the latest tzdata and/or tzcode files from IANA and puts them 50 in the input_data/iana and input_tools/iana directories for use by the 51 update-tzdata.py script. See download-iana-files.py --help for more. 52 53update-tzdata.py 54 - Regenerates the external/icu and system/timezone/output_data timezone 55 data files. 56 57See update instructions below for how these tools are used. 58 59IANA rules data changes 60======================= 61 62When IANA release new time zone rules, the update process is: 63 641) Run "download-iana-files.py --data" to update the input_data/iana file. 652) Make manual modifications to input_data/android files as needed. 663) There are sometimes code and metadata changes associated with tzdata updates 67 that should be applied to Android's copy of ICU. 68 e.g. see http://bugs.icu-project.org/trac/search?q=2015d 694) Run update-tzdata.py to regenerate the system/timezone/output_data, 70 system/timezone/testing/data, external/icu runtime files and testing equivalents. 715) Build/flash a device image with the changes and run CTS: 72 cts-tradefed 73 run cts -m CtsLibcoreTestCases 74 run cts -m CtsIcuTestCases 75 (And any others that you think may have been affected) 766) Upload, review, submit the changes from external/icu and system/timezone. 77 78REMINDER: Any prebuilt apks of OEM-specific time zone data apps .apk files 79(i.e. ones that that contain distro files) will also need to be regenerated 80with a new version code / string and any OEM-specific tests should be run. 81APEX files containing time zone data files will also need to be regenerated. 82 83IANA tools changes 84================== 85 86Occasionally it might be necessary / desirable to update the version of zic 87used to generate Android's tzdata file. For example, if IANA introduce new 88syntax to the text rules files (e.g. asia, north_america, etc.) or adds useful 89command-line arguments to zic. This should be needed very rarely. 90 91It is recommended that this is done independently of a data update to help 92isolate unexpected changes to behavior. 93 94Note that updating the version of zic used to create the tzdata file is 95independent of the copy of zic used by ICU. Also, bionic contains 96a copy of tzcode (e.g. localtime.c) which is based on yet another IANA 97release so compatibility and consistency is a consideration. 98 99The steps for updating IANA tools are similar to updating IANA data except 100you can use "download-iana-files.py --tools" instead of "--data" and testing 101should be more rigorous. 102 103REMINDER: As above, having updated the tooling then all binaries that contain 104tzdata should also be regenerated. e.g. APK and APEX files. 105 106 107Time Zone Data Set Versioning 108============================= 109 110Android needs various files to be updated to take a time zone data update. 111These files come from various sources and we needed a concise shorthand 112to indicate compatibility between a set of files and an Android release. This is 113known as the "Time Zone Data Set Version". Currently we expect to increment this 114version with every dessert release, though this may change in future. 115 116The idea of a single version to describe time zone data updates was first 117introduced in O-MR1 with the concept of a "distro" which could be delivered by 118an APK. The Android time zone "distro" is a zip archive containing the files 119needed to update a device's time zone rules by overlaying files into locations 120in /data. See distro/ for details. 121 122The "distro" concept will be removed in a future release of Android as it is 123being replaced by an APEX file containing the same data. As the APEX contains 124the same files we continue to use a shorthand version code. See apex/ for 125details. 126 127Time Zone Data Set Versions have a major and minor version number: 128 129- Major version numbers are mutually incompatible. e.g. v2 is not compatible 130 with a v1 or a v3 device. 131- Minor version numbers are backwards compatible. e.g. a v2.2 distro will work 132 on a v2.1 device but not a v2.3 device. 133- The minor version is reset to 1 when the major version is incremented. 134 135The most obvious/common change that can occur between Android releases is an 136ICU upgrade, which currently requires a major version increment: Android uses 137the ICU4C's native file format for both ICU4C and ICU4J time zone code which is 138tied to the ICU major version. The main .dat file used by ICU is held in 139external/icu and will naturally be updated when ICU is updated. Less obviously, 140the time zone data set version code and files must be updated as well. 141 142Other examples of changes that affect format versioning: 143 144Major version increment: 145- A non-backwards compatible change to the tzdata or tzlookup.xml files used 146 by bionic / com/android/i18n/timezone code. 147- Removal of an existing file from the distro. 148 149Minor version increment: 150- Backwards compatible changes: 151 - A new file in the distro. 152 - Additional required data in an existing file (e.g. a backwards compatible 153 change to tzdata / tzlookup.xml). 154 155 156Changing the Time Zone Data Set Version 157--------------------------------------- 158 1591) Modify android_icu4j/libcore_bridge/src/java/com/android/i18n/timezone/TzDataSetVersion.java 160 - CURRENT_FORMAT_MAJOR_VERSION, CURRENT_FORMAT_MINOR_VERSION 1612) Run update-tzdata.py to regenerate the system/timezone/output_data, 162 system/timezone/testing/data, external/icu runtime files and testing equivalents. 1633) Build/flash a device image with the changes and run CTS tests: 164 atest CtsHostTzDataTests 165 atest CtsIcuTestCases 1664) Run non-CTS test cases: 167 atest FrameworksServicesTests:com.android.server.timezone 1685) Upload, review, submit the changes from system/timezone and external/icu/. 169 170REMINDER: Any prebuilt apks / apex files (i.e. ones that that contain time zone files) 171will also need to be regenerated after this change. 172 173