4.2 KiB
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) Goal: project builds produce version-named punk executables for tcl 8.6 and tcl 9 as the project version advances - punk8---.exe / punk9---.exe per version, punk8-dev.exe / punk9-dev.exe tracking the latest build, and plain punk8.exe / punk9.exe created initially then replaced only when an actual release is tagged - tolerating the disk growth for now. Acceptance: a project build at the current punkproject.toml version produces punk8---
.exe and punk9---
.exe (names derived from the version, not hand-maintained) plus punk8-dev.exe / punk9-dev.exe updated to that same build; rebuilding at an unchanged version refreshes that version's binaries and -dev without touching other versions' outputs; plain punk8.exe / punk9.exe exist and are replaced only by an explicit release step - a normal build never overwrites them; the scheme is declared succinctly via the G-024 toml mapping (no per-version config edits); archival/deletion of accumulated versioned binaries is out of scope with the trigger question recorded in the detail file.
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).