punkshell/goals/G-098-suite-tk-tcllib-critcl.md

G-098 suite_tcl90 full punkshell dependency set: Tk+tklib, tcllib with critcl accelerators, and testsuite gating

Status: active Scope: src/buildsuites/suite_tcl90/ (recipe extensions, driver steps, testsuite gate), src/buildsuites/_build/ (tk/tklib/tcllib/critcl sources and outputs), bin/tools/ (pinned zig as consumed), src/tests/ (punkshell suites exercised against the suite-built runtime) Goal: suite_tcl90 builds/installs the remaining runtime pieces punkshell testing depends on - Tk (fossil core.tcl-lang.org/tk) loadable by the suite's Tcl 9.0 windows runtime together with a matching tklib (fossil core.tcl-lang.org/tklib; pure-tcl, installed via its own installer.tcl where that does more than a straight copy), and tcllib (fossil core.tcl-lang.org/tcllib) installed via its documented mechanism (installer.tcl / sak.tcl checked for installation behaviour that is not just a straight copy) WITH its critcl-built C accelerators (tcllibc; critcl from github.com/andreas-kupries/critcl driving zig cc as the compiler, bootstrapped by the suite-built tclsh - no MS toolchain) - and the suite's test surface becomes a gate: suite.tcl test parses the all.tcl totals rather than trusting the exit code and fails on failures absent from a recorded expected-failure baseline. Acceptance: from the pinned zig and fetched sources the suite produces a Tk the suite tclsh loads (package require Tk with a create/destroy-window verification recorded in this file) and a matching tklib whose packages resolve from the install (a representative tklib package require recorded); a tcllib install performed via its own installer machinery (installer.tcl/sak.tcl behaviour checked and recorded - module selection, pkgIndex/tm generation, critcl module handling) whose accelerators load (package require tcllibc) with a punkcheck-relevant hashing comparison showing the accelerated path engaged versus pure-tcl; critcl is version-pinned and driven with zig cc; suite.tcl test gates on parsed totals against a recorded expected-failure baseline and the current 72 core-test failures are dispositioned (fixed or baselined with reasons); punkshell's runtests can run against the suite-built runtime with Tk-dependent suites no longer skipped for lack of Tk.

Context

Follow-on from G-096 (tracked zig buildsuite; zig 0.16.0 pin adopted 2026-07-20), per user direction 2026-07-20:

• Tk must be built to run ALL punkshell tests (Tk-dependent suites currently skip).
• A matching tklib may be required for Tk to function properly - believed pure-tcl, so a fossil pull plus possibly its installer.tcl "depending on whether it does anything special" (user wording).
• tcllib is mostly pure-tcl but its critcl-built accelerators make a huge performance difference - without tcllibc, punkcheck hash checking is very slow. tcllib has an installer.tcl and sak.tcl which should be checked for installation behaviour that is not just a straight copy.
• critcl (github.com/andreas-kupries/critcl) may be required for the accelerators; it needs a tclsh (the suite-built shell) and a C compiler (zig cc - keeps the no-MS-toolchain policy; the mechanism is zig-version-agnostic).
• Testsuite state at goal creation: full Tcl core suite on the suite-built shell runs 66350 tests, 72 FAILED (triage pending; native-runtime baseline on this machine is exec-14.3 only), and all.tcl's exit code does not reflect failures - hence the totals-parsing gate requirement.

Notes

• Related goals: G-096 (the buildsuite this extends; its remaining items - piperepl rebase/matrix and punk-getzig per-version fetch - stay with G-096), G-005 (zig build infrastructure direction), G-060 (qemu cross-platform matrix - eventual multi-platform consumer), G-021/G-020 (agent visual verification - a working Tk underpins those).
• The 72-failure triage is tracked HERE (gate clause), not in G-096, to avoid double tracking.

Progress

2026-07-20 increment 1: activated; hermetic clone store; Tk builds and smokes

