Recipe format reference

34 min read

This is the normative schema for the two TOML files at the heart of a pekit recipe: pekit.toml (the recipe proper) and package.pekit.toml (what to package). It enumerates every section, every key, its type, whether it is required, and its meaning. Behaviour that a key merely triggers is cross-linked to the concept pages; this page is the field-by-field contract.

Two strictness rules hold throughout and are called out per-section below:

• Unknown keys are hard errors. Every table the loader owns has a fixed set of accepted keys. Any other key — including a camelCase spelling of a known snake_case key, such as outDir — is rejected with an unknown_key diagnostic. There is no lenient/forward-compatible mode.
• Types are checked on decode. A key declared here as a string must be a string, a table must be a table, and so on; a mismatch is an invalid_type error.

pekit.toml #

Worked example #

out_dir = "dist"

[env]
CFLAGS = "-O2"
PREFIX = "/usr"

[wrap]
command = ["pesb", "run", "--", "{{command}}"]

[source.git]
url = "https://github.com/example/tool.git"
ref = "v{{version}}"
versions = ">=1.0"
tag_regex = "^v(?P<version>[0-9.]+)$"

[build]
command = "make PREFIX=$PREFIX"

[build.docs]
command = ["make", "docs"]
needs = ["main"]

[build.linked]
command = "make link"
dependencies.pesb-dev.libc = ">=2.38"

[test]
command = "make check"

[install]
command = "make install DESTDIR=$PEKIT_OUT"

[clean]
command = "make clean"

Top-level keys #

The recipe file accepts exactly these top-level keys. Anything else is an unknown recipe key error.

[env] #

A flat table of environment-variable name → value. Every entry is exported into each target command's environment (layered on top of the PEKIT_* contract; see Anatomy of a recipe).

Each NAME must match ^[A-Za-z_][A-Za-z0-9_]*$; anything else is an invalid_env error. Values must be strings. Declaration order in the file is preserved, so a later entry may reference an earlier one via shell expansion in the target command.

[wrap] #

Wraps every target command in another command (for example, running it inside a sandbox launcher).

No other key is permitted under [wrap]. The {{command}} rules mirror a target command:

• String form: the whole string is run through a shell; it must contain the substring {{command}} exactly once.
• Array form: {{command}} must appear as a complete argument (not a substring of a larger argument) exactly once, and never as the first element (element 0 is the wrapper program itself).

An omitted command yields an empty wrap (no wrapping).

[source] #

Selects and configures the source tree. It has four sub-tables. At most one reproducible source (git, url, or pypi) may be present — declaring more than one is a mixed_source error. A local source may be combined with a reproducible one (the local path acts as an override). Unknown keys directly under [source] are rejected.

One direct key is accepted alongside the sub-tables:

See Sources for materialisation, caching, and provenance behaviour. Resolved git, url, and PyPI sources are pinned trust-on-first-use in the recipe's machine-written pekit.lock.

[source.git] #

[source.git.signature] #

Optional sub-table of [source.git]. If present, every resolve requires a valid OpenPGP signature on the release. The signature is checked after the mirror fetch and before the lock is written or the tree is checked out. An unsigned or lightweight tag, or an unsigned commit, is signature_missing. An SSH or X.509 signature is signature_unsupported. A signature that fails, or a tag object that names another tag or points somewhere other than the resolved commit, is signature_invalid. Each of these aborts the run and writes no lock entry. The verified signer's fingerprint is recorded as the lock entry's signature_key.

[source.url] #

When patch_series is present, the selected version must be stable major.minor.patch. The primary url, root, checksum-table lookup, and signature render against major.minor; the complete selected version remains the package version.

[source.pypi] #

Pekit requests https://pypi.org/simple/<normalized-project>/ as application/vnd.pypi.simple.v1+json. It accepts one non-yanked, stable, Pekit-compatible, PEP 625 .tar.gz sdist per version, requires that entry's SHA-256, extracts its standardized root, and records the exact URL and digest in pekit.lock. Wheels and legacy sdist formats are not candidates. There is no configurable index URL in this source kind.

[source.url.signature] #

Optional sub-table of [source.url]. Its presence makes upstream signature verification required: the detached signature is fetched and verified against the pinned keys before a version is locked or built. A missing signature is signature_missing; a failed verification is signature_invalid; either aborts the run and writes no lock entry. Verification is in-process OpenPGP — no host gpg is involved.

Key expiry is evaluated at the signature's signed creation time, so a later key expiry does not invalidate an older release. Current key revocations and explicit signature expiry are still enforced, and a signature dated after key expiry or materially in the future is rejected by default.

