Browse Source
G-153 [proposed]: fork-as-upstream metakit port under the pinned zig - standalone core + Mk4tcl dll/static shapes, win32-x86_64 + win32-ix86 from day one, KitCreator patch audit vs the 2.4.9.8 baseline, dll smoke under suite-built tclsh86t (the sdx-circularity probe enabler), mk4 x64<->ix86 interchange check, and ready-to-land sources.config/zon record text for suite consumption. Non-contract Notes: G-101 records metakit_punk as the mk4 porting vehicle superseding the TEMP_REFERENCE metakit trees; G-130 gains the measured UCRT linkage + OS-floor statement (Win10 zero-prereq, Win7/8.x need KB2999226, XP/2000 structurally out), the Windows 2000 placement with the luck-specimen Win2k-clean import measurement, the SSE2 (pentium4) cpu-baseline rider, and the lane-mechanics inventory (standardTargetOptions present; critcl/baselines/punkres-PE32/punkbin-folder/twapi-x86 gaps); G-131 points at G-153 for its metakit arm. goals_lint clean. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.commaster
5 changed files with 219 additions and 0 deletions
@ -0,0 +1,136 @@ |
|||||||
|
# G-153 metakit_punk zig port: fork-as-upstream Mk4tcl for the 8.6 kit container |
||||||
|
|
||||||
|
Status: proposed |
||||||
|
Scope: external fork repo c:/repo/jn/metakit_punk (gitea jn/metakit - the port itself lands there); src/buildsuites/suite_tcl86/sources.config and src/buildsuites/suite_tcl86/build.zig.zon (ready-to-land metakit records drafted in the detail file; landing them is G-101-era consumption); TEMP_REFERENCE/{metakit_jnorthrup,metakit_pooryorick,KitCreator} (read-only patch/boot-chain reference - machine-local); goals/G-101-tcl86-kit-container-strategy.md (consumer decision record) |
||||||
|
Goal: the punkshell-maintained metakit fork (c:/repo/jn/metakit_punk - gitea jn/metakit - pooryorick 2.4.9.8 porting baseline with the dead upstreams preserved as in-repo reference snapshots) builds standalone under the pinned zig toolchain as a Tcl-agnostic C++ core library plus the Mk4tcl binding in both loadable-dll and static-embed shapes, for win32-x86_64 and win32-ix86 alike, and a suite-built 8.6 shell loads and exercises the dll - so the G-101 mk4 container candidate rests on a first-party, commit-pinned, provenance-carrying source referenced by the buildsuites the punkzip way (gitea commit pin in sources.config plus zon tarball record) rather than on dead third-party upstreams or a wholesale vendor copy. |
||||||
|
Acceptance: in c:/repo/jn/metakit_punk under the pinned zig 0.16.0, 'zig build' and 'zig build test' pass for both x86_64-windows and x86-windows with the 32-bit tests executed natively on the x64 host (WoW64); the KitCreator mk4tcl patch set (eight patches vs 2.4.9.7) is audited against the 2.4.9.8 baseline with a per-patch disposition recorded (ported as fork commits citing origin / already present in baseline / rejected with reason); the Mk4tcl binding builds as a stubs-linked dll against the same tcl core-8-6-branch pin suite_tcl86 carries and suite-built tclsh86t loads it - package require Mk4tcl plus an mk::file open/set/select/close round trip - with the transcript recorded in this file; an mk4 datafile written by the x86_64 build reads back identically under the ix86 build and vice versa; a static-embed shape (archive registerable via Tcl_StaticPackage) links into a copy of the kit-class shell target or its blocker is recorded here; the fork commit is pinned with ready-to-land sources.config and build.zig.zon record text captured in this file; and metakit_punk's root LICENSE lands with the first ported sources (MIT/X11 retained). |
||||||
|
|
||||||
|
## Context |
||||||
|
|
||||||
|
Metakit's upstreams are dead or dormant: the official jcw lineage froze at 2.4.9.7 |
||||||
|
(jnorthrup GitHub mirror, last commit 2011) and the pooryorick community fork at |
||||||
|
2.4.9.8 (2018). The buildsuites' referencing pattern for LIVE upstreams (fossil |
||||||
|
branch records in sources.config + per-checkin tarball pins in build.zig.zon, |
||||||
|
suite-owned recipes over raw trees) therefore does not fit; the applicable |
||||||
|
precedent is punkzip (G-126, achieved 2026-07-27 - see |
||||||
|
goals/archive/G-126-punkzip-accelerator.md): a punkshell-maintained fork that IS |
||||||
|
the upstream, self-hosted on gitea, commit-pinned by the suites, with its own zig |
||||||
|
build system. |
||||||
|
|
||||||
|
The fork repo was seeded 2026-07-30 (user-built skeleton): DOX/AGENTS.md |
||||||
|
governance, read-only reference snapshots of both upstreams under src/reference/ |
||||||
|
with a provenance table, and a port-relevant fork-difference analysis (33 files |
||||||
|
differ 2.4.9.7 -> 2.4.9.8; classified noise / warning-hygiene / type |
||||||
|
modernization / Tcl-binding behavior). Its own contracts already fix key |
||||||
|
decisions: port from the pooryorick snapshot only; Python binding out of scope; |
||||||
|
upstream build systems (autoconf/MSVC/CMake) not carried; snapshots byte-frozen. |
||||||
|
Direction confirmed by the user 2026-08-02: the port is driven from punkshell |
||||||
|
sessions with access to this goals tree, so this file is the plan of record. |
||||||
|
|
||||||
|
Boundary (deliberate, keeps the fork reusable): metakit_punk owns the storage |
||||||
|
engine (upstream src/ + include/) and the mk::* Tcl binding (tcl/mk4tcl.cpp/.h + |
||||||
|
tcl/tests). Kit boot machinery - kitInit.c preinit, boot.tcl, setupvfs-style kit |
||||||
|
writers, rechan - stays G-101 suite-side territory (kbskit/KitCreator kitsh are |
||||||
|
the references, per G-101's reading order), and mk4vfs.tcl ships with tclvfs |
||||||
|
which the suite already builds. tequila/mkshow/mk4too stay reference-only unless |
||||||
|
a need appears. |
||||||
|
|
||||||
|
Sequencing value: milestones 1-2 (standalone build; dll smoke under tclsh86t) |
||||||
|
need no shellspy changes at all, and the dll milestone doubles as G-101's cheap |
||||||
|
first probe for the sdx bootstrap circularity (run sdx under the suite-built |
||||||
|
dynamic shell with Mk4tcl loaded as a package - option (a) in G-101's sdx |
||||||
|
section) and as the proof that a zig-built Mk4tcl works at all. |
||||||
|
|
||||||
|
## Approach |
||||||
|
|
||||||
|
- Target axis from day one: build.zig uses b.standardTargetOptions like punkzip |
||||||
|
and build86.zig; test steps run for x86_64-windows AND x86-windows (WoW64 |
||||||
|
executes 32-bit natively on the x64 host - force the run steps if the builder |
||||||
|
classifies the target foreign). Resolved triples map to punk canonical names |
||||||
|
(x86-windows-gnu -> win32-ix86) for any artifact naming. |
||||||
|
- Tcl headers without losing standalone buildability: a -Dtcl-src=<path> build |
||||||
|
option whose default is a lazy build.zig.zon dependency on the SAME tcl |
||||||
|
core-8-6-branch tarball pin suite_tcl86 carries (checkout 1d1d5cbd91), so |
||||||
|
source identity matches the suite and a bare clone still builds with no |
||||||
|
punkshell present. The dll shape links tclstub86; the static shape compiles |
||||||
|
for Tcl_StaticPackage registration. |
||||||
|
- Suite consumption shape (when G-101 lands it): unlike tcl/thread/tclvfs (raw |
||||||
|
trees + suite-authored recipes), metakit_punk brings its own build.zig - the |
||||||
|
suite consumes it as a zig package dependency (b.dependency().artifact()) |
||||||
|
rather than growing a forked build_mk4tcl86 recipe. Expose installed headers + |
||||||
|
named static libs cleanly for that. |
||||||
|
- Referencing is pin-only: no wholesale vendor of the fork into shellspy while |
||||||
|
the port churns. If a make.tcl-level tool step later needs to rebuild metakit |
||||||
|
from a bare shellspy checkout, the punkzip vendoring pattern |
||||||
|
(src/tools/<name>/ + PROVENANCE.md, edit-upstream-first, re-vendor procedure, |
||||||
|
G-063-style licence records) transfers directly. |
||||||
|
- Restraint rules from the fork's own docs carry extra force during the port: |
||||||
|
never re-simplify the pooryorick paren/brace hygiene; prefer per-file warning |
||||||
|
flags in build.zig over source edits so diffs against the reference snapshot |
||||||
|
stay meaningful. |
||||||
|
- Early C++ spike before porting all ~47 files: link a trivial C++ static lib |
||||||
|
into a copy of the kit-class shell target at both arches (zig's libc++ is |
||||||
|
static on windows-gnu targets - measured 2026-08-02, no new dll imports beyond |
||||||
|
the UCRT set the shells already carry, recorded in G-130 Notes) and check |
||||||
|
whether metakit's THROW layer permits -fno-exceptions, which simplifies the |
||||||
|
i386 EH story. |
||||||
|
|
||||||
|
## Notes |
||||||
|
|
||||||
|
- Related: G-101 (proposed) - the primary consumer: this goal is its mk4 |
||||||
|
candidate's leadup, separately landable; the container decision, boot chain, |
||||||
|
sdx provenance/circularity, and the metakit-under-Tcl-9 port-cost survey all |
||||||
|
live there. G-101 flags "deciding which patch lineage to carry is a required |
||||||
|
step" - this goal's patch audit IS that step, landing as fork commits. |
||||||
|
- Related: G-131 (proposed) - the strongest argument for the mk4 candidate is |
||||||
|
one container format across both generations; G-131's metakit arm cannot |
||||||
|
complete before the port work this goal starts. The 8.6-side shapes land |
||||||
|
here; the Tcl 9 mk4tcl port stays future work at the cost G-101 surveyed |
||||||
|
(~23 Tcl_Size call sites, one Tcl_ChannelType, five Tcl_ObjType |
||||||
|
initialisers) - keep version-sensitive spots localized as they are touched, |
||||||
|
do not port to 9 under this goal. |
||||||
|
- Related: G-130 (proposed) - the win32-ix86 axis is baked into this goal's |
||||||
|
acceptance (dual-arch tests + mk4 interchange check) so the fork never grows |
||||||
|
an x64-only assumption; G-130 owns the 32-bit runtimes themselves. The |
||||||
|
interchange check matters because punkshell's cross-baking path writes kits |
||||||
|
on the x64 host for ix86 runtimes (the G-127 target-keyed bake lineage - |
||||||
|
achieved 2026-07-31, see goals/archive/G-127-crosstarget-vfs-bake.md). |
||||||
|
- Related: G-105 (proposed) - platform-name canon and the zig-triple <-> |
||||||
|
platform-dir mapping this goal's artifact naming follows. |
||||||
|
- Related: G-026 (proposed) and G-063 (proposed) - fork-boundary provenance and |
||||||
|
per-package licence records; metakit is MIT/X11 (license.terms retained in |
||||||
|
the snapshots and in ported sources; root LICENSE lands with first port). |
||||||
|
- Patch-audit inventory (from G-101's reference survey, KitCreator/mk4tcl/ |
||||||
|
patches/all/ vs metakit 2.4.9.7): 64-bit filespace, 32/64 fix, |
||||||
|
unregisterchans, fixeventchannels, shared-obj linker, ranlib/ar (eight files |
||||||
|
total). The pooryorick 2.4.9.8 baseline already absorbed at least the channel |
||||||
|
unregistration and stdint fixed-width types (per the fork-difference analysis |
||||||
|
in metakit_punk src/reference/AGENTS.md); the 64-bit filespace and |
||||||
|
fixeventchannels lineage are the likely live ones. Audit each; x86_64 |
||||||
|
correctness hinges on the 64-bit set, and the linker/ranlib ones are expected |
||||||
|
autoconf-era rejects. |
||||||
|
- Draft sources.config record for suite_tcl86 (name/dir chosen to match the |
||||||
|
gitea repo name; dir names are recipe-coupled per that file's header): |
||||||
|
`source metakit git https://www.gitea1.intx.com.au/jn/metakit <commit> metakit` |
||||||
|
(commit pin like punkzip - the fork carries no tags yet; the ssh origin |
||||||
|
ssh://git@pcm-gitea1.corp.intx.com.au:2222/jn/metakit is the push remote, the |
||||||
|
https web URL is the fetch/pin form). |
||||||
|
- Draft build.zig.zon record for suite_tcl86 (hash computed with the pinned zig |
||||||
|
at landing time - 'zig fetch' from the suite dir per that file's TRAP note): |
||||||
|
`.metakit = .{ .url = "https://www.gitea1.intx.com.au/jn/metakit/archive/<commit>.tar.gz", .hash = "<zig-fetch>", .lazy = true },` |
||||||
|
- UCRT/deployment: adding the C++ engine to shells changes exe size, not the |
||||||
|
redistribution story - zig links libc++ statically on windows-gnu and the CRT |
||||||
|
import surface stays the UCRT set measured in G-130 Notes (2026-08-02). |
||||||
|
- 32-bit specifics: metakit's native era was 32-bit, so risk direction is |
||||||
|
benign; mmap address space caps very large datafiles on ix86 (irrelevant at |
||||||
|
kit scale - worth one doc line in the fork); the mk4 FILE FORMAT is |
||||||
|
portable across arches by design, which is exactly what the interchange |
||||||
|
acceptance pins. |
||||||
|
- Version/package identity: keep `package provide Mk4tcl` at an upstream-shaped |
||||||
|
version initially (2.4.9.8-era) for boot-script compatibility; fork releases |
||||||
|
take their own repo-level versioning like punkzip did (v2.x.y). Decide the |
||||||
|
exact package-version policy at first dll landing and record it here. |
||||||
|
- Overlap survey 2026-08-02: goals_xref paths src/buildsuites/suite_tcl86, |
||||||
|
src/buildsuites, bin/runtime/win32-ix86 -> G-101 G-131 G-105 G-130 (all |
||||||
|
named above); suite_tcl90-side neighbours G-108/G-110/G-116 are |
||||||
|
target/debug/tls lanes with no metakit coupling beyond shared suite dirs. |
||||||
Loading…
Reference in new issue