From 3a49aa4c484c90e004c1f1778d7a5c5c0b558be2 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Wed, 22 Jul 2026 11:10:27 +1000 Subject: [PATCH] punk::platform buildsuite axis; record binary-.tm platform-segregation constraints (G-109) - platform records + 'help platforms' gain buildsuite (supported|planned|candidate|none): whether OUR zig buildsuites produce runtimes for a platform. Deliberately a separate axis from tiers - punkbin-structured repos (or third-party equivalents) can host runtimes built by any mechanism, so runtime-tier hosting coexists with buildsuite=none (netbsd/dragonflybsd-class examples, per user review). openbsd/netbsd/dragonflybsd records now carry the runtime tier. Current values: win32-x86_64 supported (suite_tcl90), linux-x86_64 planned (G-105), linux-arm64/linux-arm/macosx/freebsd-* candidate, rest none. - G-109 notes record the binary-.tm platform reality the user's fat-tm experience established (retracting this survey's earlier 'tm-are-cross-platform' shorthand): multi-platform fat .tm are the wrong shape (oversized downloads; same-version shadowing leaves no drop-in path), platform segregation must ride tcl::tm::path via per-platform TM ROOTS selected by boot - and platform dirs cannot nest inside an existing tm root (subdirs are namespace components), so those roots must be sibling trees. Candidate manifest field: declared target platform so libunknown can skip wrong-platform binary .tm. Project 0.18.1. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- CHANGELOG.md | 4 ++ goals/G-105-buildsuite-cross-target.md | 9 ++++ .../G-109-libunknown-manifest-multiname-tm.md | 17 ++++++ punkproject.toml | 2 +- src/modules/punk-999999.0a1.0.tm | 30 ++++++----- src/modules/punk-buildversion.txt | 2 +- src/modules/punk/platform-999999.0a1.0.tm | 52 ++++++++++++------- src/modules/punk/platform-buildversion.txt | 2 +- 8 files changed, 85 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 25708bbf..15b5f23d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ The latest `## [X.Y.Z]` header must match the `version` field in `punkproject.to Entries are newest-first; one bullet per notable change. See the root `AGENTS.md` "Project Versioning" section for the bump policy. +## [0.18.1] - 2026-07-22 + +- `punk::platform` records + `help platforms` gain a `buildsuite` axis (supported/planned/candidate/none): whether the punkshell zig buildsuites produce runtimes for a platform - deliberately separate from the artifact-tree tiers, since punkbin-structured repos can host runtimes built by any mechanism (a platform can be runtime-tier hosted while buildsuite=none, e.g. netbsd/dragonflybsd). openbsd/netbsd/dragonflybsd records now carry the runtime tier (hosted third-party runtimes possible). + ## [0.18.0] - 2026-07-22 - Canonical punkshell platform names (platform-folder synchronization survey; G-105 groundwork). New module `punk::platform` 0.1.0: `platforms` (canonical records with status supported/dormant/recognized and artifact-tree tiers), `normalize` (folds Tcl platform-package version-dependent aliases: amd64->x86_64, aarch64->arm64, macos->macosx, macosx arm->arm64), `local ?-tier lib|runtime?` (runtime tier collapses macOS per-arch to the universal `macosx` runtime-store name). New `help platforms` shell topic (punk 0.2.7) renders the canon with the running interpreter marked and the raw platform-package identifiers for comparison. Boot machinery (punkboot platform_generic snips in punk_main.tcl/project_main.tcl/make.tcl) now normalizes via an inline copy of the same mapping (platform_punk). `src/vendorlib_tcl8`/`_tcl9` platform subfolders synchronized to the canon: freebsd-amd64 renamed freebsd-x86_64, new freebsd-arm64/linux-arm64/macosx-arm64 (+ tracked linux-arm), msys-x86_64 marked dormant pending a utility decision. punk-runtime bash platform prongs emit canonical names (aarch64->linux-arm64 with no fetch default yet, arch-aware freebsd/openbsd/netbsd/dragonflybsd). diff --git a/goals/G-105-buildsuite-cross-target.md b/goals/G-105-buildsuite-cross-target.md index a6ef2472..21e337fc 100644 --- a/goals/G-105-buildsuite-cross-target.md +++ b/goals/G-105-buildsuite-cross-target.md @@ -102,3 +102,12 @@ dimension), G-102 (achieved 2026-07-21 - driver shape settled; target becomes a (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. diff --git a/goals/G-109-libunknown-manifest-multiname-tm.md b/goals/G-109-libunknown-manifest-multiname-tm.md index 44fff8c8..73d305e1 100644 --- a/goals/G-109-libunknown-manifest-multiname-tm.md +++ b/goals/G-109-libunknown-manifest-multiname-tm.md @@ -55,3 +55,20 @@ mount path - the 8.6 leg of acceptance), TIP 590 (lowercase naming), G-110 ## Notes - 2026-07-21: drafted and approved (user: "approved - apply both"). +- 2026-07-22 (platform-canon survey discussion; user experience recorded): + binary-bearing .tm modpods are PER-PLATFORM artifacts, and multi-platform + "fat" .tm files are the wrong shape - the user tried a multi-platform thread + .tm in the past and found it unworkable: (a) downloads far larger than any + one consumer needs, and (b) same-version shadowing - one name-version + resolves to ONE file under tm handling with no arch awareness, so a user + cannot drop in a replacement .tm carrying their platform when a same-version + copy is already on the path. Platform segregation for binary .tm therefore + has to happen via tcl::tm::path - PER-PLATFORM TM ROOTS selected by the boot + for the running platform (punk::platform canon names). NOTE the structural + constraint: platform dirs canNOT nest inside an existing tm root - a + subdirectory of a tm path is a NAMESPACE component (foo/bar-1.tm = foo::bar), + so per-platform roots must be sibling trees registered separately (layout + naming TBD when the need lands, e.g vendormodules_tcl9-/ siblings + or a byplatform// parent). Candidate defensive extra for THIS + goal's manifest format: a declared target-platform field, letting libunknown + skip/refuse wrong-platform binary .tm even when someone shares a path. diff --git a/punkproject.toml b/punkproject.toml index 64253049..ff3ffdc8 100644 --- a/punkproject.toml +++ b/punkproject.toml @@ -1,4 +1,4 @@ [project] name = "punkshell" -version = "0.18.0" +version = "0.18.1" license = "BSD-2-Clause" diff --git a/src/modules/punk-999999.0a1.0.tm b/src/modules/punk-999999.0a1.0.tm index e5de89ff..2a1a8f06 100644 --- a/src/modules/punk-999999.0a1.0.tm +++ b/src/modules/punk-999999.0a1.0.tm @@ -8990,16 +8990,19 @@ namespace eval punk { "Canonical punkshell platform names."\ -help\ "Show the canonical punkshell platform-dir names - (punk::platform::platforms) with status and the artifact-tree - tiers each name serves, marking the running interpreter's own - platform. These names organize the punkbin artifact repo's - platform folders, bin/runtime// (punk-runtime - fetch/list/use -platform), the lib_tclX / vendorlib_tclX - auto_path dirs wired by the boot, and the runtime-artifact - metadata target field. The raw Tcl platform-package identifiers - are shown for comparison (punk::platform::normalize folds their - version-dependent aliases - amd64/aarch64/macos - into the - canonical names)." + (punk::platform::platforms) with status, the artifact-tree + tiers each name serves, and the buildsuite axis (whether the + punkshell zig buildsuites produce runtimes for the platform - + separate from hosting: punkbin-structured repos can carry + runtimes built by any mechanism), marking the running + interpreter's own platform. These names organize the punkbin + artifact repo's platform folders, bin/runtime// + (punk-runtime fetch/list/use -platform), the lib_tclX / + vendorlib_tclX auto_path dirs wired by the boot, and the + runtime-artifact metadata target field. The raw Tcl + platform-package identifiers are shown for comparison + (punk::platform::normalize folds their version-dependent + aliases - amd64/aarch64/macos - into the canonical names)." @values -min 0 -max 0 } proc platforms {context args} { @@ -9016,15 +9019,16 @@ namespace eval punk { $t add_column -headers [list "Platform"] $t add_column -headers [list "Status"] $t add_column -headers [list "Tiers"] + $t add_column -headers [list "Buildsuite"] $t add_column -headers [list "Notes"] dict for {p pinfo} [punk::platform::platforms] { set pshown $p if {$p eq $local_lib || $p eq $local_runtime} { set pshown "* $p" } - $t add_row [list $pshown [dict get $pinfo status] [join [dict get $pinfo tiers] ,] [dict get $pinfo notes]] + $t add_row [list $pshown [dict get $pinfo status] [join [dict get $pinfo tiers] ,] [dict get $pinfo buildsuite] [dict get $pinfo notes]] } - foreach c {0 1 2} { + foreach c {0 1 2 3} { $t configure_column $c -minwidth [expr {[$t column_datawidth $c] + 2}] } $t configure -title $title @@ -9036,6 +9040,8 @@ namespace eval punk { append detail " runtime-tier $local_runtime" } append detail "\ntiers: runtime = punkbin + bin/runtime folders; lib = lib_tclX/vendorlib_tclX auto_path dirs" + append detail "\nbuildsuite: whether the punkshell zig buildsuites produce runtimes for the platform" + append detail "\n(a separate axis - punkbin-structured repos can host runtimes built by any mechanism)" catch { append detail "\nraw Tcl platform package ([package present platform]): generic [platform::generic] identify [platform::identify]" } diff --git a/src/modules/punk-buildversion.txt b/src/modules/punk-buildversion.txt index 3fcf3368..c303b26a 100644 --- a/src/modules/punk-buildversion.txt +++ b/src/modules/punk-buildversion.txt @@ -1,7 +1,7 @@ 0.2.7 #First line must be a semantic version number #all other lines are ignored. -#0.2.7 - new 'help platforms' topic (aliases: platform): canonical punkshell platform-dir names from punk::platform::platforms rendered with status/tiers/notes, the running interpreter's lib-tier and runtime-tier names marked, and the raw Tcl platform-package identifiers (generic/identify) shown for comparison. Degrades cleanly when punk::platform is unavailable. All platform/platforms prefixes are mutually ambiguous so they fall through to command lookup (env/environment precedent). +#0.2.7 - new 'help platforms' topic (aliases: platform): canonical punkshell platform-dir names from punk::platform::platforms rendered with status/tiers/buildsuite/notes (buildsuite = zig-buildsuite runtime production, a separate axis from hosting), the running interpreter's lib-tier and runtime-tier names marked, and the raw Tcl platform-package identifiers (generic/identify) shown for comparison. Degrades cleanly when punk::platform is unavailable. All platform/platforms prefixes are mutually ambiguous so they fall through to command lookup (env/environment precedent). #0.2.6 - G-076: 'help tcl' renders the mitigated/mitigation buginfo axis (punk::lib 0.4.3+): a triggered check reporting mitigated keeps its severity level but displays 'warning level: (mitigated)' in subdued grey (term-grey foreground) instead of the level colour, followed by an indented 'mitigated: ' block when mitigation text is supplied. Unmitigated warnings render unchanged. #0.2.5 - G-045: ::punk::helptopic::define_docs converts from interim left-margin authoring to indented block-form values under the new punk::args @normalize directive (the constructed-definition normalization consumer proof): basehelp/topichelp/help_chunks-extra are braced indented blocks with a structural leading newline, the generated definitions declare @normalize, and the -unindentedfields declarations from punk 0.2.4 are dropped. Rendered 'i help'/'i help_chunks' output unchanged (verified aligned incl. the blank-line separator in help_chunks). #0.2.4 - G-045: 'i help' usage table alignment - ::punk::helptopic::define_docs authors its help text at the left margin and declares -unindentedfields {-help} on both the generated @cmd line (honoured as of punk::args 0.6.1) and the topic argument line. Previously the @cmd -help braced literal carried ~16 spaces of source indent into the constructed definition (no whole-block normalization), rendering Description continuations +12 right of the first line, and the \n-relative topic -help rendered its first line +4 (the injected display prefix). Both blocks now render flush. Text content unchanged (manual ~70-col folding retained). diff --git a/src/modules/punk/platform-999999.0a1.0.tm b/src/modules/punk/platform-999999.0a1.0.tm index a4de7182..fc38b552 100644 --- a/src/modules/punk/platform-999999.0a1.0.tm +++ b/src/modules/punk/platform-999999.0a1.0.tm @@ -63,20 +63,29 @@ namespace eval punk::platform { #tiers: which artifact-tree tiers use the name - # runtime = punkbin platform folders + bin/runtime// # lib = lib_tclX/ + vendorlib_tclX/ auto_path dirs + #buildsuite: whether OUR zig buildsuite system (src/buildsuites; G-103 kit + #family, G-105 cross-target) produces runtimes for the platform. A SEPARATE + #AXIS from tiers deliberately: punkbin (or a third-party repo using the same + #structure) can host runtimes built by any mechanism - a platform can be + #runtime-tier hosted while buildsuite=none (we may never build it ourselves). + # supported - a tracked suite produces family artifacts today + # planned - named in an active/proposed goal (e.g G-105 linux-first) + # candidate - plausible zig target, no committed goal + # none - no build intention; hosted/third-party runtimes only variable platforms { - win32-x86_64 {status supported tiers {runtime lib} notes "primary development platform"} - linux-x86_64 {status supported tiers {runtime lib} notes ""} - linux-arm64 {status supported tiers {runtime lib} notes "aarch64; punkbin's existing arm kit predates the arm64 name and sits in linux-arm"} - linux-arm {status supported tiers {runtime lib} notes "32-bit arm"} - macosx {status supported tiers {runtime} notes "universal (multi-arch) macOS binaries - runtime tier keeps one folder"} - macosx-x86_64 {status supported tiers {lib} notes ""} - macosx-arm64 {status supported tiers {lib} notes "Apple silicon"} - freebsd-x86_64 {status supported tiers {runtime lib} notes ""} - freebsd-arm64 {status supported tiers {runtime lib} notes "no artifacts yet"} - msys-x86_64 {status dormant tiers {lib} notes "msys/cygwin-built tclsh runtimes; utility under review"} - openbsd-x86_64 {status recognized tiers {} notes ""} - netbsd-x86_64 {status recognized tiers {} notes ""} - dragonflybsd-x86_64 {status recognized tiers {} notes ""} + win32-x86_64 {status supported tiers {runtime lib} buildsuite supported notes "primary development platform (suite_tcl90)"} + linux-x86_64 {status supported tiers {runtime lib} buildsuite planned notes "G-105 first cross-target, WSL-verified"} + linux-arm64 {status supported tiers {runtime lib} buildsuite candidate notes "aarch64; punkbin's existing arm kit predates the arm64 name and sits in linux-arm"} + linux-arm {status supported tiers {runtime lib} buildsuite candidate notes "32-bit arm"} + macosx {status supported tiers {runtime} buildsuite candidate notes "universal (multi-arch) macOS binaries - runtime tier keeps one folder; zig darwin cross needs SDK work"} + macosx-x86_64 {status supported tiers {lib} buildsuite none notes "would follow a macosx runtime arc"} + macosx-arm64 {status supported tiers {lib} buildsuite none notes "Apple silicon; would follow a macosx runtime arc"} + freebsd-x86_64 {status supported tiers {runtime lib} buildsuite candidate notes ""} + freebsd-arm64 {status supported tiers {runtime lib} buildsuite candidate notes "no artifacts yet"} + msys-x86_64 {status dormant tiers {lib} buildsuite none notes "msys/cygwin-built tclsh runtimes; utility under review"} + openbsd-x86_64 {status recognized tiers {runtime} buildsuite none notes "hosted third-party runtimes possible"} + netbsd-x86_64 {status recognized tiers {runtime} buildsuite none notes "hosted third-party runtimes possible"} + dragonflybsd-x86_64 {status recognized tiers {runtime} buildsuite none notes "hosted third-party runtimes possible"} } namespace eval argdoc { @@ -90,11 +99,18 @@ namespace eval punk::platform { "Return the canonical punkshell platform-name records as a dict keyed by platform-dir name (e.g win32-x86_64). Each value is a dict with keys: - status supported|dormant|recognized - tiers which artifact-tree tiers use the name - (runtime = punkbin + bin/runtime folders, - lib = lib_tclX/vendorlib_tclX auto_path dirs) - notes free-text qualifiers + status supported|dormant|recognized + tiers which artifact-tree tiers use the name + (runtime = punkbin + bin/runtime folders, + lib = lib_tclX/vendorlib_tclX auto_path dirs) + buildsuite supported|planned|candidate|none - whether the + punkshell zig buildsuite system produces + runtimes for the platform. Deliberately a + separate axis from tiers: punkbin-structured + repos can host runtimes built by any mechanism, + so a platform can be runtime-tier hosted while + buildsuite=none. + notes free-text qualifiers These names are the contract for punkbin platform folders, bin/runtime//, lib_tclX/vendorlib_tclX platform dirs and the G-103 runtime-artifact metadata target field. diff --git a/src/modules/punk/platform-buildversion.txt b/src/modules/punk/platform-buildversion.txt index 4abe8a12..be3e43d5 100644 --- a/src/modules/punk/platform-buildversion.txt +++ b/src/modules/punk/platform-buildversion.txt @@ -1,4 +1,4 @@ 0.1.0 #First line must be a semantic version number #all other lines are ignored. -#0.1.0 - initial release (2026-07-22 platform-folder synchronization; G-105 groundwork): the canonical punkshell platform naming layer over Tcl's platform package - platforms (canonical records: status/tiers/notes), normalize (amd64->x86_64, aarch64->arm64, macos->macosx, macosx arm->arm64), local ?-tier lib|runtime? (runtime tier collapses macosx per-arch to the universal macosx runtime-store name). Canon consumed by: punkbin platform folders, bin/runtime//, lib_tclX/vendorlib_tclX platform dirs, G-103 artifact metadata targets, 'help platforms' topic. The boot machinery (punkboot::lib platform_generic snips in punk_main.tcl/project_main.tcl/make.tcl) carries an inline copy of the normalization mapping - keep in sync. +#0.1.0 - initial release (2026-07-22 platform-folder synchronization; G-105 groundwork): the canonical punkshell platform naming layer over Tcl's platform package - platforms (canonical records: status/tiers/buildsuite/notes; buildsuite = whether the punkshell zig buildsuites produce runtimes for the platform, deliberately a separate axis from the tiers a name organizes - punkbin-structured repos can host runtimes built by any mechanism, so runtime-tier hosting can coexist with buildsuite=none), normalize (amd64->x86_64, aarch64->arm64, macos->macosx, macosx arm->arm64), local ?-tier lib|runtime? (runtime tier collapses macosx per-arch to the universal macosx runtime-store name). Canon consumed by: punkbin platform folders, bin/runtime//, lib_tclX/vendorlib_tclX platform dirs, G-103 artifact metadata targets, 'help platforms' topic. The boot machinery (punkboot::lib platform_generic snips in punk_main.tcl/project_main.tcl/make.tcl) carries an inline copy of the normalization mapping - keep in sync.