Installation Instructuctions for the Chronos Date/Time Library

Chronos is currently available only for VisualWorks Smalltalk, Squeak Smalltalk and Dolphin Smalltalk.

For VisualWorks, the version currently distributed should be compatible with all versions of VisualWorks from 2.0 forward (and perhaps earlier, but it hasn't been tried.) However, the “file-out” format is NOT compatible with versions of VisualWorks prior to 5i.3. For instructions and advice on installing Chronos in versions of VisualWorks prior to 5i.3, or for information on porting Chronos to non-VisualWorks environments other than those already available, see the Porting.html document that should accompany this document.

The VisualWorks version of Chronos is distributed as a .zip file, which contains .st source code file-ins and also parcels (which are alternatives to each other.) Chronos for VisualWorks is also available from the Cincom Public PostGreSQL StORE Repository.

The Squeak and Dolphin versions lack some of the functionality provided by the VisualWorks version. The Squeak version, for example, cannot determine the user's local time zone from the host operating system's time zone setting.  Neither the Squeak nor the Dolphin versions of Chronos are able to determine locale information from the operating system.

The version of Chronos distributed for Squeak should be compatible with all Squeak versions since Squeak 3.6 (and perhaps even earlier.)  Chronos for Squeak is distributed as both a .zip file and a .sar file (both of which contain .st source code file-ins.) The .zip file also contains .mcz files (which are alternatives to the file-ins.) Chronos for Squeak is also available from either SqueakMap or SqueakSource.

The version of Chronos for Dolphin is known to be compatible with the X6 version of Dolphin Smalltalk.  Whether it is compatible with any other verision of Dolphin is not known (any information on that topic would be appreciated.) It is distributed as a .zip file containing a .pac ("package") file.

All the .zip files for all versions of Chronos contain the Chronos Time Zone Repository.

1. Install the Chronos Time Zone Repository

If you've obtained the Chronos distribution by installing the Chronos Bundle from the Cincom Public StORE Repository, or by installing it from either SqueakMap or SqueakSource, then you should also download the Chronos Time Zone Repository from the Chronos web site (navigate to the Downloads>>Time Zones frame, then select the Chronos Time Zone Repository link--or just select the immediately-preceding link in this parenthetical comment.) 

The Chronos Time Zone Repository is included in the Chronos archive file ("Chronos.zip"--available from the Chronos web site.)  The pathname of the Chronos Time Zone Repository in the Chronos.zip archive file is Chronos/time-zones.  If the Chronos Time Zone Repository is downloaded separately (as "time-zones.zip,") then its pathname in the archive file is "time-zones". 

Extract the entire contents of whichever archive file you downloaded (either Chronos.zip or time-zones.zip) to the location of your choice. Chronos can be configured so that it will find the Chronos Time Zone Repository at any location accessible using the Smalltalk file operation primitives. For the VisualWorks and Squeak versions of Chronos, the persistent time zone rulesets in the Chronos Time Zone Repository are also individually accessible via HTTP at a well-known URL  (e.g., "http://date-time-zone.com/time-zones/rulesets/Europe/Berlin.tzn".)

Depending on whether or not you are using the Squeak version of Chronos, where you decide to locate the Chronos Time Zone Repository (and in which directory you plan to keep the Smalltalk image in which you install Chronos,) you may or may not need to set the value of the CHRONOS_PATH environment variable to the absolute path of the directory where the Chronos Time Zone Repository is (or will be) located. The Squeak version of Chronos cannot access OS environment variables, so for Squeak especially, putting the Chronos Time Zone Repository in the same folder that contains the Smalltalk image that you will be using to install Chronos will be the easiest approach initially.

If the Chronos Time Zone Repository cannot be located, Chronos will issue error/warning messages to the Transcript, and although Chronos will still be functional, it will not be able to resolve any time zones identified by Olson timezone keys (e.g., 'America/Los_Angeles'.) Full functionality will be restored once Chronos is able to locate a valid Chronos Time Zone Repository.

Should you  desire to keep the Chronos Time Zone Repository somewhere other than the image's current working directory, or if Chronos complains that it can't find the Chronos Time Zone Repository, then you need to read the next section.  Otherwise, you can skip it and continue with the section titled Setting the System Time Zone. 

How to Locate the Chronos Time Zone Repository Somewhere Other than the Image's Current Directory

For either VisualWorks or Dolphin (but not for Squeak,) the best approach is to set the system envorinment variable CHRONOS_PATH to the pathname of the directory that contains the "time-zones" folder. 

Example: If the Chronos Time Zone Repository (which resides in the "time-zones" folder) is located at "C:\DevTools\Smalltalk\Chronos\time-zones", then the value of the CHRONOS_PATH environment variable should be set to "C:\DevTools\Smalltalk\Chronos". Using the CHRONOS_PATH environment variable is a very good approach in many situations, especially when one uses multiple Chronos-enabled images that reside in different locations, and/or when multiple users should be sharing the same Chronos Time Zone Repository over a network.

Another option would be to programmatically inform your Chronos-enabled image where the Chronos Time Zone Repository will be located. The location where a Chronos-enabled image expects to find the Chronos Time Zone Repository can be programmatically changed using the ChronosSystemFacade API.  Evaluate <ChronosSystemFacade resourceRepositoryContext resourcePathPrefix: prefixString>, where prefixString is the pathname (as a String, using host OS filename syntax) of the directory that contains the time-zones folder (e.g., if the time-zones folder's absolute pathname is 'C:\DevTools\Smalltalk\Chronos\time-zones', then resourcePathPrefix should be 'C:\DevTools\Smalltalk\Chronos'.) Of course, Chronos must first be installed in the image, and then the image must be saved after the pathname has been programmatically set.

During installation and/or whenever a Chronos-enabled image is restarted from a snapshot, Chronos will search for the folder containing the Chronos Time Zone Repository at the following locations (in the order specified):

1. At the "last good location" where that particular image most recently found the folder containing the Chronos Time Zone Repository. When installing Chronos for the first time in an image, the “last good location” is assumed by fiat to be the current working directory (e.g., "Filename defaultDirectory" in VisualWorks, or "FileDirectory default" for Squeak.)
2. For VisualWorks and Dolphin only: At the pathname specified by the value of the environment variable CHRONOS_PATH (if defined, and if the specified path exists.) 
3. In the current working directory according to the host Smalltalk environment (which can resolve to unexpected values in some situations.) This is the easiest approach when one is only using a single Chronos-enabled image, and is the recommended approach for initial installation and evaluation.
4. For VisualWorks only: In the same folder where the current VisualWorks image file is located (the path to the image may not necessarily be the same as the current directory--for example, on Windows, when an image is started by drag and drop.)
5. For VisualWorks only: In the $VISUALWORKS folder--if it's defined and the specified path exists (for versions of VW without an explicit $VISUALWORKS folder, this will instead be the folder where the image expects to find its *.sou file.)

The ChronosSystemFacade singleton is responsible for finding the Chronos Time Zone Repository. It searches for the Chronos Time Zone Repository whenever Chronos is initially installed in an image, whenever a Chronos-enabled image is restarted from a snapshot, or whenever the message #install is sent to the ChronosSystemFacade singleton (e.g, "ChronosSystemFacade current install."). 

The ChronosSystemFacade singleton is also responsible for setting the Chronos system time zone, based on whichever Chronos time zone best matches the time zone used by the host system to define local time, according to the currently-specified matching policy.  See the class comment of ChronosSystemFacade for more information. 

Notes:

• The expected filename (component of a pathname) of the directory containing the Chronos Time Zone Repository is specified by the method ChronosSystemFacade>>timeZoneResourcesDirectoryName (hard-coded to be 'time-zones')
• The Chronos Time Zone Repository folder contains the following subfolders:
  • foreign-keys (contains mappings between Olson time zone keys and the time zone names used by other time zone databases, such as Microsoft's)
  • leap-seconds (contains leap second schedules for time scales, such as UTC)
  • localization-policies (contains the preferred mappings between zone offsets, zone abbreviations, and Olson time zone keys, on a per-country basis)
  • Olson-zoneinfo-sources (countains the text files--using the Unix line-end convention--that comprise the Olson Time Zone Database as published by Arthur David Olson; these are the source or input files for the Chronos Time Zone Compiler, and can also be used as the source/input files for various other time zone compilers, including zic, the one used by Unix/MacOS X)
  • rulesets (contains the time zone rulesets in the standard Chronos format, as compiled by the Chronos Time Zone Compiler, representing the time zone rules for all the time zones defined in the Olson Time Zone Database)

2. Setting the System Timezone

Divining which  time zone ruleset represents the local time of the host system (or the user--which may be different!) is a non-trivial problem. How Chronos attempts to do this, and how effective it is, varies considerably between different host operating systems and different Smalltalk flavors. (For a more in-depth discussion of the issues involved, see the essay Discovering the Local Time Zone--Why It's a Hard Problem.)

Although the Chronos system time zone can be set programmatically at any time after Chronos has been installed (see the class comment of ChronosTimezone for the specifics,) it is generally more convenient to configure your operating environment and/or installation image so that Chronos will be able to automatically set its system time zone to match the local time zone used by your operating system (although there's not much that can be done when using Squeak.) If this is not done, then during initial installation Chronos will simply use whatever information it may be able to obtain to guess at the correct local time zone.

If the Chronos Time Zone Repository is not accessible, Chronos will make no attempt to discover the local time zone.

In the case of VisualWorks, Chronos will first attempt to get a valid POSIX or Olson time zone from the TZ environment variable.  If that fails, and it's running on Windows, it will then attempt to access the time zone ruleset from the Windows Registry (which will fail if the OSTimeZone package is not--or cannot be--installed.) If the host OS is some flavor of UNIX, and the OSTimeZone package has been installed, Chronos will attempt to discover the current offset from Universal Time, and then use both that and the country code to make a reasonably good guess about the correct ruleset for the local time zone. As a last resort, Chronos will use the information provided by the VisualWorks default TimeZone to guess at the most likely corresponding Olson timezone (for now, this will only be helpful in cases where you’ve already set the VW default TimeZone as desired in the installation image; however, Cincom currently plans to provide the capability for some future VisualWorks version to initialize the default TimeZone instance based on the ruleset of the time zone that the host system uses to define local time.)

In the case of Dolphin, Chronos will obtain what it needs from the Windows Registry. However, Chronos will instead use the TZ environment variable (and ignore the Windows Registry,) provided the TZ environment variable is set to a valid POSIX or Olson time zone.

In the case of Squeak, Chronos will create a Chronos time zone that exactly matches Squeak's native time zone. For Squeak 3.7 and later, that means a time zone whose fixed offset is the same as that of "DateAndTime localTimeZone"; for Squeak 3.6 and earlier, that means that Chronos defaults to Universal Time.

The recommended configuration procedure varies by Smalltalk flavor, and for VisualWorks also by operating system:

Squeak: Install the Chronos Time Zone Repository in the same directory where you keep the Chronos-enabled image you will be using.  Once Chronos has been installed in your image, programattically set the Chronos system time zone (e.g., "(Timezone at: 'Asia/Tokyo') beSystem", "(Timezone at: 'Europe/Berlin') beSystem", "(Timezone at: 'Europe/London') beSystem", "(Timezone at: 'Americal/New_York') beSystem", "(Timezone at: 'Americal/Los_Angeles') beSystem"--see below for more time zone keys.) Save your image.

Dolphin: Install the Chronos Time Zone Repository in the same directory where you keep the Chronos-enabled image you will be using.  That should be all that's necessary.

VisualWorks[Windows]: Install Cincom’s DLLCC and OSTimeZone parcels into the image into which you wish to install Chronos. Chronos will attempt to do this for you during installation, but it will not succeed unless those parcels have been installed at the expected locations in the $VISUALWORKS directory. If both parcels are installed (either by you, or automatically during Chronos installation,) then in most cases Chronos will be able to correctly determine the system timezone (provided you have it set correctly in Windows to begin with.)

If defined and set to a valid value, Chronos will instead use the value of the TZ environment variable when running on Windows, although Windows itself makes no use of it. See the UNIX section below for information on the valid values to which the TZ environment variable may be set. For instructions on setting environment variables in Windows, see the Windows documentation—or do a Web search.

VisualWorks[UNIX/Linux/MacOSX]: For a variety of reasons (most of which are covered in exhaustive detail in the essay Discovering the Local Time Zone--Why It's a Hard Problem,) you should set the TZ environment variable to the key of whatever Olson time zone in which you’d like to operate (or alternatively, you may set it to any valid POSIX time zone rule literal, such as ‘CST6CDT’.)

For the United States, the correct time zone key would very probably  be one of “America/Adak”, ":Pacific/Honolulu", ":America/Anchorage", ":America/Los_Angeles', ‘:America/Phoenix’, “:America/Denver’, “America/Boise”, “:America/Chicago”, “:America/Indiana/Indianapolis”, “:America/Detroit” or “:America/New_York”. There are several other choices in the States of Alaska and Indiana, and in the various US territories and possessions.

For Europe, common options would be “:Europe/London”, “:Europe/Berlin”, “:Europe/Madrid”, “:Europe/Paris”, "Europe/Amsterdam", “:Europe/Athens” and “:Europe/Moscow”.

For Asia, common options would be “:Asia/Jerusalem”, “:Asia/Tokyo”, “:Asia/Hong_Kong” and “:Asia/Calcutta”.

The full list of Olson timezone keys (over 400 of them—and that’s not a typo) is available from a text file in the Chronos Time Zone Repository (located at /time-zones/rulesets/index.) The full list can also be accessed programmatically by evaluating ‘ChronosTimezone allRegisteredKeys.’

The recommended procedure for setting the TZ environment variable on UNIX is to add a command such as one of the following to your “.profile” configuration file (although this won’t work on all flavors of UNIX, it should work on most of them—see the documentation of your particular UNIX variant if you encounter problems):

	TZ=’:America/Indiana/Vevay’; export TZ
	TZ=’:Australia/Sydney’; export TZ
	TZ=’HOVT-7HOVST-8,M3.5.0,M10.1.0/3:00’; export TZ

The first two examples use Olson time zone keys; the last example uses a POSIX time zone rule literal. See the UNIX documentation of the tzset command and/or Specifying the Time Zone with TZ for more information on setting the time zone on Unix systems.

Note the “:” character preceding the Olson time zone key. Chronos will actually recognize the specified time zone even if the “:” is missing—but UNIX and applications running on it may not. Perversely, AIX forbids the colon--and some versions don't support Olson time zones in any case.

3. Install Chronos In An Image

The Chronos Date/Time Library

Generally, the Chronos Date/Time Library should install equally well into either a "virgin" image, or into an image that has the code of other applications and/or libraries already installed. For Dolphin, all code resides in a Chronos-specific package ("Chronos".) For VisualWorks, all code resides in Chronos-specific packages contained (directly or indirectly) by the bundle "Chronos"--and all classes are defined in the namespace "Chronos."

Chronos does require that certain core image behavior remains unchanged. For the most part, Chronos depends only on the presence and correct operation of (a subset of) the classes and methods specified and required by the ANSI Smalltalk Standard. Almost all the exceptions would be base library classes and methods used by ChronosEnvironment and its subclasses, ChronosSystemFacade and its subclasses and ChronosSystemClock and its subclasses. The subclasses of ChronosEnvironment, ChronosSystemFacade and ChronosSystemClock are intentionally and necessarily specific to the particular Smalltalk environment (e.g., VisualWorks, Dolphin, Squeak, ...)

If you're using a version of of your Smalltalk development environment modified in such a way that the code in any of the Chronos classes won't work as intended, then you'll have to either revert your image to "virgin" behavior, or else modify the offending Chronos methods (in effect, you'll have to "port" Chronos to your modified development environment.) Your choice.

The only modifications Chronos makes to the "virgin" library of the supported Smalltalk flavors are the addition of a handful of utility methods to certain classes.  Which native classes, if any, will have methods added by Chronos depends on the particular Smalltalk flavor and/or version. For VisualWorks, Chronos adds utility methods to Core.TimeZone, Number, Integer, CharacterArray, Filename, BlockClosure, Date, Time and Timestamp. Chronos itself either never invokes or uses any of such utility methods added to base system classes, or else checks for their presence and uses alternative logic if they are absent. With the single exception of the methods added to VisualWorks' Core.TimeZone, such added methods are solely for the convenience and usage of the clients of the Chronos Date/Time library, and all of them can be removed without affecting the operation of Chronos in any way.

Dolphin

VisualWorks

Note: The Bundle Squeak-Chronos, which is a port of Squeak's Chronology Date/Time library from Squeak to VisualWorks, and is distributed as part of the Seaside Web Server (in order to provide Squeak-VW portability for Seaside) adds some of the same methods to the same classes as does the Chronos-VW-Extensions package--although with different implementations, of course. If you need both the Chronos and the Squeak.Chronology Date/Time libraries in the same image at the same time, you'll have to decide whose version of the conflicted utility extension methods you wish to use (if any!) One approach to handle this issue would be to port any code that depends on one of the Date/Time libraries to use the other.  Since both libraries have the same core API (defined by the ANSI Smalltalk Standard,) and since both also include "VW compatiblity methods," that may in fact be easier than it sounds in many cases (so the news isn't all bad.)

For VisualWorks, the utility methods added by Chronos are all defined as class extensions in the package Chronos-VW-Extensions (so you can easily find them and check for any collisions with code added by your own applications and/or libraries.) Examples of the added methods: Number>>hours (so that '-8 hours’ will evaluate to a Duration of -8 hours length,) BlockClosure>>durationToRun, CharacterArray>>asTimezone and Timestamp>>asDateAndTime (which answers the conversion of a Timestamp into a Chronos Timepoint.) The methods the Chronos-VW-Extensions package adds to Core.TimeZone may also be removed, although doing so may cause time zone rule translation into instances of Core.TimeZone to be incorrect in cases involving either fractional-hour offsets or fractional-hour DST transition times. None of the methods added by Chronos to Core.TimeZone conflict with any methods in the Squeak-chronos Bundle.

Installation Instructions: Chronos can be installed as a Parcel, as a file-in or by using StORE:

Parcel (Chronos.pcl): Extract all files from Chronos.zip and load the parcel Chronos.pcl into a VW image of your choice which does not have a previous version of Chronos currently installed. If a previous version of Chronos is installed in the target image, remove it first. [Note: Loading the Chronos.pcl parcel into pre-VW7x images has not been tried--it may or may not work]

File-In (Chronos.st): Extract all files from Chronos.zip and file in Chronos.st to a VW image of your choice which does not have a previous version of Chronos currently installed. If a previous version of Chronos is installed in the target image, remove it first. [For versions of VW prior to 5i.3, see the companion document Porting.html.]

StORE Repository: Load the “Chronos” bundle. The latest version is always available from the Cincom Public PostGreSQL StORE Repository.

Squeak

After the Installation

The Chronos Time Zone Compiler (and other utilities)

VisualWorks

Installation Instructions: The Chronos Time Zone Compiler can be installed as a Parcel, as a file-in or by using StORE:

Parcel (Chronos-Utilities.pcl): Extract all files from Chronos.zip and load the parcel Chronos-Utilities.pcl into the VW image of your choice which does not have a previous version of The Chronos Time Zone Compiler currently installed. If a previous version of The Chronos Time Zone Compiler is installed in the target image, remove it first. [Note: Loading the Chronos-Utilities.pcl parcel into pre-VW7x images has not been tried--it may or may not work]

File-In (Chronos-Utilities.st): Extract all files from Chronos.zip (if you haven’t already) and file in Chronos-Utilities.st to the VW image of your choice which does not have a previous version of the Chronos-Utilities bundle currently installed [However, for versions of VW prior to 5i.3, see the companion document Porting.html.]

StORE Repository: Load the “Chronos-Utilities” bundle. The latest version is always available from the Cincom Public PostGreSQL StORE Repository.

Squeak

Dolphin

Additional information about the Chronos Time Zone Compiler and the Olson Time Zone Database:

• To generate the Chronos Time Zone Repository de novo, or to ensure you are using the latest version of the Olson Time Zone Database, fetch the Olson source files from ftp://elsie.nci.nih.gov/pub/, extract/install them into <path-prefix>/time-zones/Olson-zoneinfo-sources, and then run the Chronos Time Zone Compiler by evaluating "OlsonTZDBRulesetCompiler processTimeZoneRules", thereby generating a new version of the Chronos Time Zone Repository. This procedure can also be used to generate a “de novo” version of the Chronos Time Zone Repository, which may be necessary when you do not already have a version of the Chronos Time Zone Repository, and are unable to access the latest version from the Chronos web site [direct link: http://www.chronos-st.org/downloads/time-zones.zip].
• The Olson time zone source files are packaged as a zipped tar file in the ftp://elsie.nci.nih.gov/pub/ folder. The name of the file has the form tzdataYYYYv.tar.gz, where YYYY is the 4 digits of the year and v is a lower-case letter of the English alphabet that indicates the version index within the year (so that the first version in the year 2006 would be 2006a, the second version would be 2006b, and so on.) The last version of the file for 2005 has the name tzdata2005r.tar.gz, and contains the version of the database commonly referred to as 2005r.
• The source files from which the Chronos time zone rulesets, localization policies and UTC leap second schedule are generated reside in the Chronos Time Zone Repository at the location <path-prefix>/time-zones/Olson-zoneinfo-sources. Arthur David Olson publishes updated versions of the source data about once every month (some countries decide de novo every year what their daylight saving policy will be, and of course there’s always some set of countries every year that decide to change their rules.)
• The value of <path-prefix> currently used by a Chronos image can be discovered by evaluating “ChronosSystemFacade current resourcePathPrefix.” If the value is the empty string or nil, then <path-prefix> is the current working directory (the absolute path for which can be discovered by evaluating “ResourcePath defaultDirectory.”)

Getting Started

Information on getting started is available from the Overview document, or from the Chronos web site.

Chronos Updates

When updated versions of either the Chronos Date/Time Library or the Chronos Time Zone Repository become available, that information will be published on the Chronos Blog.  Soon, there will be an  Atom feed by means of which XML-encoded publication announcements can be obtained, which will enable automation of the time zone repository update process .