# eggert/tz architecture

> Architecture diagram of the GitHub repository eggert/tz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eggert/tz
- Repository: https://github.com/eggert/tz

## Overview

##### Project type and purpose
- This is the IANA “tz” distribution: a C-based library + command-line tools + data set that represent historical and current time-zone rules worldwide.
- It is not a typical client/server or web app, but a data-driven tooling package: you compile source data into binary zoneinfo files, build a small run-time library, and install a handful of CLI utilities.

##### File structure
- Top-level files
- Makefile, configure‐style scripts: orchestrate build and install
- C source files (date.c, localtime.c, zic.c, zdump.c, etc.): implement library and tools
- Data directories (africa/, europe/, northamerica/, …): plain-text zone definition files
- Scripts (checklinks.awk, ziguard.awk, tzselect.ksh, workman.sh): validation, selection, migration helpers
- Documentation (tz-how-to.html, theory.html, manpages .1/.3/.5/.8): usage and design background
- Static tables (iso3166.tab, zone.tab, zone1970.tab, leap-seconds.list): reference data
- Patterns
- Layered architecture: data layer → compiler tool (zic) → binary zoneinfo layer → run-time library → CLI utilities
- Build/install: Makefile drives compilation of C sources and installation of data + binaries

##### README for additional insights
- Purpose: “Provide a compendium of data about the history of civil time…”
- Usage: run make install, then utilities like zdump to inspect zoneinfo
- Contribution: data fixes and enhancements welcome

