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.
892 Commits
1 Branch
1 Tag
191 MiB
 
 
 
 
 
 
Tree: f9046dc191
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'f9046dc191'
${ noResults }
punkshell/src/project_layouts/README.md

3.1 KiB
Raw Blame History

project_layouts information

This folder is the payload store for project layouts: the directory trees that dev project.new (punk::mix::commandset::project::new) copies to create a new project.

Discovery: the punk.templates capability

Layouts in this store do not show as available unless referenced by a layout ref file found via the punk.templates capability (handler: punk::cap::handlers::templates; principal provider: punk::mix::templates).

Providers register template base folders with a pathtype. Base folders are merged in priority order (lowest to highest):

module < shellproject < currentproject < absolute < adhoc

Within the shellproject/currentproject multivendor trees (src/decktemplates), vendor/ folders are added before vendor/_project, and custom/ levels override vendor/ levels. When the same visible name is produced by more than one ref, the highest-priority one keeps the bare name and later ones are suffixed #2, #3, ...

Layout refs

A layout ref is a zero-byte file in a layout_refs/ folder under a template base (e.g. src/decktemplates/vendor/punk/layout_refs/, or a module-shipped templates/layout_refs/). The entire meaning is in the filename:

<alias>@<segment>+<segment>+...  .ref
  • The text before the first @ is the alias - the layout's nominal name. If the alias is empty the last + separated segment is used as the name.
  • The text after the first @ is a + separated path relative to /src/project_layouts identifying the layout folder. Segments after the first @ may themselves contain @ (derived-layout folder names such as othersample@sample-0.1).
  • The visible layout name is prefixed with the vendor folder name and a dot unless the vendor is the pseudo-vendor _project (e.g. project@vendor+punk+project-0.1.ref in a vendor/punk/layout_refs folder presents as layout name "punk.project").
  • Only filenames matching @vendor+.ref or @custom+.ref are recognised; files named ignore* are skipped.

The ref indirection exists to break recursion: layout payloads may embed module trees (including the punk::mix::templates module itself), so modules ship only small ref files while the layout payloads live once, here, outside any module.

Store structure

src/project_layouts/{vendor,custom}/{<vendorname>,_project}/<layoutfolder>
  • vendor/ trees should not be customised directly; place overrides under custom/. The pseudo-vendor _project holds project-local staging copies.
  • Overlay semantics (custom-over-vendor merging, .anti deletion markers, newname@base derived layouts, _project staging) are documented design - see custom/punk/sample-0.1/extra.txt - but are NOT yet implemented: project.new currently copies exactly one resolved layout folder.

Goal G-087 (goals/G-087-thin-project-layouts.md) tracks implementing the overlay merge, migrating refs to fauxlink files, and restructuring this store to thin layouts whose heavy infrastructure is injected at generation time (retiring the embedded module-tree snapshots currently stored here).