NAME

build_tz_database.pl - Build the DateTime::Lite::TimeZone SQLite database

SYNOPSIS

# Fetch latest tzdata from IANA, compile, build database:
perl scripts/build_tz_database.pl [--verbose]

# Specific version:
perl scripts/build_tz_database.pl --tz-version 2026a

# Already-downloaded tarball:
perl scripts/build_tz_database.pl --tarball /path/to/tzdata2026a.tar.gz

# Use system zoneinfo (no download):
perl scripts/build_tz_database.pl --zoneinfo /usr/share/zoneinfo

DESCRIPTION

Builds the SQLite timezone database bundled with DateTime::Lite::TimeZone.

Primary mode downloads the latest (or specified) tzdata release directly from IANA (https://ftp.iana.org/tz/releases/), verifies the GPG signature, compiles the Olson source files with zic(1), and parses the resulting TZif binary files (RFC 8536). Downloaded tarballs are cached under ~/.cache/dtl-tzdata/ to avoid redundant downloads.

Fallback mode (--zoneinfo) reads TZif files from a local compiled zoneinfo directory instead of downloading. Useful when IANA is unreachable or for quick local rebuilds from the installed system timezone data.

Run this script whenever a new tzdata release is available, then commit the updated lib/DateTime/Lite/tz.sqlite3.

OPTIONS

--tz-version version

Target a specific tzdata version such as 2026a. Defaults to the latest version found on the IANA releases page.

--tarball file

Use an already-downloaded tzdata*.tar.gz file, skipping the download.

--zoneinfo directory

Use a local compiled zoneinfo directory instead of downloading from IANA.

--db file

Output database path. Defaults to lib/DateTime/Lite/tz.sqlite3 relative to the distribution root.

--cache-dir directory

Where to store cached tarballs. Defaults to ~/.cache/dtl-tzdata/.

--skip-verify

Skip GPG signature verification. Not recommended for production.

--verbose

Print one line per timezone as it is processed.

REQUIREMENTS

Always required: zic(1) (from the tzdata or tz-utils system package), DBI, DBD::SQLite >= 1.27.

For primary mode: curl(1) or wget(1).

Recommended: gpg(1) for signature verification.

Optional (non-fatal if absent): rdfind(1) for deduplication, symlinks(1) for relative symlink conversion.

EPOCH CONVERSION

TZif transition times are stored as seconds since the Unix epoch (1970-01-01T00:00:00 UTC). DateTime uses seconds since the Rata Die epoch (0001-01-01T00:00:00). The constant UNIX_TO_RD = 62_135_683_200 converts between them.

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

Copyright(c) 2026 DEGUEST Pte. Ltd.

All rights reserved

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.