x-lang

← Index

x/tool/pin

Class Pin

%pin-manifest-name

Member: data carried by a Pin instance.

%pin-visited-cell

Member: data carried by a Pin instance.

%pin-out-cell

Member: data carried by a Pin instance.

%pin-own-roots-cell

Member: data carried by a Pin instance.

%pin-lock-name

Member: data carried by a Pin instance.

%pin-platform-heads

Member: data carried by a Pin instance.

(Pin %pin-lock-header-for dest)

%pin-release-base

Member: data carried by a Pin instance.

%pin-release-name

Member: data carried by a Pin instance.

(Pin %pin-bad what)

(Pin %pin-forms text)

(Pin %pin-root form dir)

(Pin %pin-boot form)

(Pin %pin-src form)

(Pin %pin-allow-skew form)

(Pin %pin-engine form)

(Pin %pin-interpret forms dir)

(Pin %pin-manifest-arg head forms dir)

(Pin %pin-manifest-args head forms dir)

(Pin %pin-own-src? src)

(Pin %pin-manifest-raw head forms)

(Pin %pin-manifest-forms dir)

(Pin %pin-arm! roots)

(Pin %pin-path-norm p)

(Pin %pin-push! cell v)

(Pin %pin-take-rel dirs tail)

(Pin %pin-out-has? rel)

(Pin %pin-closure-of name)

(Pin %pin-mkdirs dir)

(Pin %pin-copy! dest entry)

(Pin %pin-rels entries)

(Pin %pin-copy-all! dest lst)

(Pin %pin-digest path)

(Pin %pin-lock-parse forms)

(Pin %pin-lock-parse-seeds forms)

(Pin %pin-lock-path dest)

(Pin %pin-lock-forms dest)

(Pin %pin-str->sym s)

(Pin %pin-platform-forms forms)

(Pin %pin-lock-read dest)

(Pin %pin-lock-read-seeds dest)

(Pin %pin-lock-render entries)

(Pin %pin-seed-render seeds)

(Pin %pin-seed-put seeds name rels)

(Pin %pin-append-new acc lst)

(Pin %pin-seed-claims seeds acc)

(Pin %pin-not-in rels lst)

(Pin %pin-lock-entries dest rels)

(Pin %pin-lock-relock! dest seed rels)

(Pin %pin-report-dropped dest dropped)

(Pin %pin-tree-files root)

(Pin %pin-verify-fails dest lock)

(Pin %pin-join-lines lst)

(Pin %pin-length lst)

(Pin %pin-url base tag file)

(Pin %pin-download-tmp! url target)

(Pin %pin-download! url target)

(Pin %pin-release-parse forms)

(Pin %pin-release-file name files)

(Pin %pin-bundle-parse forms)

(Pin %pin-bundle-decl-name)

(Pin %pin-bundle-tree stage)

(Pin %pin-digest-bin path)

(Pin %pin-untar! archive dest)

(Pin %pin-lang-parse forms)

(Pin %pin-untar! archive dest)

(Pin %pin-concat a b)

(Pin %pin-kind path)

(Pin %pin-ends-x? name)

(Pin %pin-x-files dir)

(Pin %pin-scan-project-files paths)

(Pin %pin-project-closure srcdir)

(Pin %pin-audit-missing dest rels)

(Pin %pin-vendor-project! dest srcdir label)

(Pin %pin-entry-of file)

(Pin %pin-lock-set-platform! dest forms)

(Pin %pin-nonplatform-render forms)

(Pin %pin-lock-root roots)

(Pin %pin-scan-arm! forms d dest)

(Pin %pin-scan-restore! snapshot)

(Pin %pin-dir-or-dot dir)

(Pin %pin-need head forms dir)

(Pin %pin-closure-names entries)

(Pin %pin-selected-paths entries)

(Pin %pin-unselected names selected)

(Pin %pin-rel-name rel)

(Pin %pin-name-candidates namestr)

(Pin %pin-cand-paths dir cands)

(Pin %pin-running-entry)

(Pin %pin-init-opts opts dir entry)

(Pin %pin-init-template entry)

(Pin %pin-take-module name)

(Pin %pin-take-version who name spec)

(Pin %pin-walk-file rel src)

(Pin %pin-tf-walk path rel acc)

