jn
/
punkshell
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
864 Commits
1 Branch
1 Tag
147 MiB
 
 
 
 
 
 
Tree: d2e96dbe30
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'd2e96dbe30'
${ noResults }
punkshell/bin/AGENTS.md

6.4 KiB
Raw Blame History

bin/

Purpose

Built punk shell executables (kits with the punk boot layer), assorted build/experiment tooling, and plain runtime kits under runtime/. Executables here are build outputs - agents do not hand-edit binaries.

Generated polyglot .cmd scripts - never edit in place

The .cmd scripts here (e.g runtime.cmd) are punk MULTISHELL polyglots GENERATED by punk::mix::commandset::scriptwrap::multishell from scriptset sources under src/scriptapps/bin/ (the home for bin-deployed scriptsets, e.g runtime.* alongside getzig.*) or src/scriptapps/ itself (e.g tclargs.*, dtplite.*): payload scripts (<name>.ps1, <name>.bash, <name>.tcl, ...) plus a <name>_wrap.toml config, spliced into the punk.multishell.cmd template. The polyglot structure is deliberately fragile (mutual shell-hiding tricks, LF-only endings, cmd.exe's 512-byte label-scanner constraints) - a hand-edit can silently break one of the participating shells.

When asked to "fix bin/.cmd":

  1. Edit the payload/config sources under src/scriptapps/bin/ (never the output file).
  2. Re-wrap from the scriptset's folder: cd src/scriptapps/bin then punk::mix::commandset::scriptwrap::multishell <name> -askme 0 (output defaults to <projectroot>/bin; requires Thread + the punk::mix modules, e.g a punk shell or a tclsh with project module paths).
  3. The wrapper runs checkfile (the 512-byte label/boundary validator) automatically - heed ERROR output; "possibly bogus target" warnings are normal for polyglots. Payload growth can push a TEMPLATE label beyond the payloads (e.g :exit_multishell) across a 512-byte boundary: fix by resizing the byte-alignment spacer comment at the end of the affected payload (see the (512B spacer) comment in runtime.bash) and re-wrapping until checkfile is ERROR-free.
  4. Commit source AND regenerated output together: the scriptwrap test suite pins that a re-wrap of the runtime scriptset reproduces bin/runtime.cmd byte for byte (src/tests/modules/punk/mix/testsuites/scriptwrap/multishell.test scriptwrap_runtime_cmd_roundtrip_no_drift), so drift in either direction fails tests. bin/dtplite.cmd is pinned the same way (src/tests/shell/testsuites/binscripts/dtplite.test dtplite_cmd_roundtrip_no_drift).

dtplite (dtplite.cmd)

bin/dtplite.cmd wraps tcllib's dtplite doctools processor (payload src/scriptapps/dtplite.tcl, tclsh nextshell on all platforms). It exists so the punk repl's unknown-handler can resolve the bare dtplite command via PATH - dev doc.validate (punk::mix::commandset::doc) depends on it. The payload falls back to the project-vendored tcllib (src/vendorlib_tcl9/<arch>/tcllib*) when the invoking tclsh has no dtplite package installed.

Local Contracts

Launch package modes (built punk shells)

The first argument to a built punk shell may be a dash-delimited package mode composed of tokens from dev, os, src, internal (e.g. punksys src, punk902z dev-os). internal is the default and is always appended when absent. A first argument that is not a valid mode list is treated as a subcommand instead. Implementation: src/vfs/_config/punk_main.tcl (search all_package_modes).

src mode is the one that matters for verifying working-tree changes:

  • Discovers the project root from the executable's location (exe in bin/ -> parent directory), not from the cwd - it works from any working directory as long as the executable resides in the project's bin/.
  • Prepends src/modules, src/modules_tcl<N>, src/bootsupport/modules{,_tcl<N>} and src/vendormodules{,_tcl<N>} to the module path, sets package prefer latest so dev-numbered 999999.0a1.0 source modules beat kit-stamped snapshots on unversioned package require, and registers #modpod modules from src/modules (startup notice: src mode: registered N #modpod modules from .../src/modules).
  • Consequence: punksys src / punk902z src exercises current working-tree source with no kit rebuild; a plain launch (punksys) exercises the module snapshots baked into the kit at build time. package present <pkg> reporting 999999.0a1.0 (vs a release version like 0.7.1) tells you which set a session is running - runbooks with version expectations must state the intended launch mode.

Runtime fetch/selection (runtime.cmd)

bin/runtime.cmd {fetch|list|use|run} manages the plain runtimes under bin/runtime/<platform>/ (retrieved from the punkbin artifact repo with sha1 verification against its sha1sums.txt - both the powershell payload on windows and the bash payload on unix verify; a fetch whose checksum fails leaves only a .tmp). list -remote compares local runtimes against the server's sha1sums (Same version / UPDATE AVAILABLE / not-listed, plus remote-only entries; the bash payload falls back to a cached sha1sums.txt with a warning when the server is unreachable). The artifact server base url is overridable via PUNKBIN_URL (mirrors/testing) in both payloads. Which runtime run launches is the per-machine "active" selection in bin/runtime/<platform>/active.toml (constrained single-key toml active = "<name>", written by runtime.cmd use <name>, marked in list, VCS-ignored via the existing bin/* globs). Resolution order for run: PUNK_ACTIVE_RUNTIME env override, then active.toml, then a sole installed candidate - with multiple runtimes and no selection it errors listing candidates rather than guessing. The first fetch sets the active runtime only when none is recorded.

Interactive verification shells

  • Interactive console/repl verification should cover both Tcl generations - behaviour can differ materially (e.g. the Tcl 8.6 windows console channel driver vs the Tcl 9 rewrite). Use a Tcl 8.6-based punk shell (punksys.exe) and a current Tcl 9-based punk shell (named for the Tcl release it embeds, e.g. punk902z.exe at the time of writing - ask the user which is current rather than assuming). info patchlevel in-session confirms the runtime.
  • runtime/win32-x86_64/ holds plain tclkits/tclsh runtimes without the punk boot layer - use these for clean-environment probes isolating Tcl-level behaviour from punk (they may lack extensions such as twapi; add an external lib dir to auto_path when a probe needs one).

Work Guidance

Verification

None - build outputs; behaviour is verified via src/tests/ and interactive runbooks.

Child DOX Index

  • runtime/win32-x86_64/ - plain runtime kits (no child AGENTS.md needed; covered by this file's contracts)