Crate tzcompile 

tzcompile — a memory-safe Rust implementation of (a declared subset of) the IANA timezone compiler zic.

What this crate is

It compiles IANA tzdata source text (Zone / Rule / Link lines) into binary TZif files as specified by RFC 9636 / tzfile(5). It is library-first: the CLI in the zic-rs binary is a thin shell over the API exposed here.

Compiler pipeline

source text  ->  lexer  ->  parser  ->  Database  ->  compile  ->  TzifData  ->  TZif bytes
                (source::)          (model records)  (compile::)   (tzif::)

The companion compare module is an oracle: it can run the reference C zic and diff its output against ours, semantically (the contract) and byte-for-byte (a stretch goal for the simplest zones). It is the only place that ever executes an external zic; the compile path never shells out.

Scope (current declared subset)

zic-rs grows strictly by fixture class, so the supported surface is exactly what the checked-in fixtures (and their reference-zic/zdump oracle results) prove. At present that is: fixed-offset zones and Links; finite named-Rule DST sets (lastSun/Sun>=N/Sun<=N, AT suffixes w/s/u, FORMAT %s/slash/%z); recurring (TO=maximum) rule sets summarised by an exact POSIX-TZ footer; and multi-era UNTIL continuations (including the final-recurring-era anchor). Everything outside the proven subset — e.g. inline-saving eras with a %s/slash FORMAT or a negative save, 24:00/negative compiled times, leap seconds — is rejected with an explicit diagnostic rather than approximated (the fail-closed doctrine). (Accepted breadth: inline-save eras with a literal/%z FORMAT; both mixed finite+recurring final-era shapes — effectively recurring-only as in Europe/London, and genuinely mixed-in-era as in America/New_York; and the obsolete FROM=minimum, coerced to 1900 like reference zic.) The authoritative, always-current lists live in docs/supported-syntax.md and docs/unsupported-syntax.md; the milestone history is in docs/roadmap.md.

Re-exports

pub use diagnostics::Diagnostic;

pub use diagnostics::DiagnosticCode;

pub use diagnostics::DiagnosticLayer;

pub use diagnostics::DiagnosticSpanPrecision;

pub use diagnostics::DiagnosticVerbosity;

pub use diagnostics::Severity;

pub use error::Error;

pub use error::Result;

Modules

aux_tables

T16.4 — auxiliary-table validator (zone.tab / zone1970.tab / zonenow.tab / iso3166.tab) plus a bounded install-ecology status.

cli

Command-line interface — a thin shell over the tzcompile library.

compare

The compatibility oracle: compile a zone both ways and compare.

compile

The semantic compiler: a parsed Database zone → in-memory TzifData.

diagnostics

Located, coded diagnostics about tzdata source.

doctor

doctor (T16.6b) — a read-only environment probe for operators/packagers.

error

Error and diagnostic plumbing.

fs

Filesystem layer: the only part of the crate that writes output, and it does so safely.

hash

A small, dependency-free SHA-256 (FIPS 180-4) used to fingerprint compiled TZif files in the alias/canonical manifest (see manifest).

limits

Resource limits (T17.1b) — generous hard caps on input-driven dimensions.

manifest

The alias/canonical manifest (alias-map.json) — a producer-side artifact that records, for a compile run, which identifiers are canonical zones and which are links (aliases), with content hashes and an explicit account of where link materialisation duplicates bytes.

model

The parsed, still-textual semantic model of a tzdata source: the records the parser produces and the compiler consumes.

release_diff

release-diff (T16.6a) — diff two IANA tzdb releases per identifier.

report

support-report — an honest frontier map of which identifiers in a tzdata source file zic-rs can compile, and why the rest cannot.

semantic_witness

T15.3 — semantic witnesses: typed, zdump-backed behaviour evidence for the public conformance engine. A semantic witness answers “at this instant, do zic-rs and the reference agree on the local (utoff, is_dst, abbreviation)?” — read through the project’s footer-aware behaviour oracle, reference zdump. It is deliberately not structural validation (RFC 9636 byte-format correctness is T15.4) and not a diagnostic: a witness proves selected behaviour under an oracle, nothing more.

size_report

size-report (T21.2) — a read-only footprint report over a produced output tree (--out <dir>), for the container / embedded image builder (see docs/container-embedded-builder.md).

source

Source front-end: turning tzdata text into a typed Database.

structural

structural-report — a measured structural-parity inventory of zic-rs TZif output against reference zic (campaign T8).

tzif

TZif output: the in-memory TzifData model and the writer that serialises it to the on-disk format described by RFC 9636 / tzfile(5).

vendor_oracle

T16.5 — external vendor-oracle receipt admission.

Structs

CompileConfig

Fully-resolved configuration for a compile run.

CompileReport

Structured, deterministic summary of a compile run.

EmitOptions

Full emission options: an EmitStyle plus the optional -R redundant-tail bound (T10.3).

LinkReport

Per-link outcome record for the compile report.

RangeSpec

Reference zic’s -r '[@lo][/@hi]' range-truncation bounds (T10.4), as raw parsed Unix-second instants — None on a side means that side is unbounded (zic’s min_time/max_time default).

ZoneReport

Per-zone outcome record for the compile report.

Enums

EmitStyle

Explicit-transition emission style (campaign T8-slim). This is an emission policy — it never changes behaviour (every mode is zdump-equivalent: the POSIX footer governs the tail identically); it only changes how many explicit transitions are written before the footer takes over.

LinkMode

How Link records are materialised in the output tree.

UnsupportedPolicy

Policy for source constructs this version does not implement.

ZoneSelection

Selection of which zones (and their links) to compile.

Constants

DEFAULT_TRANSITION_LIMIT

Sensible, safe defaults (no default output dir — that is always explicit).

Functions

collect_source_files

Expand input paths into a deterministic, flat list of source files.

compile_zone

Compile one zone (by name) from a parsed database into in-memory TZif data.

compile_zone_styled

Compile one zone with an explicit emission policy. Accepts a bare EmitStyle or a full EmitOptions (style + -R redundant-tail bound). compile_zone is exactly this with EmitStyle::Default; the default output is byte-for-byte unchanged from before T8-slim.

compile_zone_to_bytes

Convenience: compile a zone straight to TZif bytes (default emission style).

compile_zone_to_bytes_styled

Convenience: compile a zone straight to TZif bytes with an explicit emission policy (EmitStyle or EmitOptions).

is_contained

True when path is strictly contained within root after normalising ./...

load_database

Read every tzdata source file referenced by paths and parse it into a Database.

resolve_link_target

Resolve a link target name to the underlying canonical zone name, following link chains.