(Pin %pin-tf-each path rel lst acc)

(Pin %pin-scan-pair which arg dirs)

(Pin %pin-scan-form form dirs)

(Pin %pin-scan-list forms dirs)

(Pin %pin-scan-project-pair which arg)

(Pin %pin-scan-project-list forms)

(Pin closure name)

The module’s vendorable import closure: root-relative file paths (the module, its transitive imports, and any ./-relative include siblings), discovery order. Boot-floor modules – pre-seeded under the running dialect, so inert in an overlay – are excluded. Loud error on any path the static walk cannot resolve.

Parameters:

Returns: LIST — Root-relative file path strings

(Pin vendor dest name)

Copy the module’s import closure into dest, preserving the root-relative layout (dest/x/type/dict.x pins x/type/dict). Run from a fresh session with x/tool/pin imported FIRST, so the boot floor is exact. A boot-floor seed is refused: it is unpinnable under this dialect (the pin boundary). Returns the copied paths.

Parameters:

Returns: LIST — Root-relative file path strings copied

(Pin vendor-project dest srcdir)

Vendor a whole project’s import closure in one call: scan srcdir’s *.x sources for every (import NAME), take the union of their closures, and copy it into dest with the lockfile updated – the multi-import vendor. Run from a fresh session with x/tool/pin imported FIRST (unarmed), so names resolve to the platform being vendored FROM and the boot floor is exact; boot-floor seeds are skipped. Returns the copied paths.

Parameters:

Returns: LIST — Root-relative file path strings copied

(Pin %pin-boot-fails dest lockforms)

(Pin %pin-engine-stamp name)

(Pin %pin-release-notice lockforms)

(Pin %pin-payload-notice lockforms)

(Pin %pin-tree-isa)

(Pin %pin-isa-notice lockforms)

(Pin verify dest)

