pantry

Documentation

Overview

Package pantry parses and validates pkgx pantry package.yml recipes. The parsed Recipe is the shared representation that both the YAML front-end and the HCL2 front-end decode into, so a recipe written either way yields an identical build.

Index

• func Supports(r *Recipe, platform, arch string) bool
• func Validate(data []byte) error
• type Recipe
  • func Parse(data []byte) (*Recipe, error)
• type Runtime

Functions

func Supports

func Supports(r *Recipe, platform, arch string) bool

Supports reports whether a recipe's `platforms:` admits one target.

The field was parsed and read by nobody. 81 recipes in the pantry declare a platforms: that excludes darwin — elfutils.org, systemd.io, x.org/xserver, kernel.org/linux, github.com/vmware/tdnf among them — and every consumer treated them as darwin candidates: `bk factory` on darwin attempted them and collected the failures, and `bk depgaps` ranked THEIR unmet dependencies as darwin gaps, which is how rpm.org/rpm and opensuse.org/libsolv came to sit in a darwin/aarch64 ranking.

Honouring it removes only work that cannot succeed. Measured against the published registry: of those 81, seven do have a darwin bottle (freedesktop.org/libbsd, github.com/containerd/nerdctl, github.com/containers/buildah, github.com/rui314/mold, gnupg.org/v2.5, google.com/fullycapable, mercure.rocks) and all seven are MIRRORS — platform-tags=0, upstream's layer format. Our factory has never built one.

Three spellings are accepted, because the pantry uses all three:

platforms: linux                        # a bare string
platforms: [linux]                      # a list of OS names
platforms: [linux/x86-64, linux/aarch64]  # os/arch slugs

An absent field means every platform. An entry naming only an OS admits every arch of it; an os/arch slug admits exactly that pair.

func Validate

func Validate(data []byte) error

Validate checks raw package.yml bytes against the authoritative schema.

Types

type Recipe

type Recipe struct {
	Distributable any            `yaml:"distributable"`
	Versions      any            `yaml:"versions"`
	Dependencies  map[string]any `yaml:"dependencies"`
	Build         any            `yaml:"build"`
	Test          any            `yaml:"test"`
	Provides      any            `yaml:"provides"`
	Runtime       *Runtime       `yaml:"runtime"`
	Companions    map[string]any `yaml:"companions"`
	Platforms     any            `yaml:"platforms"`
	Warnings      any            `yaml:"warnings"`
	// Members makes a recipe a SET: a named, versionable tree of packages
	// rather than one discrete package.
	//
	// The three systems that solved this agree on the shape and disagree on
	// almost nothing that matters here:
	//
	//	Nix    a tree IS a derivation — `buildEnv` takes a list of packages
	//	       and its output is a tree of symlinks. No new kind of object.
	//	Guix   a manifest names packages; a PROFILE is the tree it makes.
	//	Spack  `spack.yaml` is the abstract set, `spack.lock` the concrete
	//	       one: "the same root specs... may concretize differently".
	//
	// Nix's answer is the one taken: a set is an ordinary recipe. It is
	// therefore signed, attested, published and installed by everything that
	// already does those things for a package — rather than a second kind of
	// artefact to keep in step, which is the defect this repository has paid
	// for more than once.
	//
	// What this does NOT give is Guix's warning: a manifest alone is not
	// reproducible, because the same names resolve differently against a
	// different package set. `members` is the ABSTRACT half; `bk lock` is
	// the concrete one, and writes the resolved versions down beside the
	// pantry and overlay revisions that produced them.
	//
	// The shape is `dependencies`' shape on purpose: a reader who knows one
	// knows the other, and the resolver already handles it.
	Members map[string]any `yaml:"members"`

	DisplayName string `yaml:"display-name"`
	Summary     string `yaml:"summary"`
	Description string `yaml:"description"`
}

Recipe is a decoded package.yml. Fields use `any` where pkgx allows several shapes (a script may be a string or a list; env values a scalar or a list; deps a constraint or a platform-keyed map) — the build-script generator resolves those shapes against the build target. Unknown keys are retained in Extra so nothing is silently dropped.

func Parse

func Parse(data []byte) (*Recipe, error)

Parse decodes and validates package.yml bytes into a Recipe. It decodes into the typed struct first (so a type mismatch is reported precisely), then checks the whole document against the authoritative schema.

type Runtime

type Runtime struct {
	Env map[string]any `yaml:"env"`
}

Runtime is the environment a package exports to its consumers.