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