Verify dest against its lockfile, BOTH halves: every overlay entry’s digest must match and every file in the tree must be listed (an unlisted file is a rogue shadow ready to win root precedence), and when the lock pins a boot amalgam, the amalgam on disk must match the lock’s recorded digest – the boot-time wrapper only compares recorded ISA strings, so verify is where a tampered or skewed amalgam is caught (#145). A missing lockfile, missing file, digest mismatch, or unlisted file is a loud error naming each offender; release, payload and ISA drift against the running engine are notices, never errors – the release pairing is ENFORCED by the wrapper at boot, where a refusal can still prevent the crash, and verify is where you read what it will decide. Returns the number of overlay files verified.

Parameters:

Returns: INT — Files verified

(Pin audit dest . srcdir)

Cross-check an overlay against the project’s real imports: scan srcdir’s *.x sources for their union import closure and report every required file MISSING from dest. Each missing file is an import that silently falls through to the live platform – a half-pin. Returns the missing root-relative paths (empty = complete) and prints a notice when non-empty; guard CI with (if (null? (Pin audit …)) ok (error …)). Run unarmed, like vendor-project.

Parameters:

Returns: LIST — Missing root-relative file paths (empty = complete pin)

(Pin init . opts)

Write a starter pin.xon – the manifest every other verb reads – commented so it teaches its own vocabulary: (root “deps”) (src “.”) (boot “boot/.x"). Writes intent only: no directories are made and nothing is downloaded (boot and sync do those, in that order). Refuses to overwrite an existing manifest. Returns the manifest's path.

Parameters:

Returns: STRING — Path of the written pin.xon

(Pin sync . dir)

Bring the overlay in line with the project’s code: read pin.xon, scan its (src …) tree for every import, and vendor the union closure into its FIRST (root …), rewriting the lockfile. Idempotent, and the whole update after a source file gains an import – no module list to maintain by hand. Run unarmed (–no-pin), so platform names resolve to the platform being vendored FROM; the manifest’s OTHER roots are the project’s own modules, and sync arms them itself for the scan (#223) – their files are walked for imports but never vendored: they are already in the repo, versioned, which is what those roots declare. Returns the vendored root-relative paths.

Parameters:

Returns: LIST — Root-relative file path strings now pinned

(Pin check . dir)

The whole integrity question in one call, for CI: the overlay must match its lockfile byte for byte (nothing edited, nothing unlisted), AND no import in the (src …) tree may fall through to the live platform. A digest mismatch or unlisted file is a loud error; a fallen-through import is reported and returned. Returns the missing root-relative paths – empty means the pin is complete and intact.

Parameters:

Returns: LIST — Imports absent from the overlay (empty = complete)

(Pin boot tag . opts)

Pin the language itself to a release, in one step: read the manifest’s (boot …) path, fetch and verify that release’s amalgam into place, and record the release tag, its ISA fingerprint, its payload fingerprint (when the release publishes one) and the amalgam’s digest in the lockfile beside pin.xon. The release manifest is consumed, not kept – its three facts live in the lock, so nothing generated is left in the boot directory. This verb is also the UPGRADE and the REPAIR: re-run it with a new tag to move the pin, or the same tag to restore a damaged amalgam or lock – the currently pinned amalgam stays in place until its replacement has verified (fetch publishes only a clean digest), and the lock rewrites only after that. Returns the amalgam’s path.

Parameters:

Returns: STRING — Path of the verified amalgam

(Pin resolve name spec)

The file an (import-version-once NAME “SPEC”) would load, resolved against the CURRENT import roots without loading anything – the dry run of a versioned import, as closure is of vendor. Run it where your program runs (armed, the overlay answers; unarmed, the platform does). A spec nothing satisfies is the same loud error the import raises.

Parameters:

Returns: STRING — Path of the file the spec selects

(Pin unused . srcdir)

Version files no import in srcdir’s sources selects – the safe-removal list. Provably neutral: resolution takes the newest satisfying candidate per root, so a file this returns cannot change any scanned import’s outcome by being removed (had it been able to win for some spec, it would already be selected). The answer is relative to the sources scanned: an external consumer’s specs are invisible here. Run unarmed, like audit; prints a notice when non-empty.

Parameters:

Returns: LIST — Full paths of version files nothing scanned selects

(Pin fetch dest tag entry . base)

Fetch a released amalgam, verified or nothing: downloads the tag’s pin.release.xon and .x (curl via fork/execvp -- absent curl prints the URLs and stops), checks the manifest names the tag, digests the amalgam with Sha256 -- the differentially-verified JIT engine where the host supports it (seconds), pure-x elsewhere (minutes for an amalgam; either way announced), and errors on any mismatch, naming the offending file (left in place for inspection; do not boot it). Reports whether the release's ISA fingerprint matches this tree's engine/tools/contract/isa.x when present -- drift is information, not an error: a pinned platform pairs with its own engine. Returns the amalgam's path.

Parameters:

Returns: STRING — Path of the verified amalgam

(Pin install url . dest)

Install a lang from a published pin, with nothing cloned. Downloads the lang.pin.xon the URL names, reads it (closed vocabulary – an unknown form is a loud error), then acquires the tarball that pin describes exactly as (Pin bundle) does: digested with pure-x Sha256 before tar runs, quarantined on mismatch, staged and renamed only once whole. Installs to /, the STABLE name `-l` resolves, replacing any previous version only after the new one has verified. Default destination is the running x's /langs, so an installed x needs no argument; a checkout has no install root and must be given one. Returns the installed directory.

Parameters:

Returns: STRING — Path of the installed lang

(Pin bundle dest . dir)

Acquire a lang bundle, verified or nothing. Reads lang.pin.xon (closed vocabulary – an unknown form is a loud error, never a skip), downloads the tarball its (bundle “sha256:…” “URL”) row names to a temp path, and digests it THERE with pure-x Sha256 before tar is run at all: an archive that does not match is quarantined as .rejected -- the bytes are the evidence -- and nothing is unpacked. A verified archive unpacks into a per-pid staging directory and is renamed into place at /-/ only once whole, so a tar that dies half way cannot leave a partial tree where the already-acquired check would later read it as complete. The bundle's lang.xon must agree with the pin about which lang it is, and its (requires-release ...) is reported against this tree's stamp -- drift named, not fatal. An already-acquired bundle at the same release is honoured without touching the network. Returns the bundle's directory.

Parameters:

Returns: STRING — Path of the verified, unpacked bundle

(Pin %pin-bundle-acquire! name tag want url dest home)

(Pin %pin-bundle-pairing pd)