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.
761 Commits
1 Branch
1 Tag
147 MiB
 
 
 
 
 
 
Tree: 72d7fa80b2
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '72d7fa80b2'
${ noResults }
punkshell/goals/G-057-kit-icon-embedding.md

4.2 KiB
Raw Blame History

G-057 Windows kit builds embed a configurable icon (twapi resource replacement, per-vfs override)

Status: proposed Scope: src/make.tcl (kit/zipkit wrap steps), src/runtime/punk1.ico (project default, existing), src/vfs/*.vfs (override placement convention), src/runtime/mapvfs.config (only if an explicit config element is the chosen override mechanism), TEMP_REFERENCE/tcl-sfe (read-only reference), helper proc location decided in the work (make.tcl inline vs punk::mix lib) Acceptance: see GOALS.md index entry (canonical).

Context

Built punk kit executables currently carry whatever icon resource their runtime stub shipped with. The project icon src/runtime/punk1.ico exists and is COPIED into vfs trees (a tclkit-era convention), but nothing embeds it into the produced executable's Windows resources - so all kits look like their runtime in Explorer and the taskbar.

The reference mechanism is tcl-sfe (TEMP_REFERENCE/tcl-sfe, read-only), written by twapi author and Tcl core member Ashok P. Nadkarni: library/sfe-0.2.tm method replaceIcon / ReplaceIconInStub replaces RT_ICON (type 3) and the icon group (RT_GROUP_ICON, type 14) via twapi::extract_resources / twapi::begin_resource_update / twapi::delete_resource / twapi::update_resource / twapi::end_resource_update, building the group entry from the .ico file's own image directory.

Approach

  • Hook the icon step into make.tcl's kit wrap processing (driven by src/runtime/mapvfs.config), operating on the BUILD COPY of the runtime stub - never on the originals under src/runtime.
  • Payload integrity is the critical ordering constraint: a Windows resource update rewrites the PE image and corrupts any already-appended vfs payload. Either icon the stub copy BEFORE appending the zip/metakit payload, or use the sfe approach of splitting payload off, updating resources, and reattaching (sfe-0.2.tm does the split/update/reattach dance for exactly this reason). Chosen ordering to be recorded here.
  • Default icon: src/runtime/punk1.ico. Per-kit override supplied by the kit's .vfs. IMPORTANT wrinkle for the override convention: _vfscommon.vfs already merges a punk1.ico into every built vfs tree, so override detection must consult the kit's own CUSTOM .vfs folder (pre-merge, under src/vfs/) - or use an explicit mapvfs.config element - otherwise every kit would appear to "override" with the same common file. Chosen convention to be recorded here.
  • Graceful degradation: twapi unavailable, or non-Windows build, skips the icon step with an actionable notice; the build otherwise proceeds unchanged (per the src/AGENTS.md optional-extension guidance).
  • Idempotence: re-running a wrap on an already-processed build copy must converge (sfe deletes existing icon/group resources before writing - follow that).

Follow-on candidate goal (flagged, not yet a GOALS.md entry)

Version-information resource stamping (RT_VERSION, type 16) - sfe-0.2.tm already demonstrates the resource construction (BuildVersionResource, string tables, delete-then-write). Requirements sketch agreed 2026-07-10:

  • Copyright: defaults to the copyright already present in the INPUT kit runtime executable's version resource (carry it over - the runtime authors' copyright is not ours to silently drop), while being easily configurable - initially from punkproject.toml and/or per-vfs config.
  • Product Name: should indicate the core Tcl version of the runtime by default (e.g. carrying the Tcl major.minor the kit embeds), similarly configurable via punkproject.toml / per-vfs config.
  • Other fields (FileVersion/ProductVersion from the project version, FileDescription etc.) to be settled when the goal is drafted.
  • Config surface should anticipate the toml direction already agreed for build configs (punkproject.toml now; buildsuites toml era later).

Notes

  • tclsfe-x64.exe is already one of our mapped runtimes (mapvfs.config) - the same author's stub and the reference mechanism, so it makes a good first test subject alongside a tclkit-style runtime.
  • Resource inspection for acceptance: twapi::extract_resources on the built exe (compare icon group/images against the source .ico), not visual inspection.
  • Linux/other-platform kit outputs have no PE resources - explicitly out of scope; the skip path covers them.