`(sigil env package)`

(sigil env package) - First-class environment package values.

Channel modules construct immutable package records. Passing an existing package as the first constructor argument performs a functional copy with keyword overrides:

(package hello version: "2.10" source: old-source)

Human versions are metadata. package-identity hashes the complete canonical build-relevant value and is the reproducibility identity.

Canonical schema: package-v2

The canonical datum is package-v2. Relative to package-v1 it changes the meaning of dependencies: and adds five fields. There is exactly ONE canonical-schema revision planned for this work, and it defines the FULL target surface up front (topics/sigil-packaging-v2-implementation-plan decision 1.1): later stages ACTIVATE fields, they never redefine the schema, so package identities do not move when a capability arrives.

dependencies: (name, package-identity) pairs, not realized output hashes. A dependency now names a PACKAGE; the engine resolves the identity through the verified catalogue and substitutes an output hash only when it constructs the external-recipe. Authoring may pass sibling package values directly and the constructor normalizes them. build-inputs: same pair shape; tool packages that join PATH in the build sandbox but contribute no -I/-L/PKGCONFIGPATH flags and no named references. env: per-package environment, an alist of (NAME . VALUE). search-paths: exports this package contributes to its consumers, an alist of (VARIABLE . RELATIVE-SUBDIR). This is how one package's include layout stops being hardcoded in the generic builder. toolchain: optional package identity selecting a channel-packaged toolchain instead of the pinned seed one. phases: gain the run kind (an argv executed in the source tree). patches: gain the channel-resident form (channel-patch path: ... sha256: ...).

A field being expressible here does not mean it is realizable yet. Fields the current builder cannot honour are refused by POLICY at sigil channel publish (see (sigil channel publish)), loudly and by name, rather than by schema -- so identities stay stable as capability arrives.

package-v1 data remains DECODABLE for reading (read-package-v1-datum) and is refused by canonical-datum->package, which is the only door to a package identity.

Exports

package-depprocedure

Construct a package-dep record.

package-dep?procedure

Test if a value is a package-dep record (or a subtype).

package-dep-nameprocedure

Get the name field of a package-dep record.

package-dep-identityprocedure

Get the identity field of a package-dep record.

%sealed-package--typevariable

Get the identity field of a package-dep record.

sealed-packageprocedure

Construct a sealed-package record.

sealed-package?procedure

Test if a value is a sealed-package record (or a subtype).

sealed-package-nameprocedure

Get the name field of a sealed-package record.

sealed-package-versionprocedure

Get the version field of a sealed-package record.

sealed-package-sourceprocedure

Get the source field of a sealed-package record.

sealed-package-buildenvprocedure

Get the buildenv field of a sealed-package record.

sealed-package-toolchainprocedure

Get the toolchain field of a sealed-package record.

sealed-package-dependenciesprocedure

Get the dependencies field of a sealed-package record.

sealed-package-build-inputsprocedure

Get the build-inputs field of a sealed-package record.

sealed-package-envprocedure

Get the env field of a sealed-package record.

sealed-package-search-pathsprocedure

Get the search-paths field of a sealed-package record.

sealed-package-phasesprocedure

Get the phases field of a sealed-package record.

sealed-package-divergencesprocedure

Get the divergences field of a sealed-package record.

dependency-object-dataprocedure

Canonical datums for every package value that was used as a dependency or build input in this process, sorted by identity.

validate-interpolationsprocedure

${name} RESOLVES dependencies: ONLY. A build input is NOT nameable, and that is a deliberate restriction rather than an omission.

THE CASE IT CLOSES, named because it is a legitimate-looking one and someone will want it: --with-perl=${perl} / --with-tool=<path> in a configure invocation, where perl is declared as a build input. That is a real autotools idiom. It is refused because interpolating a build tool's store path puts that path into the built artifact, which makes it a RUNTIME reference to something the package never declared as a runtime dependency -- the exact condition P3.4's output reference scanning (scanned subset of declared) exists to refuse. A tool you built WITH is not a thing you link AGAINST, and letting ${} blur the two erodes the distinction the two fields exist to draw. Plan section 4 states the rule: only dependencies: produce -I/-L/PKGCONFIGPATH and ${name} references; build-inputs get PATH and search-paths only.

TO REOPEN IT DELIBERATELY, build-inputs would need a declared-runtime story first -- realistically P3.4, which is what could tell a baked tool path from a baked library path. Until then a package that genuinely needs the path declares the thing as a dependencies: entry, which is a true statement about what ends up in its output.

The restriction is enforced twice: here, at the identity door, and again in the builder, where interpolate-argument's dep-prefixes are built from dep-inputs and simply do not contain build inputs.

This TIGHTENED an earlier reading that accepted build-input names. It can move no identity: build-inputs: is refused at channel publish AND channel check with exit 70, so no package using one has ever been published and no derivation record naming one exists anywhere.

canonical-datum-schemaprocedure

The canonical schema tag of a datum, or #f if it is not a package datum at all. Callers that must distinguish "old format" from "garbage" ask this rather than pattern-matching the head themselves.

canonical-datum->packageprocedure

Strict inverse of package->canonical-datum. The reconstructed value is validated again so malformed data crossing the authoring child boundary can never acquire a package identity in the parent.

This is the ONLY door to a package identity, so it is also where the schema bump is enforced: a package-v1 datum is refused by name. 0.18.0 shipped with v1 as the canonical form, and a released binary that meets a changed format without a changed version tag would silently misread it instead of refusing. Refusing is the version field's whole job.

read-package-v1-datumprocedure

Decode a package-v1 datum for READING only. It yields an alist of the v1 fields, never a package value, so no v1 datum can acquire a v2 identity by any path. dependencies in v1 are realized OUTPUT hashes, which is a different kind of value from a v2 dependency identity; that is precisely why they are not interchangeable and why this returns raw fields rather than pretending to migrate them.

packagevariable

(No description)

package?variable

(No description)

package-namevariable

(No description)

package-versionvariable

(No description)

package-sourcevariable

(No description)

package-buildenvvariable

(No description)