NAME
prebuild - custom build process for Time::OlsonTZ::Data
SYNOPSIS
./prebuild status
./prebuild get_olson download latest
./prebuild build_data
./prebuild unbuild_data
./prebuild bare
DESCRIPTION
This program performs build actions for the Time::OlsonTZ::Data module that should run before the usual build process of Build.PL
and Build
. The module distribution tarball for CPAN includes the results of the prebuild process, because the prebuilding process only runs on Unix and requires a C compiler, whereas some CPAN users use other platforms or lack a compiler. The products of the prebuild process are treated as source for by Build.PL
and Build
. Those who are on Unix can use this program to rebuild the data files from their true source, possibly with modifications.
A further complication is that the source for the data files, and for the program that builds most of the data files, is not actually maintained as part of the Time::OlsonTZ::Data module. These source files are maintained and canonically distributed by the maintainers of the Olson timezone database, entirely outside the Perl context. The purpose of this module is to repackage this data for Perl purposes. For this reason, this program supports downloading that part of the source.
The process of building Time::OlsonTZ::Data thus involves the following sequence of states for the module distribution directory:
- bare wrapper source
-
Directory contains only the CPAN wrapper code. There are no Olson source files, no built tzfiles or Perl-format metadata, no
Build
script, and noblib
subdirectory.This is the form of the directory that version-control repositories should have, if they're tracking only the CPAN wrapper project.
- combined true source
-
In addition to the CPAN wrapper code, there is a full set of Olson source files (
tzcode
andtzdata
) in thetzsrc
subdirectory, and atzsrc.meta
file giving identification details for the Olson source files. There are no built tzfiles or Perl-format metadata, noBuild
script, and noblib
subdirectory.This is the main form of the directory that should be used by someone who edits the Olson source as well as wanting the CPAN wrapper. A version-control repository could sensibly track this, for such a user. However, if you maintain a non-standard version of the Olson database outside the context of this wrapper, and want to apply this wrapper to it, it's better to work from the bare wrapper source and use the get_olson local mechanism to incorporate the Olson source.
- data built
-
In addition to the combined true source, there is a full set of tzfiles under
lib/Time/OlsonTZ/Data
, and metadata described in Perl form inlib/Time/OlsonTZ/Data.pm
andlib/Time/OlsonTZ/Data/country_selection.tzp
. There is noBuild
script, and noblib
subdirectory.This is the form of the directory that is published as a tarball on CPAN. The tzfiles and Perl-format metadata are generated from Olson data source files, using a combination of Olson and wrapper code. All the generated files are platform-neutral.
- configured for target
-
In addition to the combined source and built data files, there is a
Build
script incorporating knowledge of a particular host and proposed installation location. There is noblib
subdirectory.This is an intermediate stage in normal CPAN build processing.
- built for target
-
In addition to the combined source, built data files, and
Build
script, there is ablib
subdirectiory which contains all the files that are to be installed, laid out as they will be when installed.This is an intermediate stage in normal CPAN build processing. Installation and automated testing proceed from this state.
ACTIONS
The first command-line argument specifies what action is required from this program. The actions are:
- status
-
Describe the status of the build process. This will primarily be one of the five states listed above. If some build products exist from later in the process, but not enough to reach the next major state, the specific additional items are listed.
- get_olson download version
- get_olson local directory version
-
Acquire Olson database source, placing (most of) it in a
tzsrc
subdirectory and creating atzsrc.meta
file to describe it. This will not replace an existingtzsrc
directory; use the bare action first if you want to throw away existing source.In the download form, the database will be downloaded from an appropriate distribution site. The version argument may be an Olson database version number such as "
2012b
", to download that specific version, or "latest" to get the current version.In the local form, the database will be copied from a local directory where it's already been unwrapped. The version argument must be an Olson database version number such as "
2012b
", specifying which version is in the directory.This action ensures that only public-domain matter goes into the
tzsrc
subdirectory. The downloaded source is checked for the expected markers indicating public-domain status, and an error is signalled if it cannot be confirmed. A small number of known files are filtered out, because they are either definitely not PD (they are BSD licensed) or not properly labelled (though presumably actually are PD). None of the files that are filtered out are required for building tzfiles.The downloading and PD-checking code is quite strict about the expected form of the Olson source distribution. Anything surprising is liable to cause an abort, and it is entirely foreseeable that it will abort in situations that are actually acceptable. An error at this stage, therefore, does not necessarily indicate a fatal problem; it indicates a need for human attention, potentially resulting in editing this code to handle the new situation.
- build_data
-
Build a full set of tzfiles and put metadata into Perl form. This requires Olson source to be available in the
tzsrc
subdirectory. It will replace any existing tzfiles and metadata files. - build_data tzfiles
- build_data metadata
-
Build a subset of the data files. This requires Olson source to be available in the
tzsrc
subdirectory. It will replace any existing tzfiles and metadata files. - unbuild_data
-
Remove any target build, target configuration, and data build products. This cleans up the distribution directory as far as the combined true source state.
- bare
-
Remove any target build, target configuration, and data build products, and Olson database source. This cleans up the distribution directory as far as the bare wrapper source state.
OPTIONS
- -t target-dir
-
Operate on the module distribution in the specified directory. Defaults to the current directory.
AUTHOR
The Olson timezone database was compiled by Arthur David Olson, Paul Eggert, and many others. It is maintained by the denizens of the mailing list <tz@iana.org> (formerly <tz@elsie.nci.nih.gov>).
The Time::OlsonTZ::Data
Perl module wrapper for the database was developed by Andrew Main (Zefram) <zefram@fysh.org>.
COPYRIGHT
The Olson timezone database is is the public domain.
The Time::OlsonTZ::Data
Perl module wrapper for the database is Copyright (C) 2010, 2011, 2012, 2013, 2014, 2017, 2018, 2019, 2020 Andrew Main (Zefram) <zefram@fysh.org>.
LICENSE
No license is required to do anything with public domain materials.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.