[source.url.patch_series] #

Optional sub-table of [source.url] for upstreams that publish a base archive and numbered incremental patches. Version major.minor.N materialises the base plus patches 1 through N. Enumeration always exposes patchlevel zero and every contiguous published patchlevel; a gap is url_patch_gap.

Patches are applied in order using the host patch command with batch mode, forward-only application, and fuzz disabled. All patch hashes and configured signatures are verified before Pekit writes the version's lock entry.

[source.local] #

[input.<name>] #

An additional authenticated upstream, for a build that genuinely consumes more than one. A recipe may declare any number, each under its own name. Names are lower-case alphanumeric words separated by hyphens (invalid_name otherwise), and must stay distinct after upper-casing and mapping - to _, because that is the $PEKIT_INPUT_<NAME> a target reads.

Accepts the same keys as [source.url], including a nested signature table, with two differences:

{{version}} inside an input block renders that input's own version, never the recipe's. Each input is fetched, signature-checked and pinned in pekit.lock as an [[input]] entry, materialised at $PEKIT_INPUT_<NAME>, bind-mounted read-only under isolation, and carried in the source package under upstream/<name>/.

When a recipe delegates build, the fetched source tree's own [input.<name>] tables are part of the build too. The delegating recipe resolves and pins them in its own pekit.lock, and their key_files resolve beside the source's pekit.toml. A recipe input with the same name replaces the source's as a whole. See Additional inputs.

[delegate] #

Lets a recipe borrow definitions that live inside the fetched source tree rather than in the recipe directory. May be written as a bare boolean (delegate = true, equivalent to all = true) or as a table.

Any other key is an unknown delegate key error. A category is delegated when either its own flag or all is set.

[source_package] #

Controls the corresponding-source package a recipe emits alongside its binary packages. Emission is automatic; the table controls naming, emission and additional shared source inputs. A recipe emits one when both of these hold: it has a reproducible [source] (git, url or PyPI; local overrides and bare branch refs never qualify), and it produces at least one peipkg-format package.

Any other key is an unknown source_package key error.

