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.
• 2026-07-22: punk-runtime grew the cross-platform staging surface this goal will consume (user-approved; details in G-103 Progress 2026-07-22): fetch/list/use -platform with local-platform default (PUNK_RUNTIME_PLATFORM env override), foreign fetch name-required, list !TARGET-MISMATCH integrity flag from the G-103 metadata target field, run local-only. Platform-dir naming alignment progress: bash payload's FreeBSD dir aligned to punkbin's actual freebsd-x86_64 (was freebsd-amd64). Still open for this goal's alignment item: the zig-triple <-> platform-dir mapping itself, openbsd-amd64 (payload) vs the x86_64 convention, and a windows-arm default for the ps1 payload once punkbin carries such a folder.
• 2026-07-22 CANONICAL PLATFORM NAMES SETTLED (user-directed survey of punkbin vs punkshell platform folders; resolves this goal's "platform-dir naming alignment" item on the punkshell side - the zig-triple <-> platform-dir mapping remains this goal's build-time work). Canon = punk::platform module (src/modules/punk/ platform-999999.0a1.0.tm; 'help platforms' topic): - punkshell platform-dir names with cpu normalized amd64->x86_64, aarch64->arm64 (arm = 32-bit; on macosx arm folds to arm64), os macos->macosx; special universal 'macosx' for the runtime tier (punkbin + bin/runtime keep ONE macOS folder - make.tcl convention blessed), per-arch macosx-x86_64/macosx-arm64 for lib trees. Supported: win32-x86_64, linux-x86_64, linux-arm64, linux-arm, macosx, macosx-x86_64, macosx-arm64, freebsd-x86_64, freebsd-arm64. Dormant: msys-x86_64 (utility under user review). Recognized (no artifacts): openbsd/netbsd/dragonflybsd-x86_64. Tcl's platform package stays the RAW identifier (version-varying outputs: 1.1.x renamed macos, aarch64 passthrough); punk::platform::normalize is the folding layer; the punkboot platform_generic snips (punk_main/project_main/make.tcl) gained an inline platform_punk normalization (kept in sync by comment contract). vendorlib_tcl8/9 platform subfolders synchronized to canon (freebsd-amd64 -> freebsd-x86_64 rename; freebsd-arm64/linux-arm64/macosx-arm64 added; stray untracked macosx-arm empties removed). punk-runtime prongs emit canon (linux-arm64 has NO fetch default until punkbin carries that folder). FLAGGED for user decisions: (a) punkbin linux-arm holds tclkit-902-Linux64-arm-dyn which by its name is an arm64 build - recommend a linux-arm64 punkbin folder at next arm publish (artifacts immutable, no moves); (b) msys-x86_64 disposition; (c) vendored platform-1.0.19 vs core 1.1.x re-vendor (normalization makes punkshell robust either way - upgrade optional); (d) src/vfs stays UNcategorized by platform (mapvfs mappings + purpose-names carry the platform axis) - acceptable now; recommend revisiting when G-105 cross-wraps land (a mapvfs platform column per make.tcl's existing x-platform TODO beats restructuring the .vfs tree).
• 2026-07-22 addendum (user review): punk::platform records gained a 'buildsuite' axis (supported|planned|candidate|none) - whether OUR zig buildsuite system produces runtimes for a platform - deliberately separate from the tiers axis, because punkbin (or third-party repos using the same structure) can host runtimes built by any mechanism: a platform can be runtime-tier hosted while buildsuite=none (netbsd/dragonflybsd-class examples). Current values: win32-x86_64 supported (suite_tcl90), linux-x86_64 planned (this goal), linux-arm64/linux-arm/macosx/freebsd-* candidate, remainder none. This goal updates the field as targets land.