punkshell/src/buildsuites

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.