• Activated by the user. Clone-store design (two user course-checks): fossil clone dbs are CACHES, not build output - they now live in the punkshell-owned machine-level store ~/.punkshell/fossils (user preference: ~/... on all platforms for cross-platform doc simplicity, a deliberate exception to windows convention), independent of the personal ~/.fossils AND outside deletable _build-class dirs (git clean -fdx safe). Missing clones seed READ-ONLY by file copy from -seedfossils (default ~/.fossils; the seed is never written - the copy is pulled current), else network-clone. Override: -repofolder / PUNK_FOSSIL_STORE, the latter registered in punk::config's known env vars ('help env' surfacing; punk::config pending-0.2.0 entry). -refresh now pulls store clones before updating checkouts; clean wipes the stage only. Verified: full seed->open->build->smoke PASS from an empty store (6 clones seeded, ~1.2GB), then store migrated to ~/.punkshell/fossils and re-verified (checkouts re-opened from the new store, PASS, zero re-seeds).
• Sources wired: tk (core-9-0-branch -> stage/tk9; clone was stale at 2023/8.7a6 and pulled current - TK 9.0.2), tklib (trunk, current), tcllib (trunk, current).
• Tk recipe (build_tk/build_tk.zig, 0.16 API): tcl9tk90.dll from stock sources - object inventory from tk/win/makefile.vc TKOBJS+TTK_OBJS (generic/unix-shared/win/ ttk splits corrected against the tree; xlib emulation sources x{colors,draw,gc, image,util}.c were absent from the name-pattern extraction and restored; tkStubLib/ttkStubLib excluded as stub-archive objects), tkMain compiled ansi+UNICODE with the forced -U ansi guard (G-096 finding), CFG_* pkgconfig defines generated at build time, rc from win/rc/tk.rc with explicit include_paths (wish.exe.manifest and tcl headers), system libs incl oleaut32 (tkWinSend OLE). tk script library installs to out/lib/tk9.0; the driver generates tkUuid.h + wish.exe.manifest (TK_WIN_VERSION 9.0.2.902 by the tree's own formula) and writes the pkgIndex.tcl (tk + Tk ifneeded -> ../../bin/tcl9tk90.dll, makefile.vc install convention).
• SMOKE PASS on the suite shell: package require Tk -> 9.0.2; winfo screen 3840x2160 depth 32; label pack + update + destroy clean (real window station exercised, not just a load).

2026-07-20 increment 2: tklib installed via its own installer; tooltip smoke

• Installer behaviour checked (per the user's caveat) before use: NOT a straight copy
  • module exclusion list (unless +excluded), app-script generation, optional nroff/html doc install, and generation of the aggregating top-level pkgIndex.tcl (gen_main_index sources each module's index - required for package resolution since module indexes sit two levels below auto_path). critcl DSL procs are stubbed to no-ops (pure-tcl confirmed). Batch surface: -no-gui -no-wait with -pkgs/-apps/-html/-nroff/-examples toggles and *-path overrides; default paths derive from the RUNNING tclsh.
• Driver step: run installer.tcl with the SUITE-BUILT shell, batch, packages only (-no-gui -no-wait -pkgs -no-apps -no-html -no-nroff -no-examples) - defaults land it at out/lib/tklib0.9 with the generated main pkgIndex. Idempotent (skipped when a tklib* install exists).
• SMOKE PASS: in the suite shell, package require Tk + package require tooltip -> tooltip 2.0.4 (a Tk-dependent tklib package resolving through the aggregate index).

Remaining for acceptance:

• tcllib install via installer.tcl/sak.tcl (behaviour check) + critcl-built tcllibc (critcl git clone/pin driving zig cc) + hashing comparison evidence.
• suite.tcl test gate: parse all.tcl totals vs a recorded expected-failure baseline; disposition the 72 current failures.
• punkshell runtests against the suite-built runtime with Tk suites unskipped.
• Fetch conventions follow suite_tcl90, with the hermetic clone store adopted at this goal's activation (user decision 2026-07-20): clones live in the suite-owned _build/suite_tcl90/fossils store (seeded READ-ONLY from ~/.fossils when present, else network-cloned; -repofolder/PUNK_FOSSIL_STORE override; clean keeps the store, clean -all removes it), checkouts under _build with FOSSIL_HOME isolation and --nested. critcl is git, not fossil - clone/pin convention to be settled in the work (git clone under _build with a pinned tag/commit is the expected shape).