Browse Source
G-023: builds produce punk8|9-<major>-<minor>-<patch>.exe from the punkproject.toml version plus punk8|9-dev.exe tracking the latest build; plain punk8|9.exe created initially and replaced only by an explicit release step. Disk growth tolerated for now; archival/deletion trigger recorded as a later question. G-024: src/runtime/mapvfs.config converted to toml parsed via tomlish - explicit runtime/vfs/name/kittype mappings preserved, plus generative scheme declarations so the G-023 versioned outputs are one succinct entry rather than per-version lines. Entry-level validation errors; full migration preferred over a deprecation window. G-025: build stamps project version, runtime binary and vfs folder into the kit; a version-report subcommand prints them machine-parseably, with the same-named punk-module command as the single implementation (the subcommand is a thin wrapper) so scripts get the report in-process. Report keeps build stamp, live runtime facts and source-tree version distinct: src-mode sessions report stamp and live versions separately when they differ; unstamped contexts (tclsh src/make.tcl shell, plain tclsh with punk modules) report stamp fields absent rather than fabricated. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.commaster
4 changed files with 232 additions and 0 deletions
@ -0,0 +1,67 @@ |
|||||||
|
# G-023 Version-named punk binaries per Tcl generation (versioned / dev / release-gated plain names) |
||||||
|
|
||||||
|
Status: proposed |
||||||
|
Scope: src/make.tcl, src/runtime/ (mapping config - see G-024), bin/ (build outputs) |
||||||
|
Acceptance: as in root GOALS.md index (canonical). |
||||||
|
|
||||||
|
## Context |
||||||
|
|
||||||
|
The project version is now tracked and change-driven-bumped in punkproject.toml |
||||||
|
(root AGENTS.md "Project Versioning"), so builds can be named after it. Today's |
||||||
|
build outputs are fixed names declared line-by-line in src/runtime/mapvfs.config |
||||||
|
(punksys, punk902z, ...) that encode the runtime generation informally and say |
||||||
|
nothing about the project version they contain - which build a given exe |
||||||
|
represents is unknowable without launching it (G-025 addresses the launching |
||||||
|
side; this goal addresses the naming side). |
||||||
|
|
||||||
|
Naming scheme: |
||||||
|
|
||||||
|
- `punk8-<major>-<minor>-<patch>.exe` / `punk9-<major>-<minor>-<patch>.exe` - |
||||||
|
produced as the version advances; a rebuild at an unchanged version refreshes |
||||||
|
that version's binaries in place. |
||||||
|
- `punk8-dev.exe` / `punk9-dev.exe` - always the latest build, refreshed every |
||||||
|
build. |
||||||
|
- `punk8.exe` / `punk9.exe` - created initially, then replaced only by an |
||||||
|
explicit release step when an actual release is tagged. A normal build never |
||||||
|
touches them. |
||||||
|
|
||||||
|
The `8`/`9` generation split matches the existing dual-generation verification |
||||||
|
practice (bin/AGENTS.md: a Tcl 8.6 punk shell and a current Tcl 9 punk shell). |
||||||
|
|
||||||
|
## Approach |
||||||
|
|
||||||
|
- Names derive from punkproject.toml at build time - no hand-maintained |
||||||
|
per-version config entries. The scheme is declared once, succinctly, in the |
||||||
|
G-024 toml mapping; the expansion to concrete output names happens in |
||||||
|
make.tcl. |
||||||
|
- The release step that updates the plain punk8.exe/punk9.exe names should be |
||||||
|
an explicit make.tcl action tied to release tagging, not a side effect of a |
||||||
|
normal build. Its precise trigger (fossil/git tag presence, or a manual |
||||||
|
subcommand) is an implementation decision to record here. |
||||||
|
- Existing specifically-named outputs (punksys, punk902z, ...) keep working via |
||||||
|
their explicit mappings (G-024 preserves them); the versioned scheme is |
||||||
|
additive. |
||||||
|
|
||||||
|
## Space and archival |
||||||
|
|
||||||
|
These binaries are large. Accumulating one pair per project version is |
||||||
|
accepted for now. Out of scope but recorded for later: a trigger mechanism for |
||||||
|
archival/deletion (e.g. keep-latest-N per generation, prune non-release |
||||||
|
versions older than a threshold, or move to an artifact store per G-006's |
||||||
|
binary-artifacts repository). Revisit when the accumulation actually bites. |
||||||
|
|
||||||
|
## Alternatives considered |
||||||
|
|
||||||
|
- Encoding the version only inside the kit (G-025) and keeping fixed exe names |
||||||
|
- rejected as insufficient alone: side-by-side versioned binaries are the |
||||||
|
point (running/comparing multiple versions without rebuilds). |
||||||
|
- Symlinks/hardlinks for -dev and plain names instead of copies - deferred to |
||||||
|
implementation: Windows link semantics for running executables are fiddly; |
||||||
|
copies are acceptable at current sizes. |
||||||
|
|
||||||
|
## Notes |
||||||
|
|
||||||
|
- Related: G-024 (scheme declared in toml mapping), G-025 (exe self-reports its |
||||||
|
version/provenance - the complement of name-encoded versioning once files |
||||||
|
are renamed/copied), G-006 (future artifact-store home for archived |
||||||
|
versions), G-018/G-019 (other points on the executable-flavour spectrum). |
||||||
@ -0,0 +1,65 @@ |
|||||||
|
# G-024 mapvfs.config converted to toml (tomlish-parsed) with succinct scheme declarations |
||||||
|
|
||||||
|
Status: proposed |
||||||
|
Scope: src/runtime/mapvfs.config (replaced/deprecated), src/make.tcl (parsing), src/bootsupport/modules/tomlish-*.tm (parser dependency) |
||||||
|
Acceptance: as in root GOALS.md index (canonical). |
||||||
|
|
||||||
|
## Context |
||||||
|
|
||||||
|
src/runtime/mapvfs.config maps runtime binaries and .vfs folders to named |
||||||
|
executables in a custom line format: one line per runtime, being the runtime |
||||||
|
filename followed by kit-configuration lists of 1-3 elements |
||||||
|
({vfsfolder ?outputname? ?kittype?}, kittype in kit|zip|zipcat, `-` as runtime |
||||||
|
for runtime-less .kit builds, no-entry runtimes matching same-named .vfs |
||||||
|
folders implicitly). make.tcl parses it inline (~2795-2845). The format works |
||||||
|
but is idiosyncratic (comment/blank handling, positional defaults), is parsed |
||||||
|
ad hoc, and has no way to express a *scheme* - every output is one literal |
||||||
|
mapping, which conflicts with G-023 where output names derive from the project |
||||||
|
version at build time. |
||||||
|
|
||||||
|
tomlish is the project's toml parser (vendored at src/vendormodules and |
||||||
|
src/bootsupport/modules - the bootsupport copy matters since make.tcl is build |
||||||
|
tooling), so the replacement format is toml parsed via tomlish, consistent |
||||||
|
with the G-014 direction of toml + tomlish for declared configuration. |
||||||
|
|
||||||
|
## Approach |
||||||
|
|
||||||
|
- A mapvfs toml file in src/runtime/ carrying two kinds of declarations: |
||||||
|
- **Explicit mappings** - the current capability, one entry per output: |
||||||
|
runtime, vfs folder, output name (defaulting from the vfs name), kit type. |
||||||
|
Everything active in mapvfs.config today must be expressible. |
||||||
|
- **Scheme declarations** - generative entries expanded by make.tcl, first |
||||||
|
consumer being the G-023 versioned scheme: one entry per Tcl generation |
||||||
|
declaring runtime + vfs + scheme=versioned (or similar) that expands to |
||||||
|
punkN-<M>-<m>-<p>.exe, punkN-dev.exe and the release-gated punkN.exe |
||||||
|
without enumerating versions. |
||||||
|
- Validation with entry-level error reporting: a malformed or unresolvable |
||||||
|
entry (missing runtime file, missing vfs folder, unknown kit type/scheme) |
||||||
|
fails the build naming the offending entry - matching the current warnings |
||||||
|
but structured. |
||||||
|
- Legacy handling is a decision to record here: either full migration (convert |
||||||
|
the file, delete the old parser) or a deprecation window (toml wins when |
||||||
|
present, .config honoured with a deprecation warning). Full migration is |
||||||
|
preferred - the file is small and repo-internal - unless project_layouts |
||||||
|
templates complicate it (layout copies of make.tcl/mapvfs.config sync via |
||||||
|
G-012 territory; note in completion report, do not hand-sync layouts). |
||||||
|
|
||||||
|
## Alternatives considered |
||||||
|
|
||||||
|
- Keeping the custom line format and extending it with scheme syntax - |
||||||
|
rejected: doubles down on an ad-hoc parser exactly where the project is |
||||||
|
standardising on toml + tomlish. |
||||||
|
- Tcl-script config (source-able dict) - rejected for the same reason as in |
||||||
|
G-014: toml is the declared configuration format, editable without Tcl |
||||||
|
knowledge. |
||||||
|
|
||||||
|
## Notes |
||||||
|
|
||||||
|
- The commented-out historical entries in mapvfs.config (broken-runtime notes, |
||||||
|
test cases) are documentation of past pitfalls - carry the useful ones into |
||||||
|
toml comments or this file rather than losing them. |
||||||
|
- Related: G-023 (first scheme consumer), G-014 (toml+tomlish direction and |
||||||
|
the tomlish punk::args-documentation precondition - that precondition gates |
||||||
|
punk::config consumption; build-tooling use here can proceed with tomlish |
||||||
|
as-is), G-012 (layout template refresh, if layout copies of runtime config |
||||||
|
are affected). |
||||||
@ -0,0 +1,82 @@ |
|||||||
|
# G-025 Punk executables self-report project version and build provenance |
||||||
|
|
||||||
|
Status: proposed |
||||||
|
Scope: src/vfs/_config/punk_main.tcl (subcommand dispatch), src/make.tcl (stamping build info into the vfs), src/vfs/ (stamp payload location), src/modules/punk/ (in-shell command - the single implementation) |
||||||
|
Acceptance: as in root GOALS.md index (canonical). |
||||||
|
|
||||||
|
## Context |
||||||
|
|
||||||
|
With G-023 producing version-named binaries, an executable's name encodes its |
||||||
|
version - but names are mutable (copies, renames, the -dev and release-gated |
||||||
|
plain names) and say nothing about the runtime binary or vfs folder the build |
||||||
|
consumed. The executable should answer for itself from embedded data: a |
||||||
|
version-report subcommand at the launch layer, and the same-named command in |
||||||
|
the punk module for scripts already running inside a punk shell. |
||||||
|
|
||||||
|
The in-shell command is not merely an optimization over exec'ing out. In a |
||||||
|
tclsh-hosted punk shell (`tclsh src/make.tcl shell` loads punk::repl directly |
||||||
|
into the host tclsh - make.tcl ~1913) there is no punk executable to exec: |
||||||
|
`info nameofexecutable` is the external tclsh, and invoking it with the |
||||||
|
subcommand would be meaningless. The in-process command is the only correct |
||||||
|
path there - hence the module command is the single implementation and the |
||||||
|
exe subcommand is a thin dispatch wrapper over it (which is also what |
||||||
|
guarantees the two surfaces report identically). |
||||||
|
|
||||||
|
## Report semantics: three distinct notions |
||||||
|
|
||||||
|
Only in a plainly-launched stamped kit do these coincide; the report must keep |
||||||
|
them distinct and never fabricate: |
||||||
|
|
||||||
|
1. **Build stamp** - project version, runtime binary name, vfs folder name, |
||||||
|
fixed at kit assembly by make.tcl. Absent in unstamped contexts. |
||||||
|
2. **Live runtime facts** - actual `info nameofexecutable`, patchlevel. |
||||||
|
Always available. |
||||||
|
3. **Source-tree project version** - punkproject.toml, available when running |
||||||
|
from a source tree regardless of stamping. |
||||||
|
|
||||||
|
Edge cases driving the acceptance clauses: |
||||||
|
|
||||||
|
- `tclsh src/make.tcl shell`: no stamp. Stamp fields reported explicitly |
||||||
|
absent; live facts show the real host tclsh; the source-tree version may be |
||||||
|
reported but flagged as live-from-punkproject.toml, not as a stamp. |
||||||
|
- Kit launched in `src` mode (`punk902z src`): a stamp exists, but the running |
||||||
|
code is working-tree dev modules whose punkproject.toml may be ahead of the |
||||||
|
stamped version. Reporting only the stamp misstates what is running; only |
||||||
|
the live version misstates provenance - report both, distinctly labelled, |
||||||
|
when they differ. |
||||||
|
- Plain tclsh with installed punk modules and no source tree: no stamp, no |
||||||
|
punkproject.toml - live facts only. |
||||||
|
- Renamed/copied executables: the report comes from the stamp, so it stays |
||||||
|
correct whatever the file is called. |
||||||
|
- Pre-stamping kits: the subcommand/command fails gracefully with a clear |
||||||
|
message. |
||||||
|
|
||||||
|
## Approach notes |
||||||
|
|
||||||
|
- The command must work from the code interp (where scripts run), not just the |
||||||
|
repl thread - trivial for static stamp data, but stated so the G-007 |
||||||
|
location-transparency expectation is met. |
||||||
|
- The subcommand output must be machine-parseable, exit 0, and emit nothing |
||||||
|
else on stdout/stderr - usable through G-015 piped calls and by exec-style |
||||||
|
callers. |
||||||
|
- Naming (e.g. `buildinfo`) is an implementation decision: the in-shell |
||||||
|
command name must match the subcommand name and not collide with existing |
||||||
|
repl commands. |
||||||
|
- Stamp location within the vfs payload is an implementation decision to |
||||||
|
record here (candidates: a dedicated stamp file under the vfs _config, or |
||||||
|
fields merged into an existing boot config file). |
||||||
|
|
||||||
|
## Alternatives considered |
||||||
|
|
||||||
|
- In-shell command exec'ing its own executable with the subcommand - rejected: |
||||||
|
wrong in tclsh-hosted shells (no punk executable to call), needless process |
||||||
|
spawn elsewhere, and two code paths that can drift. |
||||||
|
- Reporting only the stamped version and ignoring live/source-tree context - |
||||||
|
rejected: actively misleading in `src`-mode sessions, which are the primary |
||||||
|
working-tree verification workflow (bin/AGENTS.md). |
||||||
|
|
||||||
|
## Notes |
||||||
|
|
||||||
|
- Related: G-023 (version-named binaries this complements), G-024 (build |
||||||
|
mapping that will drive stamping inputs), G-015 (piped invocation of the |
||||||
|
subcommand), G-014 (punkproject.toml reading may share tomlish plumbing). |
||||||
Loading…
Reference in new issue