jn
/
punkshell
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

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:™️: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
master
Julian Noble 2 weeks ago
parent
cae9f36d3e
commit
3a49aa4c48
8 changed files with 85 additions and 33 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 4
      CHANGELOG.md
  2. 9
      goals/G-105-buildsuite-cross-target.md
  3. 17
      goals/G-109-libunknown-manifest-multiname-tm.md
  4. 2
      punkproject.toml
  5. 30
      src/modules/punk-999999.0a1.0.tm
  6. 2
      src/modules/punk-buildversion.txt
  7. 52
      src/modules/punk/platform-999999.0a1.0.tm
  8. 2
      src/modules/punk/platform-buildversion.txt

4
CHANGELOG.md
Unescape View File

@ -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` Entries are newest-first; one bullet per notable change. See the root `AGENTS.md`
"Project Versioning" section for the bump policy. "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 ## [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). - 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).

9
goals/G-105-buildsuite-cross-target.md
Unescape View File

@ -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; (mapvfs mappings + purpose-names carry the platform axis) - acceptable now;
recommend revisiting when G-105 cross-wraps land (a mapvfs platform column per 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). 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.

17
goals/G-109-libunknown-manifest-multiname-tm.md
Unescape View File

@ -55,3 +55,20 @@ mount path - the 8.6 leg of acceptance), TIP 590 (lowercase naming), G-110
## Notes ## Notes
- 2026-07-21: drafted and approved (user: "approved - apply both"). - 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-<platform>/ siblings
or a byplatform/<platform>/ 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.

2
punkproject.toml
Unescape View File

@ -1,4 +1,4 @@
[project] [project]
name = "punkshell" name = "punkshell"
version = "0.18.0" version = "0.18.1"
license = "BSD-2-Clause" license = "BSD-2-Clause"

30
src/modules/punk-999999.0a1.0.tm
Unescape View File

@ -8990,16 +8990,19 @@ namespace eval punk {
"Canonical punkshell platform names."\ "Canonical punkshell platform names."\
-help\ -help\
"Show the canonical punkshell platform-dir names "Show the canonical punkshell platform-dir names
(punk::platform::platforms) with status and the artifact-tree (punk::platform::platforms) with status, the artifact-tree
tiers each name serves, marking the running interpreter's own tiers each name serves, and the buildsuite axis (whether the
platform. These names organize the punkbin artifact repo's punkshell zig buildsuites produce runtimes for the platform -
platform folders, bin/runtime/<platform>/ (punk-runtime separate from hosting: punkbin-structured repos can carry
fetch/list/use -platform), the lib_tclX / vendorlib_tclX runtimes built by any mechanism), marking the running
auto_path dirs wired by the boot, and the runtime-artifact interpreter's own platform. These names organize the punkbin
metadata target field. The raw Tcl platform-package identifiers artifact repo's platform folders, bin/runtime/<platform>/
are shown for comparison (punk::platform::normalize folds their (punk-runtime fetch/list/use -platform), the lib_tclX /
version-dependent aliases - amd64/aarch64/macos - into the vendorlib_tclX auto_path dirs wired by the boot, and the
canonical names)." 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 @values -min 0 -max 0
} }
proc platforms {context args} { proc platforms {context args} {
@ -9016,15 +9019,16 @@ namespace eval punk {
$t add_column -headers [list "Platform"] $t add_column -headers [list "Platform"]
$t add_column -headers [list "Status"] $t add_column -headers [list "Status"]
$t add_column -headers [list "Tiers"] $t add_column -headers [list "Tiers"]
$t add_column -headers [list "Buildsuite"]
$t add_column -headers [list "Notes"] $t add_column -headers [list "Notes"]
dict for {p pinfo} [punk::platform::platforms] { dict for {p pinfo} [punk::platform::platforms] {
set pshown $p set pshown $p
if {$p eq $local_lib || $p eq $local_runtime} { if {$p eq $local_lib || $p eq $local_runtime} {
set pshown "* $p" 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_column $c -minwidth [expr {[$t column_datawidth $c] + 2}]
} }
$t configure -title $title $t configure -title $title
@ -9036,6 +9040,8 @@ namespace eval punk {
append detail " runtime-tier $local_runtime" append detail " runtime-tier $local_runtime"
} }
append detail "\ntiers: runtime = punkbin + bin/runtime folders; lib = lib_tclX/vendorlib_tclX auto_path dirs" 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 { catch {
append detail "\nraw Tcl platform package ([package present platform]): generic [platform::generic] identify [platform::identify]" append detail "\nraw Tcl platform package ([package present platform]): generic [platform::generic] identify [platform::identify]"
} }

2
src/modules/punk-buildversion.txt
Unescape View File

@ -1,7 +1,7 @@
0.2.7 0.2.7
#First line must be a semantic version number #First line must be a semantic version number
#all other lines are ignored. #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: <level> (mitigated)' in subdued grey (term-grey foreground) instead of the level colour, followed by an indented 'mitigated: <text>' block when mitigation text is supplied. Unmitigated warnings render unchanged. #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: <level> (mitigated)' in subdued grey (term-grey foreground) instead of the level colour, followed by an indented 'mitigated: <text>' 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.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). #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).

52
src/modules/punk/platform-999999.0a1.0.tm
Unescape View File

@ -63,20 +63,29 @@ namespace eval punk::platform {
#tiers: which artifact-tree tiers use the name - #tiers: which artifact-tree tiers use the name -
# runtime = punkbin platform folders + bin/runtime/<platform>/ # runtime = punkbin platform folders + bin/runtime/<platform>/
# lib = lib_tclX/<platform> + vendorlib_tclX/<platform> auto_path dirs # lib = lib_tclX/<platform> + vendorlib_tclX/<platform> 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 { variable platforms {
win32-x86_64 {status supported tiers {runtime lib} notes "primary development platform"} win32-x86_64 {status supported tiers {runtime lib} buildsuite supported notes "primary development platform (suite_tcl90)"}
linux-x86_64 {status supported tiers {runtime lib} notes ""} 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} notes "aarch64; punkbin's existing arm kit predates the arm64 name and sits in linux-arm"} 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} notes "32-bit arm"} linux-arm {status supported tiers {runtime lib} buildsuite candidate notes "32-bit arm"}
macosx {status supported tiers {runtime} notes "universal (multi-arch) macOS binaries - runtime tier keeps one folder"} 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} notes ""} macosx-x86_64 {status supported tiers {lib} buildsuite none notes "would follow a macosx runtime arc"}
macosx-arm64 {status supported tiers {lib} notes "Apple silicon"} 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} notes ""} freebsd-x86_64 {status supported tiers {runtime lib} buildsuite candidate notes ""}
freebsd-arm64 {status supported tiers {runtime lib} notes "no artifacts yet"} freebsd-arm64 {status supported tiers {runtime lib} buildsuite candidate notes "no artifacts yet"}
msys-x86_64 {status dormant tiers {lib} notes "msys/cygwin-built tclsh runtimes; utility under review"} msys-x86_64 {status dormant tiers {lib} buildsuite none notes "msys/cygwin-built tclsh runtimes; utility under review"}
openbsd-x86_64 {status recognized tiers {} notes ""} openbsd-x86_64 {status recognized tiers {runtime} buildsuite none notes "hosted third-party runtimes possible"}
netbsd-x86_64 {status recognized tiers {} notes ""} netbsd-x86_64 {status recognized tiers {runtime} buildsuite none notes "hosted third-party runtimes possible"}
dragonflybsd-x86_64 {status recognized tiers {} notes ""} dragonflybsd-x86_64 {status recognized tiers {runtime} buildsuite none notes "hosted third-party runtimes possible"}
} }
namespace eval argdoc { namespace eval argdoc {
@ -90,11 +99,18 @@ namespace eval punk::platform {
"Return the canonical punkshell platform-name records as a dict "Return the canonical punkshell platform-name records as a dict
keyed by platform-dir name (e.g win32-x86_64). Each value is a keyed by platform-dir name (e.g win32-x86_64). Each value is a
dict with keys: dict with keys:
status supported|dormant|recognized status supported|dormant|recognized
tiers which artifact-tree tiers use the name tiers which artifact-tree tiers use the name
(runtime = punkbin + bin/runtime folders, (runtime = punkbin + bin/runtime folders,
lib = lib_tclX/vendorlib_tclX auto_path dirs) lib = lib_tclX/vendorlib_tclX auto_path dirs)
notes free-text qualifiers 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, These names are the contract for punkbin platform folders,
bin/runtime/<platform>/, lib_tclX/vendorlib_tclX platform bin/runtime/<platform>/, lib_tclX/vendorlib_tclX platform
dirs and the G-103 runtime-artifact metadata target field. dirs and the G-103 runtime-artifact metadata target field.

2
src/modules/punk/platform-buildversion.txt
Unescape View File

@ -1,4 +1,4 @@
0.1.0 0.1.0
#First line must be a semantic version number #First line must be a semantic version number
#all other lines are ignored. #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/<platform>/, 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/<platform>/, 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.

Write Preview
Loading…
Cancel
Save