punkshell/goals/G-018-zig-plain-tclsh-kits.md

G-018 Zig-built plain tclsh kits: self-contained zip-based executables without punk infrastructure

Status: proposed Scope: build.zig / build.zig.zon (per G-005), src/runtime/, src/make.tcl integration Goal: developers can use the G-005 zig build system to produce self-contained zip-based tclsh executables that carry no punk-specific infrastructure (no punk boot layer, punk modules, or punk apps) - plain tclsh kits usable independently of the punkshell product. Acceptance: a documented zig invocation on a clean checkout (zig toolchain available) produces a zip-based tclsh executable for at least one target platform that runs conventional tclsh invocations (<exe> script.tcl args, piped stdin) on a machine with no Tcl installation; a listing of the kit's mounted/zip contents shows stock Tcl (plus any declared stock runtime deps) and no punk namespaces, punk boot files, or punkshell apps; the punk-flavoured executables remain producible alongside.

Context

G-005 establishes zig-based build infrastructure to build binary dependencies (including Tcl9) from source. This goal extends that infrastructure's output targets: beyond building the punkshell product's own runtimes, developers should be able to produce plain, self-contained, zip-based tclsh executables with no punk-specific infrastructure at all - no punk boot layer (punk_main.tcl dispatch), no punk modules, no punkshell apps. A general-purpose single-file tclsh, useful independently of punkshell.

This defines one end of a deliberate spectrum of buildable executables:

• plain tclsh kit (this goal) - stock Tcl only
• trimmed punk executable (G-019) - punk infrastructure plus only the modules a dependency scan proves needed
• 'batteries included' punk executable - the current full-kit approach

Approach

• Zip-based (zipfs) kit assembly as the packaging mechanism, consistent with Tcl 9's built-in zipfs support.
• Tcl 8.6 phasing (decided 2026-07-06): the 8.6 kit mechanism is more complex to support (no built-in zipfs) and is wanted in the end, but must not block other work. Interim step: support plain (non-kit) tcl 8.6 builds from the zig infrastructure, and implement 8.6 kits when practical. This goal's acceptance is satisfiable by a Tcl 9 kit alone; 8.6 kit support is a follow-on within the same goal's spirit, not a gate.
• The plain kit is a natural first smoke target for G-005's Tcl-from-source build: it exercises the compiled runtime with minimal packaging logic before the more elaborate punk kit assembly.
• src/make.tcl integration so the target is invocable through the normal project build entrypoint as well as directly via zig.

Alternatives considered

• Relying on third-party tclkit/kitcreator builds for plain kits - rejected as the durable answer: the point of G-005 is developer-reproducible builds from source in this project's toolchain, and external kit builders are exactly the committed-binary/procurement dependency G-004..G-006 are removing.

Notes

• Depends on G-005 (zig builds Tcl from source); complements G-004 (no committed binaries) by making plain runtimes reproducible on demand.
• 'Self-contained' means: runs conventional tclsh invocations on a machine with no Tcl installation - stock Tcl library scripts ride inside the kit.
• Wish executables are not a build target at any point on the spectrum: kits that want Tk ship it as a loadable package (as the punk Windows kit already does - package require Tk from the tclsh-style executable, console retained). Applies to plain kits here and punk kits alike.