Neil Fuller | 3830d70 | 2017-08-18 17:03:59 +0100 | [diff] [blame] | 1 | This directory contains code, tools and data related to time zone rules data |
| 2 | and updates. |
Neil Fuller | 86e72c5 | 2017-06-12 15:36:06 +0100 | [diff] [blame] | 3 | |
Neil Fuller | 3830d70 | 2017-08-18 17:03:59 +0100 | [diff] [blame] | 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 | ====================== |
Neil Fuller | 86e72c5 | 2017-06-12 15:36:06 +0100 | [diff] [blame] | 38 | |
Neil Fuller | 56166d3 | 2017-06-12 12:57:10 +0100 | [diff] [blame] | 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 | |
Neil Fuller | 56166d3 | 2017-06-12 12:57:10 +0100 | [diff] [blame] | 45 | update-tzdata.py |
Neil Fuller | 35467e1 | 2017-06-12 16:55:44 +0100 | [diff] [blame] | 46 | - Regenerates the external/icu and system/timezone/output_data timezone |
| 47 | data files. |
Neil Fuller | 56166d3 | 2017-06-12 12:57:10 +0100 | [diff] [blame] | 48 | |
Neil Fuller | 3830d70 | 2017-08-18 17:03:59 +0100 | [diff] [blame] | 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 and external/icu runtime files. |
Neil Fuller | 45b6b1b | 2017-10-24 12:14:00 +0100 | [diff] [blame^] | 65 | 5) Build/flash a device image with the changes and run CTS: |
Neil Fuller | 3830d70 | 2017-08-18 17:03:59 +0100 | [diff] [blame] | 66 | cts-tradefed |
| 67 | run cts -m CtsLibcoreTestCases |
| 68 | run cts -m CtsIcuTestCases |
| 69 | (And any others that you think may have been affected) |
Neil Fuller | 45b6b1b | 2017-10-24 12:14:00 +0100 | [diff] [blame^] | 70 | 6) Upload, review, submit the changes from external/icu and system/timezone. |
Neil Fuller | 3830d70 | 2017-08-18 17:03:59 +0100 | [diff] [blame] | 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 and external/icu runtime files. |
| 126 | 4) Regenerate test data files by running: |
| 127 | cd testing/data |
| 128 | ./create-test-data.sh |
| 129 | 5) Build/flash a device image with the changes and run CTS: |
| 130 | cts-tradefed |
| 131 | run cts -m CtsHostTzDataTests |
| 132 | run cts -m CtsLibcoreTestCases |
| 133 | 6) Run non-CTS test cases: |
| 134 | make -j30 FrameworksServicesTests |
| 135 | adb install -r -g \ |
| 136 | "${ANDROID_PRODUCT_OUT}/data/app/FrameworksServicesTests/FrameworksServicesTests.apk" |
| 137 | adb shell am instrument -e package com.android.server.timezone -w \ |
| 138 | com.android.frameworks.servicestests \ |
| 139 | "com.android.frameworks.servicestests/android.support.test.runner.AndroidJUnitRunner" |
| 140 | 7) Upload, review, submit the changes from system/timezone. |
| 141 | |
| 142 | REMINDER: Any prebuilt apks of OEM-specific time zone data apps .apk files |
| 143 | (i.e. ones that that contain distro files) will also need to be regenerated |
| 144 | with a new version code / string and any OEM-specific tests should be run. |
Neil Fuller | 86e72c5 | 2017-06-12 15:36:06 +0100 | [diff] [blame] | 145 | |