diff --git a/AGENTS.md b/AGENTS.md index a05e729..d575457 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,6 +28,11 @@ This artifact repository is specific to the punkshell project. (e.g. zig archives). `src/` holds maintenance scripts for this repository itself. Platform folder names follow the punkshell canonical platform names (punk::platform module / `help platforms` in the punk shell). +- `lib/` is the LIBRARY artifact tier (shellspy G-138), distinct from the runtime + platform folders: `lib/allplatforms/` for platform-neutral packages (pure-Tcl), + `lib//` per platform for binary packages, each target subfolder with its + own `sha1sums.txt`. `lib/` never appears in `platforms.txt` (runtime folders + only). See "Library artifacts - lib tier (schema v2)" below. - `platforms.txt` at the repo root lists the platform folders this repo serves (one name per line; `#` comments and blanks ignored) - the discovery manifest for raw-file consumers that have no directory-listing capability @@ -126,6 +131,54 @@ it. Emission/verification tooling lives in shellspy `src/buildsuites/suite_tcl90 derives its identity fields from the embedded copy, `tools/family_check.tcl` embedded-record probe). +## Library artifacts - lib tier (schema v2) + +The `lib/` tier (shellspy G-138) carries suite-built LIBRARY packages as immutable +`-r` zips of installed-shape package folders: `lib/allplatforms/` for +platform-neutral packages (pure-Tcl tcllib), `lib//` for per-platform +binary packages (tcllibc critcl accelerators). Consumption (shellspy G-139) +materializes them into the punkshell repo's untracked `bin/packages//` +input tier. + +- Naming: `--r.zip` (e.g. + `tcllib2.0-tcl9-r1.zip`, `tcllibc-tcl8-r1.zip`). The GENERATION tag is part of + artifact identity, not decoration: both Tcl generations install + identically-named package folders (tcllib2.0, tcllibc) with genuinely + different bytes (binary packages link per-generation; installer output + differs). `-r` revisions are immutable exactly as in the runtime tier. +- Each zip contains the package folder in installed pkgIndex.tcl shape plus the + EMBEDDED record at `/punkbin-artifact.toml` (package root, beside + pkgIndex.tcl - inert to package loading), written before zipping + (embed-then-hash: `sha1`/`size`/`built` remain SIDECAR-ONLY). Sidecar + `.toml` + per-target `sha1sums.txt` are the integrity + authority, exactly as for runtimes. +- Record shape (`schema = 2`): the v1 identity set plus, in `[artifact]`, + `class = "library"` with `package`/`package_version`/`folder`/`tcl_generation` + (replacing the runtime tier's variant/working_name); a `[library]` table with + `driving_tcl_patchlevel` (patchlevel of the suite-built shell that ran the + installer/critcl - the generation witness, not a runtime requirement); and in + `[provenance]`, `class = "suite-built"` (schema-v2 build-origin class: + suite-built | third-party | local - the shellspy G-123 lineage), the source + checkout uuids (`tcllib_checkout`, `critcl_checkout`) and `critcl` (version + declared by the package's own critcl teapot.txt, accelerator packages only). +- Schema v2 is a SUPERSET of v1: line-based v1 consumers ignore the new fields + by construction. Ordering caveat for whole-text single-key scanners: + `[artifact] class` is the FIRST `class =` line in every record by + construction; a consumer that wants `[provenance] class` must parse tables. +- Determinism/publish discipline: zips are punkzip-assembled (sorted members, + staged mtimes synced) so re-emission over an unchanged install is + byte-identical - but the dlls INSIDE are not bit-reproducible across zig + rebuilds, so revisions bump only on deliberate publish, never per rebuild. +- md5c is deliberately NOT published: tcllib's md5 accelerator resolution + prefers tcllibc (modules/md5/md5x.tcl), which bundles the md5 accelerator. +- Emission tooling: shellspy `src/buildsuites/suite_tcl90` + `suite_tcl86` + `tools/library_artifacts.tcl` (`library-artifacts` step in both recipes; + suite READMEs document the mechanism). Publication remains a deliberate user + step: copy `out/library/punkbin/lib/*` into `lib/`, `git add`, run + `tclsh src/build_sha1sums.tcl` (it processes each `lib//` subfolder), + commit. Minisign posture unchanged: sha1sums are transport integrity; + per-artifact `.minisig` sidecars remain the anticipated verification layer. + ## Work Guidance - Adding a runtime: copy it into the platform folder, `git add` it, run diff --git a/README.md b/README.md index 63490c7..88a9c24 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,12 @@ Platforms: win32-x86_64 (zipfs and tclkit based) linux-x86_64 (tclkit based) +The lib/ folder is a separate LIBRARY artifact tier (not a platform folder): +suite-built Tcl library packages (tcllib, tcllibc) as versioned zips - +lib/allplatforms for pure-tcl packages, lib/ for binary packages, +named --r.zip with embedded provenance records and toml +sidecars (see AGENTS.md "Library artifacts - lib tier"). + Builtin packages: Thread, tcllibc, vfs, vlerq vfs and vlerq are included even in zipfs runtimes to allow them to call .kit files such as sdx.kit and to extract and build metakit based starkit executables as well as zipfs based executables. diff --git a/src/build_sha1sums.tcl b/src/build_sha1sums.tcl index 2fe0111..c1b4055 100644 --- a/src/build_sha1sums.tcl +++ b/src/build_sha1sums.tcl @@ -107,6 +107,7 @@ foreach dirtail $rootfolders { set level 0 set indent "" if {$dirtail in $known_skip_tails} {continue} + if {$dirtail eq "lib"} {continue} ;#the G-138 library tier - processed below, never a platform folder set firstword [lindex [split $dirtail -] 0] if {$firstword ni $os_list} { puts stderr "skipping unrecognised folder: $dirtail" @@ -117,6 +118,25 @@ foreach dirtail $rootfolders { do_sha1_in_folder $runtimefolder 0 } +#lib tier (G-138): library package artifacts under lib// where +#is 'allplatforms' (platform-neutral packages) or a canonical platform-dir name +#(per-platform binary packages). Each target subfolder carries its own +#sha1sums.txt; lib/ itself holds no artifacts and is deliberately NOT listed in +#platforms.txt (that file enumerates RUNTIME platform folders only). +set libbase [file join $basedir lib] +if {[file isdirectory $libbase]} { + foreach sftail [lsort [glob -nocomplain -dir $libbase -type d -tail *]] { + if {[string match .* $sftail]} {continue} + if {$sftail ne "allplatforms"} { + set firstword [lindex [split $sftail -] 0] + if {$firstword ni $os_list} { + puts stderr "${Y}WARNING: lib/$sftail is neither 'allplatforms' nor a platform-named target folder$RST" + } + } + do_sha1_in_folder [file join $libbase $sftail] 1 + } +} + #platforms.txt - the machine-readable list of platform folders this repo serves, #at the repo root so raw-file consumers (punk-runtime 'platforms -remote', and #third-party mirrors using the same layout) can discover platforms without a