punkshell/goals/G-105-buildsuite-cross-target.md

G-105 buildsuite cross-target builds (zig -target): linux first, WSL-verified

Status: proposed Scope: src/buildsuites/suite_tcl90/ (target parameterization of recipe + driver; per-target out prefixes), src/buildsuites/ (layout/naming decision: target is an INVOCATION DIMENSION, suite folders stay version-named - no per-target tree copies), bin/runtime platform-dir naming alignment (punkshell's win32-x86_64-style names vs zig triples), punkbin per-target artifact layout (with G-103 metadata carrying the target), local WSL as the first cross-verification environment Goal: buildsuites accept a target parameter (zig -target triple) producing isolated per-target outputs from the same suite tree, with the first cross target being linux x86_64 verified end-to-end using the local WSL: the cross-built tclsh (plus at least thread and tclvfs) runs there, executes scripts, loads its packages, and a core-testsuite run under WSL is recorded against its own expected-failure baseline. The layout/naming decision for buildsuites and artifact dirs is made and documented so later targets (freebsd, aarch64 variants) slot in without restructuring. Acceptance: a documented suite invocation with a target argument produces out// (or equivalent isolated prefix) without disturbing the native build; the linux tclsh runs under the local WSL executing a script and package require checks for thread/vfs (recorded here); a core-test run under WSL is gated against a tracked linux baseline (separate from the windows baseline; dispositioned entries); dynamic-extension loading works on the chosen linux flavour (the fully-static-musl 'load' limitation is the recorded reason the first target is dynamic - x86_64-linux-gnu with a pinned glibc floor, or musl-dynamic - decision + rationale recorded at activation); folder/naming decisions (suite dirs version-named, target as parameter; platform-name mapping between punkshell dirs and zig triples) are documented; punkbin layout accommodates the target dimension with G-103 metadata.

Context

User requirement 2026-07-20: "We will eventually want to use zig's cross-platform build capabilities - a first target might be for linux - something we can test with our local wsl. This has implications for how we structure/name the folders under buildsuites." Current linux runtime is a prebuilt tclkit (mapvfs.config: tclkit-902-Linux64-intel-dyn -> punkshell902 kit) - same provenance gap the suites close on windows.

zig platform-tier findings (verified 2026-07-20 - the user's asymmetry suspicion is INVERTED):

• Windows/linux AS TARGETS ship their libcs with zig on every host (mingw-w64, glibc stubs, musl) - building them FROM freebsd/macos/etc is supported; the host mostly doesn't matter for punkshell's primary pair.
• FreeBSD AS A TARGET was the historically missing piece: zig 0.16 added cross-compilation to FreeBSD 14+ (stub dynamic libc a la glibc; x86_64-freebsd and aarch64-freebsd now tested in zig's CI). Note zig still DEFAULTS to freebsd 13 - the triple must pin >=14 for cross builds.
• macOS AS A TARGET is the genuinely hard case: Apple SDK/frameworks are not shipped with zig (licensing) - anything linking system frameworks (Tk/Aqua!) needs an SDK arrangement. Out of scope here; recorded so nobody assumes triple-swap suffices.
• linux dlopen caveat driving the first-target choice: a fully-static musl build cannot usefully 'load' shared extensions - a tclsh that loads thread/vfs dlls wants dynamic linking (glibc-stub dynamic with a chosen version floor, or musl-dynamic).

Relationships: G-060 (qemu cross-platform matrix - WSL is the cheap first rung; qemu covers what WSL cannot), G-099/G-100 (the 8.6 suite inherits the target dimension), G-102 (achieved 2026-07-21 - driver shape settled; target becomes a build-graph dimension), G-103 (family x target = the punkbin artifact matrix), G-006 (punkbin artifact consent).

Notes

• 2026-07-21: this goal's dynamic-libc choice for the first linux target has a working existence proof - standard linux tclkitsh binaries are self-contained (Tcl core + script library embedded in a Metakit/zip VFS) yet DYNAMICALLY linked to libc, which is exactly why they can 'load' binary extensions. Self-contained and static-libc are orthogonal (tclkit gets the first from the embedded VFS, not by static-linking libc), so the fully-static-musl 'load' limitation stands and dynamic (glibc-stub-dynamic with a version floor, or musl-dynamic) is the tclkit model. Compiled-in batteries ('load {} ', no dlopen) are G-058's alternative (achieved 2026-07-10 - see goals/archive/G-058-static-runtime-packages.md). Don't re-litigate at activation.
• 2026-07-21: per-platform temp-file cleanup is part of verifying dynamic-loaded batteries here - a shared lib loaded from a kit's VFS is copied to a temp dir first (dlopen/LoadLibrary need a real file) and cleanup of those copies is a known wart (Tcl core TIP 741, windows-framed). Test on linux/WSL (and the G-060 guests) that it does not accumulate, or characterize it. TIP 741 detail
  • the cross-platform requirement: G-103 Notes.
• 2026-07-21: linux leg of the temp-cleanup characterization is BLOCKED on a linux tcl9 runtime - the local WSL has only tcl 8.6.14 (no zipfs), so the zipfs copy-to-temp path cannot be exercised there. Needs a linux tcl 9.0+ with zipfs + a loadable .so (this goal's own cross-build, or an apt/self-built tcl9). Windows is fully characterized (confirmed flaw, both direct-kit and modpod-.tm binary loads - G-103/G-066 Notes); the linux expectation stays no-accumulation (unlink-while-mapped) but is UNVERIFIED until a runtime exists.