##### Attention to detail
- Where manpages (date.1, zic.8, tzfile.5) and HTML docs sit in the install tree

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Source Data Store"
        A_regions["Region Directories: africa/, antarctica/, asia/, australasia/, europe/, northamerica/, southamerica/, backzone/, factory/, calendars/, etcetera/"]:::data
        A_tables["Static Tables: iso3166.tab, leap-seconds.list, zone.tab, zone1970.tab, zonenow.tab, backward"]:::data
    end

    subgraph "Build System"
        B_makefile["Makefile"]:::tool
        B_scripts["Validation & Helper Scripts"]:::tool
    end

    subgraph "Compiler Tool (zic)"
        C_zic_src["zic.c"]:::tool
        C_zic_man["zic.8"]:::tool
    end

    subgraph "Binary Zoneinfo Output"
        D_zoneinfo["Compiled zoneinfo binaries"]:::data
    end

    subgraph "Runtime Library"
        E_sources["C Sources: localtime.c, asctime.c, difftime.c, date.c, strftime.c"]:::library
        E_headers["Headers: tzfile.h, private.h"]:::library
        E_man["Man Pages: newctime.3, newstrftime.3, newtzset.3, time2posix.3, tzfile.5"]:::library
    end

    subgraph "CLI Utilities"
        F_date_src["date.c"]:::library
        F_date_man["date.1"]:::library
        F_zdump_src["zdump.c"]:::library
        F_zdump_man["zdump.8"]:::library
        F_tzselect_src["tzselect.ksh"]:::library
        F_tzselect_man["tzselect.8"]:::library
    end

    subgraph "Test Scripts"
        G_tests["checklinks.awk, checknow.awk, checktab.awk, leapseconds.awk, ziguard.awk, zishrink.awk, workman.sh"]:::script
    end

    subgraph "Install Target"
        H_zoneinfo["/usr/share/zoneinfo"]:::install
        H_binaries["CLI Binaries & Library"]:::install
        H_docs["HTML & Man Pages"]:::install
    end

    A_regions -->|"text definitions"| C_zic_src
    A_tables -->|"text definitions"| C_zic_src
    B_makefile -->|"compiles C sources"| E_sources
    B_makefile -->|"invokes zic"| C_zic_src
    C_zic_src -->|"zone text → zoneinfo binaries"| D_zoneinfo
    D_zoneinfo -->|"reads at runtime"| E_sources
    E_sources -->|"provides functions"| F_date_src
    E_sources -->|"provides functions"| F_zdump_src
    E_sources -->|"provides functions"| F_tzselect_src
    G_tests -->|"validate text data"| A_regions
    D_zoneinfo -->|"install"| H_zoneinfo
    C_zic_src -->|"install"| H_binaries
    E_sources -->|"install"| H_binaries
    F_date_src -->|"install"| H_binaries
    F_zdump_src -->|"install"| H_binaries
    F_tzselect_src -->|"install"| H_binaries
    E_man -->|"install"| H_docs
    F_date_man -->|"install"| H_docs
    F_zdump_man -->|"install"| H_docs
    F_tzselect_man -->|"install"| H_docs
    C_zic_man -->|"install"| H_docs

    click A_regions "https://github.com/eggert/tz/tree/main/africa/"
    click A_regions "https://github.com/eggert/tz/tree/main/europe/"
    click A_regions "https://github.com/eggert/tz/tree/main/northamerica/"
    click A_regions "https://github.com/eggert/tz/tree/main/etcetera/"
    click A_tables "https://github.com/eggert/tz/blob/main/iso3166.tab"
    click A_tables "https://github.com/eggert/tz/blob/main/leap-seconds.list"
    click A_tables "https://github.com/eggert/tz/blob/main/zone.tab"
    click A_tables "https://github.com/eggert/tz/blob/main/zone1970.tab"
    click A_tables "https://github.com/eggert/tz/blob/main/zonenow.tab"
    click A_tables "https://github.com/eggert/tz/tree/main/backward"
    click B_makefile "https://github.com/eggert/tz/tree/main/Makefile"
    click B_scripts "https://github.com/eggert/tz/blob/main/checklinks.awk"
    click B_scripts "https://github.com/eggert/tz/blob/main/checknow.awk"
    click B_scripts "https://github.com/eggert/tz/blob/main/checktab.awk"
    click B_scripts "https://github.com/eggert/tz/blob/main/leapseconds.awk"
    click B_scripts "https://github.com/eggert/tz/blob/main/ziguard.awk"
    click B_scripts "https://github.com/eggert/tz/blob/main/zishrink.awk"
    click B_scripts "https://github.com/eggert/tz/blob/main/workman.sh"
    click C_zic_src "https://github.com/eggert/tz/blob/main/zic.c"
    click C_zic_man "https://github.com/eggert/tz/blob/main/zic.8"
    click E_sources "https://github.com/eggert/tz/blob/main/localtime.c"
    click E_sources "https://github.com/eggert/tz/blob/main/asctime.c"
    click E_sources "https://github.com/eggert/tz/blob/main/difftime.c"
    click E_sources "https://github.com/eggert/tz/blob/main/date.c"
    click E_sources "https://github.com/eggert/tz/blob/main/strftime.c"
    click E_headers "https://github.com/eggert/tz/blob/main/tzfile.h"
    click E_headers "https://github.com/eggert/tz/blob/main/private.h"
    click E_man "https://github.com/eggert/tz/blob/main/newctime.3"
    click E_man "https://github.com/eggert/tz/blob/main/newstrftime.3"
    click E_man "https://github.com/eggert/tz/blob/main/newtzset.3"
    click E_man "https://github.com/eggert/tz/blob/main/time2posix.3"
    click E_man "https://github.com/eggert/tz/blob/main/tzfile.5"
    click F_date_src "https://github.com/eggert/tz/blob/main/date.c"
    click F_date_man "https://github.com/eggert/tz/blob/main/date.1"
    click F_zdump_src "https://github.com/eggert/tz/blob/main/zdump.c"
    click F_zdump_man "https://github.com/eggert/tz/blob/main/zdump.8"
    click F_tzselect_src "https://github.com/eggert/tz/blob/main/tzselect.ksh"
    click F_tzselect_man "https://github.com/eggert/tz/blob/main/tzselect.8"

    classDef data fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef tool fill:#ffe0b2,stroke:#e65100,color:#e65100
    classDef library fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20
    classDef script fill:#eeeeee,stroke:#616161,color:#424242
    classDef install fill:#f3e5f5,stroke:#4a148c,color:#4a148c
```
