icuSources/tools/tzcode/readme.txt

   1 **********************************************************************
   2 * Copyright (c) 2003-2004, International Business Machines
   3 * Corporation and others.  All Rights Reserved.
   4 **********************************************************************
   5 * Author: Alan Liu
   6 * Created: August 18 2003
   7 * Since: ICU 2.8
   8 **********************************************************************
   9
  10 ----------------------------------------------------------------------
  11 OVERVIEW
  12
  13 This file describes the tools in icu/source/tools/tzcode
  14
  15 The purpose of these tools is to process the zoneinfo or "Olson" time
  16 zone database into a form usable by ICU4C (release 2.8 and later).
  17 Unlike earlier releases, ICU4C 2.8 supports historical time zone
  18 behavior, as well as the full set of Olson compatibility IDs.
  19
  20 References:
  21
  22 ICU4C:  http://oss.software.ibm.com/icu/
  23 Olson:  ftp://elsie.nci.nih.gov/pub/
  24
  25 ----------------------------------------------------------------------
  26 ICU4C vs. ICU4J
  27
  28 For ICU releases >= 2.8, both ICU4C and ICU4J implement full
  29 historical time zones, based on Olson data.  The implementations in C
  30 and Java are somewhat different.  The C implementation is a
  31 self-contained implementation, whereas ICU4J uses the underlying JDK
  32 1.3 or 1.4 time zone implementation.
  33
  34 Older versions of ICU (C and Java <= 2.6) implement a "present day
  35 snapshot".  This only reflects current time zone behavior, without
  36 historical variation.  Furthermore, it lacks the full set of Olson
  37 compatibility IDs.
  38
  39 ----------------------------------------------------------------------
  40 BACKGROUND
  41
  42 The zoneinfo or "Olson" time zone package is used by various systems
  43 to describe the behavior of time zones.  The package consists of
  44 several parts.  E.g.:
  45
  46   Index of ftp://elsie.nci.nih.gov/pub/
  47
  48   classictzcode.tar.gz    65 KB        12/10/1994    12:00:00 AM
  49   classictzdata.tar.gz    67 KB        12/10/1994    12:00:00 AM
  50   e5+57.tar.gz            2909 KB      3/22/1993     12:00:00 AM
  51   iso8601.ps.gz           16 KB        7/27/1996     12:00:00 AM
  52   leastsq.xls             49 KB        4/24/1997     12:00:00 AM
  53   ltroff.tar.gz           36 KB        7/16/1993     12:00:00 AM
  54   pi.shar.gz              4 KB         3/9/1994      12:00:00 AM
  55   tzarchive.gz            3412 KB      8/18/2003     4:00:00 AM
  56   tzcode2003a.tar.gz      98 KB        3/24/2003     2:32:00 PM
  57   tzdata2003a.tar.gz      132 KB       3/24/2003     2:32:00 PM
  58
  59 ICU only uses the tzcodeYYYYV.tar.gz and tzdataYYYYV.tar.gz files,
  60 where YYYY is the year and V is the version letter ('a'...'z').
  61
  62 ----------------------------------------------------------------------
  63 HOWTO
  64
  65 1. Obtain the current versions of tzcodeYYYYV.tar.gz (aka `tzcode')
  66    and tzdataYYYYV.tar.gz (aka `tzdata') from the FTP site given
  67    above.  Either manually download or use wget:
  68
  69    $ cd {path_to}/icu/source/tools/tzcode
  70    $ wget "ftp://elsie.nci.nih.gov/pub/tz*.tar.gz"
  71
  72 2. Unpack tzcode and tzdata directly into the directory tzcode:
  73
  74    $ tar xzvf tzcode*.tar.gz
  75    $ tar xzvf tzdata*.tar.gz
  76
  77    *** Make sure you only have ONE FILE named tzdata*.tar.gz in the
  78        directory.
  79    *** Do NOT delete the tzdata*.tar.gz file.
  80
  81    The Makefile looks in the current directory to determine the
  82    version of Olson data it is building by looking for tzdata*.tar.gz.
  83
  84 3. Apply the ICU patch to zic.c:
  85
  86    $ patch < patch-icu-tzcode
  87
  88    If patch complains at this point, there is a mismatch that must be
  89    manually addressed.  See the CVS log of `patch-icu-tzcode' for
  90    version details.
  91
  92 4. Build:
  93
  94    $ make icu_data
  95
  96 5. Copy the data files to the correct location in the ICU4C/ICU4J
  97    source trees:
  98
  99    $ cp zoneinfo.txt ../../../data/misc/
 100    $ cp ZoneMetaData.java {path_to}/icu4j/src/com/ibm/icu/impl
 101
 102 6. Rebuild ICU:
 103
 104    $ cd ../../../
 105    $ {*make}
 106
 107 7. Don't forget to check in the new zoneinfo.txt (from its location at
 108    {path_to}/icu/source/data/misc/zoneinfo.txt) into CVS.
 109
 110 ----------------------------------------------------------------------
 111 HOWTO regenerate patch-icu-tzcode
 112
 113 If you need to edit any of the tzcode* files, you will need to
 114 regenerate the patch file as follows.
 115
 116 1. Follow the above instructions to extract and patch the tzcode*
 117    files in {path_to}/icu/source/tools/tzcode.  Modify any of the
 118    tzcode files.
 119
 120 2. Extract a clean set of the tzcode* files into a new directory,
 121    ../tzcode.orig/:
 122
 123    $ mkdir ../tzcode.orig
 124    $ cd ../tzcode.orig
 125    $ tar xzf ../tzcode/tzcode*.tar.gz
 126    $ cd ../tzcode
 127
 128 3. Compute diffs, ignoring files that are in only one directory:
 129
 130    $ diff -ur ../tzcode.orig . | grep -vE -e "^Only in " > patch-icu-tzcode
 131
 132 4. Test the patch-icu-tzcode file by regenerating and diffing the
 133    files again in another directory.  The expected output from the
 134    final diff command is *nothing*.
 135
 136    $ mkdir ../tzcode.new
 137    $ cd ../tzcode.new
 138    $ tar xzf ../tzcode/tzcode*.tar.gz
 139    $ patch < ../tzcode/patch-icu-tzcode
 140    $ cd ../tzcode
 141    $ diff -ur ../tzcode.new . | grep -vE -e "^Only in "
 142
 143 5. Check in the new patch-icu-tzcode file.
 144
 145 ----------------------------------------------------------------------
 146 eof