Update out-of-date docs/fix download-iana-files.py
This commit updates the README.android to bring it up to date.
It also changes the flags on download-iana-files.py to make downloads
opt-in rather than opt-out, reflecting the common case is to only want
to download the data files.
Bug: 131159913
Test: Ran download-iana-files.py
Merged-In: Id1d8b66f8635a96a88591b19e64afb906bc9bd40
Change-Id: Id1d8b66f8635a96a88591b19e64afb906bc9bd40
diff --git a/README.android b/README.android
index 0a00001..490de9b 100644
--- a/README.android
+++ b/README.android
@@ -4,6 +4,13 @@
Directory structure
===================
+apex
+ - Code related to the Android time zone update APEX file that can be used
+ to update time zone rules on Android devices.
+
+debug_tools
+ - Contains tools useful for debugging time zone issues on Android devices.
+
distro
- Code related to "distros", the collection of files that can be used to
update time zone rules on Android devices. See distro/README for details.
@@ -13,10 +20,13 @@
Some files come from external sources and some are mastered in Android.
See also download-iana-data.py.
+input_tools
+ - Contains tools that generate Android time zone files.
+
output_data
- Contains some derived files from the time zone rules update process and
- used in the Android system image and distros. Some files are also held by
- ICU - see also update-tzdata.py
+ used in the Android system image, distros and APEX files. Some files are
+ also held by ICU - see also update-tzdata.py
testing
- Contains tools and scripts related to testing time zone update code. See
@@ -28,19 +38,16 @@
/data (as could happen if the device has just received an OTA upgrade).
It is also responsible for committing staged install/uninstalls.
-zone_compactor
- - Used to create Android's native tzdata file format from the files
- produced by the zic tool. See also update-tzdata.py.
Data file update tools
======================
-download-iana-data.py
+download-iana-files.py
- A helper script run before update-tzdata.py.
- It downloads the latest tzdata update from IANA and puts it in
- the system/timezone/input_data/iana directory for use by the
- update-tzdata.py script.
+ It downloads the latest tzdata and/or tzcode files from IANA and puts them
+ in the input_data/iana and input_tools/iana directories for use by the
+ update-tzdata.py script. See download-iana-files.py --help for more.
update-tzdata.py
- Regenerates the external/icu and system/timezone/output_data timezone
@@ -53,10 +60,8 @@
When IANA release new time zone rules, the update process is:
-1) Run download-iana-data.py to update the system/timezone/input_data/iana
- file.
-2) Make manual modifications to system/timezone/input_data/android files as
- needed.
+1) Run "download-iana-files.py --data" to update the input_data/iana file.
+2) Make manual modifications to input_data/android files as needed.
3) There are sometimes code and metadata changes associated with tzdata updates
that should be applied to Android's copy of ICU.
e.g. see http://bugs.icu-project.org/trac/search?q=2015d
@@ -72,33 +77,66 @@
REMINDER: Any prebuilt apks of OEM-specific time zone data apps .apk files
(i.e. ones that that contain distro files) will also need to be regenerated
with a new version code / string and any OEM-specific tests should be run.
+APEX files containing time zone data files will also need to be regenerated.
+
+IANA tools changes
+==================
+
+Occasionally it might be necessary / desirable to update the version of zic
+used to generate Android's tzdata file. For example, if IANA introduce new
+syntax to the text rules files (e.g. asia, north_america, etc.) or adds useful
+command-line arguments to zic. This should be needed very rarely.
+
+It is recommended that this is done independently of a data update to help
+isolate unexpected changes to behavior.
+
+Note that updating the version of zic used to create the tzdata file is
+independent of the copy of zic used by ICU. Also, bionic contains
+a copy of tzcode (e.g. localtime.c) which is based on yet another IANA
+release so compatibility and consistency is a consideration.
+
+The steps for updating IANA tools are similar to updating IANA data except
+you can use "download-iana-files.py --tools" instead of "--data" and testing
+should be more rigorous.
+
+REMINDER: As above, having updated the tooling then all binaries that contain
+tzdata should also be regenerated. e.g. APK and APEX files.
-Distro Versioning
-=================
+Time Zone Data Set Versioning
+=============================
-The Android time zone "distro" is a zip archive containing the files needed
-to update a device's time zone rules by overlaying files into locations in /
-data. See distro/ for details.
+Android needs various files to be updated to take a time zone data update.
+These files come from various sources and we needed a concise shorthand
+to indicate compatibility between a set of files and an Android release. This is
+known as the "Time Zone Data Set Version". Currently we expect to increment this
+version with every dessert release, though this may change in future.
-The distro format (i.e. the files contained within the zip file) can change
-between major releases as Android evolves or makes updates to components that
-use the time zone data.
+The idea of a single version to describe time zone data updates was first
+introduced in O-MR1 with the concept of a "distro" which could be delivered by
+an APK. The Android time zone "distro" is a zip archive containing the files
+needed to update a device's time zone rules by overlaying files into locations
+in /data. See distro/ for details.
-Distros have a major and minor format version number:
+The "distro" concept will be removed in a future release of Android as it is
+being replaced by an APEX file containing the same data. As the APEX contains
+the same files we continue to use a shorthand version code. See apex/ for
+details.
-- Major format version numbers are mutually incompatible. e.g. v2 is not
- compatible with a v1 or a v3 device.
-- Minor format version numbers are backwards compatible. e.g. a v2.2 distro
- will work on a v2.1 device but not a v2.3 device.
+Time Zone Data Set Versions have a major and minor version number:
+
+- Major version numbers are mutually incompatible. e.g. v2 is not compatible
+ with a v1 or a v3 device.
+- Minor version numbers are backwards compatible. e.g. a v2.2 distro will work
+ on a v2.1 device but not a v2.3 device.
- The minor version is reset to 1 when the major version is incremented.
The most obvious/common change that can occur between Android releases is an
-ICU upgrade, which currently requires a major format version increment: Android
-uses the ICU4C's native format for both ICU4C and ICU4J time zone code which is
+ICU upgrade, which currently requires a major version increment: Android uses
+the ICU4C's native file format for both ICU4C and ICU4J time zone code which is
tied to the ICU major version. The main .dat file used by ICU is held in
external/icu and will naturally be updated when ICU is updated. Less obviously,
-the distro code and files must be updated as well.
+the time zone data set version code and files must be updated as well.
Other examples of changes that affect format versioning:
@@ -114,27 +152,22 @@
change to tzdata / tzlookup.xml).
-Changing the distro format version
-----------------------------------
+Changing the Time Zone Data Set Version
+---------------------------------------
1) Modify libcore/luni/src/main/java/libcore/timezone/TzDataSetVersion.java
- CURRENT_FORMAT_MAJOR_VERSION, CURRENT_FORMAT_MINOR_VERSION
2) Run update-tzdata.py to regenerate the system/timezone/output_data,
- system/timezone/testing/data, external/icu runtime files and testing equivalents.
-3) Build/flash a device image with the changes and run CTS:
- cts-tradefed
- run cts -m CtsHostTzDataTests
- run cts -m CtsLibcoreTestCases
+ system/timezone/testing/data, external/icu runtime files and testing equivalents.
+3) Build/flash a device image with the changes and run CTS tests:
+ atest CtsHostTzDataTests
+ atest CtsLibcoreTestCases
4) Run non-CTS test cases:
- make -j30 FrameworksServicesTests
- adb install -r -g \
- "${ANDROID_PRODUCT_OUT}/data/app/FrameworksServicesTests/FrameworksServicesTests.apk"
- adb shell am instrument -e package com.android.server.timezone -w \
- com.android.frameworks.servicestests \
- "com.android.frameworks.servicestests/android.support.test.runner.AndroidJUnitRunner"
-5) Upload, review, submit the changes from system/timezone, libcore and external/icu.
+ atest FrameworksServicesTests:com.android.server.timezone
+5) Upload, review, submit the changes from system/timezone and libcore.
+ Note: you may have changes in external/icu/ but usually there is no need to update
+ external/icu as only a timestamp in zoneinfo64.txt should have changed.
-REMINDER: Any prebuilt apks of OEM-specific time zone data apps .apk files
-(i.e. ones that that contain distro files) will also need to be regenerated
-with a new version code / string and any OEM-specific tests should be run.
+REMINDER: Any prebuilt apks / apex files (i.e. ones that that contain time zone files)
+will also need to be regenerated after this change.
diff --git a/download-iana-files.py b/download-iana-files.py
index bcf551f..a09a356 100755
--- a/download-iana-files.py
+++ b/download-iana-files.py
@@ -119,10 +119,10 @@
# See http://www.iana.org/time-zones/ for more about the source of this data.
def main():
parser = argparse.ArgumentParser(description=('Update IANA files from upstream'))
- parser.add_argument('--notools', help='Skip tools files', action='store_true')
- parser.add_argument('--nodata', help='Skip data files', action='store_true')
+ parser.add_argument('--tools', help='Download tools files', action='store_true')
+ parser.add_argument('--data', help='Download data files', action='store_true')
args = parser.parse_args()
- if args.notools and args.nodata:
+ if not args.tools and not args.data:
parser.error("Nothing to do")
sys.exit(1)
@@ -133,14 +133,14 @@
ftp.cwd('tz/releases')
output_files = []
- if not args.notools:
+ if args.tools:
# The tools and data files are kept separate to make the updates independent.
# This means we duplicate the tzdata20xx file (once in the tools dir, once
# in the data dir) but the contents of the data tar appear to be needed for
# the zic build.
new_files = DownloadAndReplaceLocalFiles(['tzdata20', 'tzcode20'], ftp, iana_tools_dir)
output_files += new_files
- if not args.nodata:
+ if args.data:
new_files = DownloadAndReplaceLocalFiles(['tzdata20'], ftp, iana_data_dir)
output_files += new_files
