diff --git a/GOALS.md b/GOALS.md index ede4a217..6464b99e 100644 --- a/GOALS.md +++ b/GOALS.md @@ -365,3 +365,15 @@ Detail: goals/G-101-tcl86-kit-container-strategy.md ### G-102 [proposed] buildsuite bootstrap without a pre-existing tclsh: zig-driver hybrid Scope: src/buildsuites/suite_tcl90/ (driver split: zig-layer fetch/generate/compile + suite-tclsh-run Tcl phases; sources.config -> zon-shaped manifest migration), src/buildsuites/ (the pattern future suites fork - interplay with G-099), bin/tools/ (pinned zig acquisition per the consent-gated mechanism), src/scriptapps/bin/ punk-getzig (acquisition layer, unchanged in role) Detail: goals/G-102-buildsuite-zig-bootstrap.md + +### G-103 [proposed] runtime kit family from buildsuites: plain / punk / bi kits with attached batteries + artifact metadata +Scope: src/buildsuites/suite_tcl90/ (kit assembly steps in recipe/driver; pattern for later suites), src/vfs/_config + src/runtime/mapvfs.config (as consumers of the new runtime names), punkbin repo layout + metadata (c:/repo/jn/punkbin; compatible repos), src/scriptapps runtime scriptset ('runtime.cmd' list/use - punk-runtime rename pending G-097), goals/G-018 (subsumption review) +Detail: goals/G-103-runtime-kit-family.md + +### G-104 [proposed] make.tcl buildsuite surface: list / info / build +Scope: src/make.tcl (buildsuite subcommand group), src/buildsuites/*/ (suite self-description contract: an 'info'/describe affordance per suite - suite.tcl action or manifest record), documentation (make.tcl help text, src/buildsuites README/AGENTS) +Detail: goals/G-104-maketcl-buildsuite-surface.md + +### G-105 [proposed] buildsuite cross-target builds (zig -target): linux first, WSL-verified +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 +Detail: goals/G-105-buildsuite-cross-target.md diff --git a/goals/G-096-zig-buildsuite-piperepl.md b/goals/G-096-zig-buildsuite-piperepl.md index 1d48abe9..b38304f5 100644 --- a/goals/G-096-zig-buildsuite-piperepl.md +++ b/goals/G-096-zig-buildsuite-piperepl.md @@ -300,4 +300,9 @@ Remaining for acceptance: tty/piped/script-arg forms; =1 with a script setting ::tclsh(dorepl) 1 -> live interactive console repl after piped eof with unconsumed input in ::tclsh(inputbuffer)). + KIT-DEFAULT POLICY UPDATE (2026-07-20, G-103): with a kit FAMILY the env gating + flips for punk kits - the patch is applied and ENABLED BY DEFAULT there (env + opt-OUT, e.g TCLSH_PIPEREPL=0), while the PLAIN family member carries no patch + for stock semantics. The matrix above still characterizes the patch itself on + the patched binary; restate it in opt-out terms when the variant lands. - Final clean-checkout re-verification of the whole flow once the above land. diff --git a/goals/G-101-tcl86-kit-container-strategy.md b/goals/G-101-tcl86-kit-container-strategy.md index fe6417a5..9fc786d1 100644 --- a/goals/G-101-tcl86-kit-container-strategy.md +++ b/goals/G-101-tcl86-kit-container-strategy.md @@ -25,6 +25,12 @@ zip-wrap). 8.6 has no zipfs, so a kit needs a vfs container and a boot mechanism make.tcl's existing 'kit' wrap type drives sdx/mk4-style wrapping; whichever container is chosen must either fit that path or come with a documented successor. +The G-103 runtime kit family (plain/punk/bi kits with thread + tclvfs + tcllib +batteries in the attached container) extends to 8.6 THROUGH this investigation: the +user notes (2026-07-20) that in the 8.6 case tclvfs may have to be STATIC and there +may be metakit-specific patching - both are part of this goal's assessment, and the +8.6 family variant is blocked on its outcome. + Separated from G-099/G-100 deliberately: runtime + libs + test gating are well-understood ports of the 9.0 work, while this is open investigation - keeping it out of their acceptance keeps the 8.6 suite arc incrementally landable. diff --git a/goals/G-102-buildsuite-zig-bootstrap.md b/goals/G-102-buildsuite-zig-bootstrap.md index 9296981a..01d819f1 100644 --- a/goals/G-102-buildsuite-zig-bootstrap.md +++ b/goals/G-102-buildsuite-zig-bootstrap.md @@ -56,4 +56,8 @@ so the manifest migration is mechanical. ## Notes -(none yet) +- 2026-07-20 (user requirements batch): the build-graph products this driver shape + must express grew concrete - the G-103 runtime kit FAMILY (plain/punk/bi kits with + attached batteries) become named build outputs, G-105 adds -target as a build + dimension, and G-104's make.tcl surface fronts whichever driver shape wins (its + suite self-description contract must survive the migration). diff --git a/goals/G-103-runtime-kit-family.md b/goals/G-103-runtime-kit-family.md new file mode 100644 index 00000000..a9e28c51 --- /dev/null +++ b/goals/G-103-runtime-kit-family.md @@ -0,0 +1,50 @@ +# G-103 runtime kit family from buildsuites: plain / punk / bi kits with attached batteries + artifact metadata + +Status: proposed +Scope: src/buildsuites/suite_tcl90/ (kit assembly steps in recipe/driver; pattern for later suites), src/vfs/_config + src/runtime/mapvfs.config (as consumers of the new runtime names), punkbin repo layout + metadata (c:/repo/jn/punkbin; compatible repos), src/scriptapps runtime scriptset ('runtime.cmd' list/use - punk-runtime rename pending G-097), goals/G-018 (subsumption review) +Goal: buildsuites produce a defined FAMILY of runnable, self-contained runtime kits - executables whose info library and core batteries live in the initially attached zip, depending on no external filesystem tree: (1) a PLAIN tclsh kit carrying loadable Thread, tclvfs with as many vfs::* packages as we have, and tcllib+tcllibc; (2) a PUNK kit = the plain kit with the TCLSH_PIPEREPL patch applied and ENABLED BY DEFAULT (env opt-out, not opt-in - users wanting stock behaviour take the plain kit); (3) BI (batteries-included) punk kits additionally carrying libraries WE BUILD - Tk first; sqlite3/tdom/twapi as future build targets - all in the attached zip. These are the project's 'runtime' executables: punkbin candidates carrying metadata (variant, component versions, target platform, provenance) that runtime list/use subcommands can surface. +Acceptance: suite_tcl90 produces named artifacts for at least plain, punk, and one bi (+Tk) kit; each verified self-contained from a path with no external Tcl visible (info library resolves into the attached zip; package require checks for Thread, vfs + representative vfs::* packages, tcllib module + tcllibc acceleration engaged; bi adds Tk create/destroy) with the checks recorded here; the punk kit demonstrates piperepl active by default and disabled via the documented env opt-out, the plain kit demonstrates stock behaviour (no patch); artifact metadata (variant, versions, target, source provenance) is emitted alongside the binaries in the punkbin layout and surfaced by the runtime scriptset's list/use; the naming scheme for family members is documented and mapvfs.config consumes the punk/bi runtimes; the 8.6 family variant is explicitly deferred to the G-101 container investigation (static vfs / metakit patching questions). + +## Context + +User requirements 2026-07-20. Formalizes and extends what suite_tcl90 half-delivers: +tclsh90szip.exe already attaches the tcl library (self-contained info library ✓) but +thread/tclvfs/tcllib ride outside (out/lib or the punk .vfs payload) - the note from +G-098 (achieved 2026-07-20), "future: attach at least tclvfs & thread to the +runtime's own zip", becomes a +requirement here, extended to tcllib+tcllibc for all family members (user lean, +agreed: tcllib is widely used and tcllibc's speedup makes bootstrapping and other +usecases far more practical; zip compression keeps the cost modest - a leaner +variant remains possible later via configuration rather than a separate philosophy). + +piperepl gating REVIEW (user 2026-07-20): the patch's original env gating +(TCLSH_PIPEREPL=1 opt-in) fit a single-binary world. With a kit FAMILY the punk kits +are FOR punk use - default ON, env opt-OUT (e.g TCLSH_PIPEREPL=0) for debugging; +the plain kit exists for those who want stock semantics. G-096's behaviour-matrix +item still characterizes the patch itself; its kit-default policy is restated there +pointing here. + +Family boundary: bi kits carry libraries WE BUILD (zig-only policy) - not vendored +third-party binaries. Tk is built today; sqlite3 is a straightforward future build +(amalgamation compiles cleanly under zig cc); tdom moderate; twapi historically +MSVC-leaning - its buildability under the zig-only policy needs investigation before +it can join a bi kit (until then twapi remains a kit-vfs vendored payload as in +punk9wintk903.vfs, outside this family's attached-zip guarantee). + +Metadata format note: toml is acceptable HERE (runtime list/use run in punkshell +contexts where vendored tomlish exists) - the 2026-07-20 toml drop applies to +BUILDSUITE BOOTSTRAP configs which must parse dependency-free, a distinct concern. +punkbin currently carries sha1sums.txt (+ minisign) - metadata extends, not +replaces, that. Compatible repos (punkbin mirrors) carry the same records. + +Relationships: G-018 (zig plain tclsh kits) is substantially subsumed by the plain +family member - reconciliation/retirement decision flagged for the user. G-102 +(zig-driver hybrid): the family members become named build-graph products. G-105 +(cross-target): family x target is the punkbin artifact matrix - metadata carries +the target dimension. G-101: the 8.6 family variant depends on the container +strategy. G-006: punkbin download consent. G-097: runtime.cmd -> punk-runtime +rename interplay. + +## Notes + +(none yet) diff --git a/goals/G-104-maketcl-buildsuite-surface.md b/goals/G-104-maketcl-buildsuite-surface.md new file mode 100644 index 00000000..ccf8a5d7 --- /dev/null +++ b/goals/G-104-maketcl-buildsuite-surface.md @@ -0,0 +1,35 @@ +# G-104 make.tcl buildsuite surface: list / info / build + +Status: proposed +Scope: src/make.tcl (buildsuite subcommand group), src/buildsuites/*/ (suite self-description contract: an 'info'/describe affordance per suite - suite.tcl action or manifest record), documentation (make.tcl help text, src/buildsuites README/AGENTS) +Goal: an ergonomic make.tcl surface for defined buildsuite builds: 'make.tcl buildsuite list' discovers the suites under src/buildsuites (excluding _build and non-suite dirs) with one-line descriptions; 'make.tcl buildsuite info ' surfaces the configured detail for review - source records from sources.config (urls/refs/pins), the pinned zig, the product set, doc pointers; 'make.tcl buildsuite build ?args?' runs the suite's driver forwarding suite options (e.g -tclbranch, -refresh, -target when G-105 lands). Suites stay SELF-describing so copy-and-tweak trees (G-096 workflow) appear in list/info automatically without make.tcl edits. +Acceptance: list shows suite_tcl90 (and any copied tree) with descriptions sourced from the suites themselves; info renders the sources.config-derived table plus zig pin and products for a named suite; build forwards arguments and streams driver output, exiting with the driver's status; the surface works when make.tcl runs under a plain tclsh and under punk kit executables; help text documents the group; the self-description contract is documented where suite authors will find it (src/buildsuites docs) and holds for a tree created by copying suite_tcl90. + +## Context + +User requirement 2026-07-20: "an ergonomic way to run a defined buildsuite build - +nice-to-have is a way to list possible builds and considering there is a fair bit of +configured info for each, a way to retrieve/review info about a particular +buildsuite. Presuming surface will be a subcommand or group of subcommands in +make.tcl." + +Design lean: make.tcl stays a THIN front - discovery by directory scan, description +and info answered by the suite itself (a 'suite.tcl info' action emitting a stable +record, or a small manifest the driver also reads). That keeps copied/retargeted +trees first-class citizens and survives the G-102 driver-shape migration (whatever +replaces suite.tcl keeps answering the same contract; make.tcl need not know which +shape a suite uses). + +Sibling ergonomics note: the earlier-recorded make.tcl 'vfs' wishes (build a single +configured kit by name + list configured kits from mapvfs.config - noted in +mapvfs.config comments and archived G-098 (achieved 2026-07-20) notes) are a +separate subsystem (kit wrapping) but the same ergonomic family - a candidate to +execute alongside this goal. + +Relationships: G-096 (suite.tcl driver + copy-and-tweak workflow this fronts), +G-102 (driver shape - the info/build contract must survive it), G-103 (family +products appear in info output), G-105 (target dimension forwarded when it exists). + +## Notes + +(none yet) diff --git a/goals/G-105-buildsuite-cross-target.md b/goals/G-105-buildsuite-cross-target.md new file mode 100644 index 00000000..8854dc6a --- /dev/null +++ b/goals/G-105-buildsuite-cross-target.md @@ -0,0 +1,42 @@ +# 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 (driver shape: target becomes a build-graph dimension), G-103 +(family x target = the punkbin artifact matrix), G-006 (punkbin artifact consent). + +## Notes + +(none yet) diff --git a/src/modules/punk/libunknown-0.2.0.tm b/src/modules/punk/libunknown-0.2.1.tm similarity index 100% rename from src/modules/punk/libunknown-0.2.0.tm rename to src/modules/punk/libunknown-0.2.1.tm