Browse Source
buildsuite group added as a declared passthrough (punk::args + fallback paths): list discovers suites (dirs carrying suite.tcl; _build excluded), info renders the manifest-derived detail, build forwards driver args untouched streaming output and exiting with the driver's status (punk-kit-hosted runs launch the driver via the kit's script subcommand, selected by the G-058 marker). Self-description = manifest option: sources.config gains description/product/ doc/zigpin records parsed by both suite.tcl (strict; pinned-zig default now reads zigpin - one source of truth) and make.tcl (tolerant). suite_tcl90 seeded with its records. Copied trees appear automatically (verified with a throwaway copy). Contract documented in new src/buildsuites/README.md + AGENTS.md, indexed from src/AGENTS.md. CHANGELOG extended under 0.23.0. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.commaster
8 changed files with 440 additions and 27 deletions
@ -0,0 +1,42 @@ |
|||||||
|
# src/buildsuites - Buildsuites (zig runtime factory) |
||||||
|
|
||||||
|
## Purpose |
||||||
|
|
||||||
|
Suites that build Tcl runtimes and binary companions from external upstream |
||||||
|
sources using the pinned zig toolchain (zig-only build policy). Arm's-length |
||||||
|
from the project build/bake stages: inputs are upstream checkouts/pins, not |
||||||
|
this project's `src/` tree. |
||||||
|
|
||||||
|
## Ownership |
||||||
|
|
||||||
|
- Suite trees (`suite_tcl90/`, future `suite_tcl86/` etc) are agent-editable |
||||||
|
under user-directed goal work (the G-096/G-099 arcs). |
||||||
|
- `_build/` is a VCS-ignored build area - never commit from it; each suite |
||||||
|
stages into `_build/<suitename>`. |
||||||
|
|
||||||
|
## Local Contracts |
||||||
|
|
||||||
|
- The suite self-description contract (what makes a directory a suite, the |
||||||
|
`sources.config` record grammar incl. description/product/doc/zigpin, the |
||||||
|
copy-and-tweak guarantee) is documented in `README.md` here - keep it and |
||||||
|
the `make.tcl buildsuite` surface in step. |
||||||
|
- `sources.config` is parsed, never executed - by both the suite driver and |
||||||
|
`make.tcl buildsuite list/info`. Grammar changes must land in both parsers |
||||||
|
(suite.tcl strict, make.tcl tolerant) plus `README.md`. |
||||||
|
- Fossil clones live in the machine-level store (`PUNK_FOSSIL_STORE`, default |
||||||
|
`~/.punkshell/fossils`) - outside `_build`-class deletable dirs. |
||||||
|
- Suite drivers must keep working when invoked directly (`tclsh suite.tcl ...`) |
||||||
|
AND via `make.tcl buildsuite build <name>` (which forwards args untouched). |
||||||
|
|
||||||
|
## Verification |
||||||
|
|
||||||
|
- `tclsh src/make.tcl buildsuite list` shows every suite with its description. |
||||||
|
- `tclsh src/make.tcl buildsuite info <name>` renders the manifest-derived |
||||||
|
detail for the touched suite. |
||||||
|
- Suite pipelines verify per their own README/goal records (test gates vs |
||||||
|
tracked expected_test_failures baselines). |
||||||
|
|
||||||
|
## Child DOX Index |
||||||
|
|
||||||
|
- `suite_tcl90/` - Tcl 9.0 suite (its README.md carries lineage/detail; no |
||||||
|
child AGENTS.md yet) |
||||||
@ -0,0 +1,70 @@ |
|||||||
|
# src/buildsuites - zig-built runtime factory |
||||||
|
|
||||||
|
Buildsuites build Tcl runtimes (and their binary companions) from external |
||||||
|
sources with the pinned zig toolchain. This is an arm's-length subsystem: it |
||||||
|
consumes upstream Tcl/Tk/extension sources, not this project's `src/` tree, |
||||||
|
and its outputs are runtime executables and artifact families - distinct from |
||||||
|
the project build/bake stages driven by the rest of `make.tcl`. |
||||||
|
|
||||||
|
## Layout |
||||||
|
|
||||||
|
- `suite_tcl90/` - the Tcl 9.0 suite (see its README for lineage and detail) |
||||||
|
- `_build/` - VCS-ignored build area; each suite stages into `_build/<suitename>` |
||||||
|
- other directories without a `suite.tcl` driver are not suites (e.g sample |
||||||
|
material) and are ignored by discovery |
||||||
|
|
||||||
|
## The make.tcl surface (G-104) |
||||||
|
|
||||||
|
Run from the projectroot: |
||||||
|
|
||||||
|
tclsh src/make.tcl buildsuite list |
||||||
|
tclsh src/make.tcl buildsuite info <suitename> |
||||||
|
tclsh src/make.tcl buildsuite build <suitename> ?driver-args ...? |
||||||
|
|
||||||
|
`list` discovers the suites and their one-line descriptions. `info` shows a |
||||||
|
suite's configured detail: description, source records (url/ref/pin), the |
||||||
|
pinned zig and whether it is present, products, and doc pointers. `build` |
||||||
|
runs the suite's driver (`suite.tcl build`) forwarding the given args |
||||||
|
untouched (e.g `-tclbranch`, `-refresh`, `-steps`), streams its output, and |
||||||
|
exits with the driver's status. The surface works under a plain tclsh and |
||||||
|
under punk kit executables. |
||||||
|
|
||||||
|
## Suite self-description contract |
||||||
|
|
||||||
|
A directory under `src/buildsuites` IS a suite when it carries a `suite.tcl` |
||||||
|
driver. Its `sources.config` is the suite's manifest - parsed as plain line |
||||||
|
records, never executed - read by BOTH the driver and `make.tcl buildsuite |
||||||
|
list/info`. Record grammar (whitespace-separated; `#` comments and blanks |
||||||
|
ignored): |
||||||
|
|
||||||
|
source <name> <kind> <url> <ref> <dir> source-pull declarations (fossil|git) |
||||||
|
description <text...> one line - the suite's list/info one-liner |
||||||
|
product <text...> repeatable - what a full build produces |
||||||
|
doc <relpath> repeatable - suite-relative doc pointers |
||||||
|
zigpin <relpath> projectroot-relative pinned zig executable |
||||||
|
|
||||||
|
Because discovery is a directory scan and description/info are answered by the |
||||||
|
suite's own manifest, a copied tree (the copy-and-tweak retargeting workflow - |
||||||
|
copy `suite_tcl90/` to `src/buildsuites/<yourname>/`, edit `sources.config`) |
||||||
|
appears in `list`/`info` automatically and stages into its own |
||||||
|
`_build/<yourname>` - no `make.tcl` edits, ever. A new or forked suite |
||||||
|
satisfies the contract by construction: keep `suite.tcl` + `sources.config` |
||||||
|
and edit the description/product records to tell the truth about your suite. |
||||||
|
|
||||||
|
The `zigpin` record is the single source of truth for the suite's pinned zig: |
||||||
|
`suite.tcl` resolves its default zig from it (precedence: `-zig` option > |
||||||
|
`PUNK_ZIG` env > the pin > `zig` on PATH) and `info` reports it with presence |
||||||
|
state (`bin/punk-getzig.cmd` fetches pinned zig versions). |
||||||
|
|
||||||
|
## Flows |
||||||
|
|
||||||
|
Each suite offers two equivalent flows (G-102): |
||||||
|
|
||||||
|
- FOSSIL DEV FLOW: `suite.tcl build|test|clean` - live checkouts per |
||||||
|
`sources.config` refs (branches may float), staged from the hermetic clone |
||||||
|
store (`PUNK_FOSSIL_STORE`, default `~/.punkshell/fossils`). |
||||||
|
- NO-TCLSH FLOW: `zig build stage|bootstrap` from the suite directory - |
||||||
|
content-hashed per-checkin pins from `build.zig.zon`. |
||||||
|
|
||||||
|
Both delegate the pipeline (configure, compile, install, smoke, test gates) |
||||||
|
to the suite's zig recipe steps. |
||||||
Loading…
Reference in new issue