The emitted package is noarch, versioned identically to the recipe's package members (members that disagree on version are a source_package_version_conflict error), licensed as the conjunction of the members' licenses and license (see below; and classed as the most encumbered member's class — proprietary over firmware over unknown over free, with an undeclared member counting as unknown), and installs under /usr/src/dist/<name>-<version>/ (with any -source suffix stripped from <name>).

The conjunction is built term by term. Each expression is split into its top-level AND terms. A term containing OR keeps its parentheses, so the surrounding ANDs can't rebind it. Repeated terms appear once, and the terms are sorted. Members licensed GPL-2.0-or-later OR LGPL-3.0-or-later, GPL-3.0-or-later and GPL-3.0-or-later AND LGPL-2.1-or-later produce (GPL-2.0-or-later OR LGPL-3.0-or-later) AND GPL-3.0-or-later AND LGPL-2.1-or-later.

The package's content:

• upstream/ — the pristine source input: a url source's downloaded artifact byte-for-byte, so its hash matches the committed pekit.lock, or a git archive export of the locked commit.
• source/ — the prepared tree, with patches already applied. Large trees travel in prepared-source.tar instead; rebuild.py verifies and reconstructs source/ before invoking Pekit.
• workspace/ — the complete captured recipe, shared inputs, inherited policy and environment profiles, preserving their relative paths.
• recipe/ and patches/ — compatibility views.
• acquisition/ and build-environment/ — captured vendoring outputs and dependency identities when provided by the isolated job.
• build-inputs.json, rebuild.py, REBUILD.md — schema-2 or schema-3 hashes, modes, provenance and the outside-checkout reconstruction command.

Output/cache state, ignored developer files, keyring/credential files and configured key paths are excluded. Missing or escaping source links fail closed. See source reconstruction for required dependency services, signing keys and the bounds of reconstruction.

Every peipkg-format member the recipe emits carries the source package's name in its manifest's build.source_package field, linking each binary to its corresponding source.

[build] / [test] / [install] / [clean] #

These four sections define targets — the commands pekit runs. Each section takes one of two shapes, distinguished by whether a command key is present directly in the section:

• Bare target: command (and the other target keys) sit directly under the section, e.g. [build] with command = "make". This defines a single target named main.
• Named targets: the section contains sub-tables, e.g. [build.docs] and [build.linked], each a target. Each name must be a valid selector.

Mixing the two — a bare command alongside a named sub-table in the same section — is a mixed_targets error. (A sub-table whose key is itself a target key, such as [build.dependencies], is read as part of the bare target, not as a named target.)

Fields of a single target:

Any other key in a target table is an unknown target key error. sign is accepted only in [build] targets, gate only in [test], and dependencies in [build] and [test]; using them elsewhere is an unknown key.

The dependencies table is keyed by provider (a selector), each mapping dependency names to version constraints:

[build.linked.dependencies]
pesb-dev.libc = ">=2.38"
pesb-dev."pkgconfig(zlib)" = "*"

Dependency names may be real package names or virtual capabilities (sonames, pkgconfig(...), etc.) and are validated against peipkg's capability grammar. See Commands and targets.

[build.<name>.sign] #

The sign table is keyed by signature kind. Each kind is a table mapping a path or glob, relative to the target's $PEKIT_OUT, to the dotted path of the keyring entry holding the signing key:

[build.main.sign.pip]
"bin/peinit"  = "tcb.priv"
"lib/*.so.*"  = "tcb.priv"

The kind decides the signature format and where it is stored; the keyring entry is resolved through the ordinary keyring mechanism when the target runs. Signing happens after the target's command exits 0 and before any dependent target or package sees the output.

For pip, the key is an ML-DSA-65 private key — PKCS#8 PEM as produced by openssl genpkey -algorithm ML-DSA-65, or a raw 32-byte seed — and every matched file must be a 64-bit little-endian ELF. A pattern that matches nothing (sign_target_missing), a keyring entry that is absent or does not load (signing_key), a file that cannot carry the signature (sign_failed), and two patterns naming different keys for one file (sign_conflict) are all errors; pekit never leaves a listed file unsigned. The mechanism is described in Signing and provenance.

[gen] #

A [gen] section defines source-generating targets: they run at the recipe root and write generated source into the tree rather than producing an out_dir artifact. Bare/named shapes work exactly as for the target sections above ([gen] is gen.main; [gen.<name>] names a target). Gen targets have their own fields — they take no needs or clear_out:

Any other key is an unknown target key error. Setting verify_on_build, verify_on_test, or verify_dependencies without a verify_command is an invalid_gen error (there is nothing to gate).

A gen target's $PEKIT_OUT is a pekit-managed scratch directory (<out_dir>/.scratch/gen/<name>) outside the artifact area, cleaned on success and retained on failure — a convenient place for verify_command to regenerate into for comparison. For the command surface, the pre-flight, and --no-verify, see Commands and targets.

package.pekit.toml #

The package file describes one or more package artifacts to emit from the built source. The same schema applies to the base file (package.pekit.toml) and to per-member member files (<name>.package.pekit.toml); see Multi-package recipes and Supporting files for how the files are discovered and layered.

Worked example #

format = "peipkg"
builds = ["main"]

[package]
name = "tool"
version = "{{version}}"
architecture = "x86-64-v3"
description = "An example tool"
license = "MIT"
homepage = "https://example.com/tool"
default_root = "opt.tool"

[dependencies]
libc = ">=2.38"
zlib = { constraint = ">=1.3", root = "opt.tool" }

[optional_dependencies]
libcurl = ">=8.0"

[provides]
tool = "{{version}}"

[files]
"main:bin/tool" = "usr/bin/tool"
"@recipe:share/" = { path = "usr/share/tool/", override = true }

[symlinks]
"usr/bin/t" = "tool"

excludes = ["@recipe:share/*.tmp"]

[claims.provides.editor.default]
path = "usr/bin/editor"
target = "usr/bin/tool"

[[publish.localdir]]
path = "dist"
overwrite = false

Top-level keys #

The package file accepts exactly these top-level keys; anything else is an unknown package key error.

Most string-valued fields (metadata, dependency names/constraints, file refs and destinations, claim paths/targets) are run through the template engine, where {{version}} and {{multipack}} are available. After [package].version is rendered, {{release}} is also available: the package's own full version, including its revision (1.13.2-3 for version = "{{version}}-3"). Pin packages built from the same source to each other with "= {{release}}", so the pins follow the revision automatically; the package.dependencies lint rule reports relations that spell out "{{version}}-N" by hand. See Versions and Multi-package recipes.

[package] #

Package metadata. Accepts exactly these keys; any other is an unknown package metadata key error. All values are strings.

Note that dependencies, provides, conflicts, and the rest are top-level tables, not sub-keys of [package].

[dependencies] #

Runtime dependency constraints. [optional_dependencies] has the identical schema. Each entry is either a bare constraint string (the short form) or a table that additionally places the dependency in a named root.

Table form keys — only these two are accepted (unknown_key otherwise):

Dependency names may be real or virtual capabilities. See Dependencies and claims.

[files] #

Maps a source ref (the key) to a destination path within the package payload (the value). The value is either a string destination or a table.

Table form keys — only these are accepted:

The source ref selects where the file is read from. A bare path with no prefix is resolved against the recipe root (or the layer's owner). Explicit forms: @recipe:<path>, @source:<path>, @workspace:<path>, and <build-target>:<path> (reading a build target's output; :<path> alone uses the main build target). Destinations ending in / and glob patterns are supported. See Packages for ref resolution and glob semantics.

[symlinks] #

Maps a destination path within the payload (the key) to a symlink target (the value).

Table form keys — only these are accepted:

excludes #

An array of refs/globs. During directory payload expansion, files matching an exclude pattern (resolved against the same root as the file mapping being expanded) are dropped from the payload. Patterns use the same ref forms as [files] keys.

[multipack] #

Expands one definition into a family of package instances, one per enumerated value. The only accepted key is enum, which takes one of two shapes:

Explicit list:

[multipack]
enum = ["gtk3", "gtk4"]

Each value must be a valid selector, non-empty, and unique.

Enumerated from files:

[multipack.enum.files]
path = "@source:themes/*/theme.ini"
regex = "^(?P<value>.+)$"

[multipack.enum.files] accepts exactly path and regex, both required:

See Multi-package recipes.

[publish] #

Where finished artifacts are published. localdir copies an artifact by basename and is written as an array of tables:

[[publish.localdir]]
path = "dist"
overwrite = false

Each entry accepts only path and overwrite:

peipkg publishes peipkg-format artifacts into a complete signed repository and is written as one table:

[publish.peipkg]
path = "dist/repository"
name = "experimental"
signing_key = "keyring:signing.repository_key"

If the directory named by path is absent or empty, it is initialized before the first package batch is published. A non-empty directory that is not already publisher state is refused rather than overwritten. Only peipkg-format artifacts may use this target. See Publish targets for key resolution, batching, and repository semantics.

[claims] #

Attaches claim slots to provides and dependency entries (a claim is a symlink slot a provider fills or a consumer expects). The [claims] table has two sides — provides and dependencies — each keyed by the provides or dependency name, then by slot, then to a descriptor. Any side other than provides/dependencies is an unknown_key error.

[claims.provides.<name>.<slot>]
path = "usr/bin/editor"
target = "usr/bin/tool"

[claims.dependencies.<name>.<slot>]
path = "usr/bin/editor"

A slot descriptor accepts exactly these two keys (anything else is rejected); both are strings and both are templated:

Provider-side slots (claims.provides) attach to matching [provides] entries by name; consumer-side slots (claims.dependencies) attach to matching [dependencies]/[optional_dependencies] entries. See Dependencies and claims and the Peios claims model for the resolution behaviour.

See also #

• Supporting files — the workspace, env, keyring, lockfile, and patch-series schemas.
• Anatomy of a recipe — the narrative walk-through of these files.
• Packaging files — how [files] refs and destinations resolve.

[sd_overrides] #

Each key is a payload path — exactly as it appears in the package, with no leading slash — and each value is an SDDL string. pekit compiles it to a binary security descriptor at pack time and puts the result in the manifest.

[sd_overrides]
"home" = "O:SYG:SYD:P(A;OICI;GA;;;SY)(A;OICI;GA;;;BA)(A;;FX;;;WD)"

An entry with no override gets its descriptor by inheritance from its parent directory when the consumer creates it, and that is what almost every entry should get. Declare one where a path needs to be more restrictive than its parent would make it, needs access for a principal the parent's inheritable ACEs do not name, or needs to start a new inheritance scope of its own.

Three constraints are worth knowing before writing one:

• The path must name a real payload entry, and it must be a regular file or a directory — never a symlink, which carries no descriptor of its own. A consumer rejects the whole package otherwise.
• Absolute SID aliases only. The compile happens on a build host with no domain and no machine to resolve against, so SY, BA, CO, WD and literal SIDs are fine while domain- and machine-relative aliases (DA, EA, LA and the rest) are an error.
• A rights field may end in a hex literal. FRFX, 0x1200af and FRFX0x6 all parse, the last of them as file read, file execute and the two bits after that. Use it for rights with no two-letter mnemonic — FILE_ADD_FILE and FILE_ADD_SUBDIRECTORY, in particular — rather than writing the whole mask as hex and losing what the mnemonics said. The literal consumes the rest of the field, so it can only come last.

Edit this page