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.
847 Commits
1 Branch
1 Tag
147 MiB
 
 
 
 
 
 
Tree: 49ec22a928
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '49ec22a928'
${ noResults }
punkshell/goals/G-024-mapvfs-toml.md

4.7 KiB
Raw Blame History

G-024 mapvfs.config converted to toml (tomlish-parsed) with succinct scheme declarations

Status: proposed Scope: src/runtime/mapvfs.config (replaced/deprecated), src/make.tcl (parsing), src/bootsupport/modules/tomlish-*.tm (parser dependency) Goal: the runtime-to-vfs-to-executable build mapping moves from the custom line format of src/runtime/mapvfs.config to a toml file parsed with the tomlish package - still supporting explicit per-executable mappings (runtime, vfs folder, output name, kit type) while also expressing generative schemes like the G-023 versioned naming in a single succinct declaration. Acceptance: a mapvfs toml file parsed via tomlish (no ad-hoc toml parsing) drives the build: every mapping currently active in mapvfs.config is expressible and at least one existing target builds identically from the toml; the G-023 versioned/dev/release-gated output scheme is declared in one entry that expands to its outputs without enumerating versions; malformed or unresolvable entries fail the build with a clear message naming the entry; the legacy .config format is either fully migrated (old parser removed) or explicitly deprecated with documented precedence between the two files.

Context

src/runtime/mapvfs.config maps runtime binaries and .vfs folders to named executables in a custom line format: one line per runtime, being the runtime filename followed by kit-configuration lists of 1-3 elements ({vfsfolder ?outputname? ?kittype?}, kittype in kit|zip|zipcat, - as runtime for runtime-less .kit builds, no-entry runtimes matching same-named .vfs folders implicitly). make.tcl parses it inline (~2795-2845). The format works but is idiosyncratic (comment/blank handling, positional defaults), is parsed ad hoc, and has no way to express a scheme - every output is one literal mapping, which conflicts with G-023 where output names derive from the project version at build time.

tomlish is the project's toml parser (vendored at src/vendormodules and src/bootsupport/modules - the bootsupport copy matters since make.tcl is build tooling), so the replacement format is toml parsed via tomlish, consistent with the G-014 direction of toml + tomlish for declared configuration.

Approach

  • A mapvfs toml file in src/runtime/ carrying two kinds of declarations:
    • Explicit mappings - the current capability, one entry per output: runtime, vfs folder, output name (defaulting from the vfs name), kit type. Everything active in mapvfs.config today must be expressible.
    • Scheme declarations - generative entries expanded by make.tcl, first consumer being the G-023 versioned scheme: one entry per Tcl generation declaring runtime + vfs + scheme=versioned (or similar) that expands to punkN---

      .exe, punkN-dev.exe and the release-gated punkN.exe without enumerating versions.

  • Validation with entry-level error reporting: a malformed or unresolvable entry (missing runtime file, missing vfs folder, unknown kit type/scheme) fails the build naming the offending entry - matching the current warnings but structured.
  • Legacy handling is a decision to record here: either full migration (convert the file, delete the old parser) or a deprecation window (toml wins when present, .config honoured with a deprecation warning). Full migration is preferred - the file is small and repo-internal - unless project_layouts templates complicate it (layout copies of make.tcl/mapvfs.config sync via G-012 territory; note in completion report, do not hand-sync layouts).

Alternatives considered

  • Keeping the custom line format and extending it with scheme syntax - rejected: doubles down on an ad-hoc parser exactly where the project is standardising on toml + tomlish.
  • Tcl-script config (source-able dict) - rejected for the same reason as in G-014: toml is the declared configuration format, editable without Tcl knowledge.

Notes

  • The commented-out historical entries in mapvfs.config (broken-runtime notes, test cases) are documentation of past pitfalls - carry the useful ones into toml comments or this file rather than losing them.
  • Related: G-023 (first scheme consumer), G-014 (toml+tomlish direction and the tomlish punk::args-documentation precondition - that precondition gates punk::config consumption; build-tooling use here can proceed with tomlish as-is), G-012 (layout template refresh, if layout copies of runtime config are affected).
  • G-037 (archived) named this file as the natural home for per-kit vendorlib payload declarations, and recorded that vendorlib and kit vfs trees have drifted in BOTH directions (vendorlib newer for udp, older for twapi) so any sync declaration needs explicit direction/authority semantics, not "copy newer over older" - see goals/archive/G-037-vendorlib-vfs-propagation.md.