On 2026-11-01 16:38, Brian Inglis via tz wrote:
Been confused by those and other messages and errors generated by other check .ck targets and scripts: are the purposes, expectations, results, and impacts, including what we should do about them, documented in the Makefile, scripts, or elsewhere?
No. The idea has been that "make check" should just succeed; and if it fails and if you lack the time or expertise to see why, send [email protected] email. (Which is what Sam did.) In the old days I would have said that if somebody were to maintain high-quality documentation along the lines you suggested, that would be a win (especially if the "somebody" wasn't me...). Nowadays, though, I wonder whether it's so often easier to ask a bot, that the benefit of having such documentation is no longer worth the maintenance cost. I just now asked Gemini 3.8 Flash to produce documentation along the lines you suggested, and it generated the following Markdown-format text. Is that good enough? If so, perhaps we can leave this sort of thing to bots in the future. (And if not, perhaps we could come up with a better prompt and/or a better model, and still leave this sort of thing to the bots.) ---- start of Gemini output ---- The documentation, expectations, and handling instructions for the validation targets (`check_*` and `.ck` targets) in the **TZDB (Time Zone Database)** repository are detailed below. --- ## 1. Overview of Check Targets (`check`, `check_*`, `.ck`) In the TZDB distribution, automated testing is organized around Make rules that validate both source code (C code) and data (zone definitions, leap seconds, link configurations). * **`make check`**: The master testing target. Running `make check` executes all individual validation steps and checks. * **`.ck` Files**: Targets ending in `.ck` (e.g., `check_web.ck`, `check_zics.ck`, `check_sorted.ck`) are **stamp files**. When a specific check script or target passes, Make creates or touches the corresponding `.ck` marker file to prevent redundant re-running unless dependencies (source files, scripts, or data) change. --- ## 2. Key Check Targets & Their Purposes ### A. Data Consistency & Syntax Checks * **`check_tables` / `check_web.ck**` * **Purpose:** Validates internal data tables (such as `zone.tab`, `zone1970.tab`, and `iso3166.tab`) against geographical guidelines, ISO standards, and format specifications. * **Expectation:** Ensures ISO country codes match standardized lists, coordinate formats are valid ($DDMMSS$), and linked zone entries correctly align across files. * **`check_zics` / `check_zic.ck**` * **Purpose:** Runs the compiled `zic` (zone information compiler) against all data files (`africa`, `asia`, `australasia`, `europe`, `northamerica`, `southamerica`, `backward`, etc.). * **Expectation:** Ensures all input files compile cleanly without warnings, syntax errors, or invalid rule boundaries. * **`check_sorted` / `check_sorted.ck**` * **Purpose:** Verifies that tabular mapping files and link entries are sorted in the standard alphabetical or regional order expected by consumers. ### B. Compatibility & Portability Checks * **`check_time_t_alternatives`** * **Purpose:** Tests compilation across various integer types and sizes for `time_t` (e.g., 32-bit signed/unsigned, 64-bit signed/unsigned, extreme values). * **Expectation:** Catches potential integer overflow, signedness mismatches, and year-2038 issues across supported C compilers. * **`check_workman`** * **Purpose:** Verifies system manual pages (`zic.8`, `zdump.8`, `tzfile.5`) for proper formatting, invalid roff syntax, and missing options. --- ## 3. Interpreting Output & Error Messages | Signal / Result | Meaning | Impact | Required Action | | --- | --- | --- | --- | | **`ALL CHECKS PASSED`** / Clean Exit (`0`) | All build artifacts, data rules, and scripts validated successfully. | High confidence in release stability. | None. Target `.ck` files are updated. | | **`zic: ... error line N`** | Syntax or semantic error in one of the tz database files (e.g., overlapping rules, invalid DST offsets). | Build aborts; invalid TZif outputs generated. | Edit the specified data file at line $N$ to correct rule dates or offsets. | | **`tab file unsorted / non-standard`** | Table entry is out of alphabetical order or missing ISO metadata. | Data consistency test fails. | Re-sort table entries or update ISO 3166-1 country definitions. | | **`time_t overflow / compiler warning`** | Type mismatch or boundary failure during `check_time_t_alternatives`. | Non-portable behavior on legacy or 32-bit architectures. | Adjust type definitions or C flags in the `Makefile`. | --- ## 4. Documentation Locations If you need to dive deeper into specific checks, consult these primary files within the tarball: 1. **`Makefile`**: Contains target definitions, dependencies, and shell commands associated with each `check_*` and `.ck` target. 2. **`README`**: High-level build instructions, compiler requirements, and test suite execution basics. 3. **`NEWS`**: Release notes listing updates, additions, or deprecations of check targets (e.g., historical removals of deprecated check rules). 4. **`check_*.py` / `check_*.sh**`: Diagnostic scripts invoked by Makefile targets that contain specific validation logic and comments. ---- end of Gemini output ---- PS. After this, Gemini asked, "Would you like detailed troubleshooting steps for a specific Makefile target or error message?" which suggests that there's a lot more info there, as needed.
