NameDateSize

..10-Aug-20184 KiB

Android.mk10-Aug-201881

distro/10-Aug-20184 KiB

download-iana-data.py10-Aug-20183.8 KiB

input_data/10-Aug-20184 KiB

input_tools/10-Aug-20184 KiB

output_data/10-Aug-20184 KiB

README.android10-Aug-20185.7 KiB

testing/10-Aug-20184 KiB

tzdatacheck/10-Aug-20184 KiB

tzdatautil.py10-Aug-20181.1 KiB

tzlookup_generator/10-Aug-20184 KiB

update-tzdata.py10-Aug-20189 KiB

zone_compactor/10-Aug-20184 KiB

README.android

1This directory contains code, tools and data related to time zone rules data
2and updates.
3
4Directory structure
5===================
6
7distro
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
11input_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
16output_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
21testing
22  - Contains tools and scripts related to testing time zone update code. See
23    testing/data/README for details.
24
25tzdatacheck
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
31zone_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
36Data file update tools
37======================
38
39download-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
45update-tzdata.py
46  - Regenerates the external/icu and system/timezone/output_data timezone
47    data files.
48
49See update instructions below for how these tools are used.
50
51IANA rules data changes
52=======================
53
54When IANA release new time zone rules, the update process is:
55
561) Run download-iana-data.py to update the system/timezone/input_data/iana
57  file.
582) Make manual modifications to system/timezone/input_data/android files as
59  needed.
603) 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
634) Run update-tzdata.py to regenerate the system/timezone/output_data,
64  system/timezone/testing/data, external/icu runtime files and testing equivalents.
655) 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)
706) Upload, review, submit the changes from external/icu and system/timezone.
71
72REMINDER: 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
74with a new version code / string and any OEM-specific tests should be run.
75
76
77Distro Versioning
78=================
79
80The Android time zone "distro" is a zip archive containing the files needed
81to update a device's time zone rules by overlaying files into locations in /
82data. See distro/ for details.
83
84The distro format (i.e. the files contained within the zip file) can change
85between major releases as Android evolves or makes updates to components that
86use the time zone data.
87
88Distros 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
96The most obvious/common change that can occur between Android releases is an
97ICU upgrade, which currently requires a major format version increment: Android
98uses the ICU4C's native format for both ICU4C and ICU4J time zone code which is
99tied to the ICU major version. The main .dat file used by ICU is held in
100external/icu and will naturally be updated when ICU is updated. Less obviously,
101the distro code and files must be updated as well.
102
103Other examples of changes that affect format versioning:
104
105Major 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
110Minor 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
117Changing the distro format version
118----------------------------------
119
1201) Modify distro/core/src/main/com/android/timezone/distro/DistroVersion.java:
121  - CURRENT_FORMAT_MAJOR_VERSION, CURRENT_FORMAT_MINOR_VERSION
1222) Modify: tzdatacheck/tzdatacheck.cpp
123  - SUPPORTED_DISTRO_MAJOR_VERSION, SUPPORTED_DISTRO_MINOR_VERSION
1243) Run update-tzdata.py to regenerate the system/timezone/output_data,
125  system/timezone/testing/data, external/icu runtime files and testing equivalents.
1264) Build/flash a device image with the changes and run CTS:
127    cts-tradefed
128    run cts -m CtsHostTzDataTests
129    run cts -m CtsLibcoreTestCases
1305) 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"
1376) Upload, review, submit the changes from system/timezone.
138
139REMINDER: 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
141with a new version code / string and any OEM-specific tests should be run.
142
143