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.

Reply via email to