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