Reference

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.

This page documents the TOML files that sit alongside a recipe — the workspace file, env files, and keyring files — and gives exhaustive reference tables for the three substitution systems used throughout pekit: template variables, source-ref roots, and publish targets.

All files are TOML. Every loader rejects unknown top-level keys with an unknown_key diagnostic, so the key tables below are complete: any key not listed is an error.

For the recipe file itself (pekit.toml / *.pekit.toml), see recipe-format.

workspace.pekit.toml #

A workspace file marks a directory as a pekit workspace and declares distro-wide defaults.

[policy] #

The [policy] table accepts package-version floors and exact ELF capabilities. Unknown keys are rejected.

Each entry in [policy.symbol_versions] is soname = "PREFIX_":

[policy]
symbol_capabilities = ["libstdc++.so.6"]

[policy.symbol_versions]
"libc.so.6"     = "GLIBC_"
"libgcc_s.so.1" = "GCC_"

env.pekit.toml #

An env file provides a named, selectable layer of environment variables, command wrapper, and dependency-provider override.

An env file must declare at least one of [env], [wrap], [sandbox], or dependency_provider; a file with none of them is rejected (missing_key).

[sandbox] #

A workspace profile's command (string or argv array, required) prepares the fresh PEKIT_SANDBOX_ROOT destination. No {{command}} placeholder is used. Optional network_targets is an array containing only "build:vendor". Optional entry is an argv array whose first element is a clean absolute path inside the prepared root. Pekit runs it inside the sandbox ahead of every target command of the profile, passing the target's shell invocation as its remaining arguments; the entry must exec them. The preparer must supply the program as an executable regular file, or the job fails with sandbox_entry before the worker starts. Processes the entry leaves behind end with the job. Pekit owns process isolation; the preparer only supplies dependencies. This table requires [isolation] enabled = true in the workspace. Member/source profiles cannot override it. See isolated production jobs.

If a prepared root has a missing or empty /etc/hosts, pekit supplies fixed IPv4 and IPv6 localhost entries before starting the worker. A populated regular hosts file is left intact; a symlink is replaced without following its target. Offline loopback tests therefore work without importing the host's aliases or granting network access.

[lint.allow] #

Some lint findings are a property of the build environment rather than of any recipe: a foreign toolchain whose startup objects carry no CET notes, say. An env file names those rules, each with its reason:

[lint.allow]
"elf.cet" = "Debian startup/runtime objects carry no CET markers; native builds enforce the rule"

The exemptions apply to the package lint gate and to a versioned pekit lint run under that --env, and to nothing built in another environment. Each key must be a known rule — not a parameter — and each reason must be non-empty. Both the workspace's and the recipe's selected env file contribute. An exemption a lint.pekit.toml already states keeps that file's reason, and allowed findings are reported like any other exemption. Use this only for an environment's own limitation; a package's defects belong in its recipe's lint file, or fixed.

--env <name> selection #

The active env file is chosen from the --env <name> flag (default main), resolved at the workspace root and then the recipe root:

When both files exist, the workspace file is the base and the recipe file overlays it for [env], [wrap], and dependency_provider. Outside a workspace only the recipe root is searched. The default env.pekit.toml is optional everywhere. When both paths resolve to the same underlying file, it is loaded only once.

[env] table #

Shared by workspace.pekit.toml, env.pekit.toml, and the recipe's own [env]. It is a flat table of NAME = "value" string pairs.

[env]
CC = "clang"
CFLAGS = "-O2 -pipe"
CXXFLAGS = "$CFLAGS -Wp,-D_GLIBCXX_ASSERTIONS"
TOOL_PATH = "$PEKIT_ROOT/tools"

$ always expands — a literal $ is not expressible here, and \$ does not escape it. A value needing one (an $ORIGIN rpath, say) belongs in the target's command, where the recipe has the full shell.

[wrap] table #

Shared by workspace.pekit.toml, env.pekit.toml, and the recipe. Wraps every target command in another command (sandbox, nice, a toolchain shim, etc.).

{{command}} rules:

• String form — the string must contain {{command}} exactly once.
• Array form — exactly one element must be the literal {{command}} (as a complete argument, not a substring), and it may not be element 0 (the program). An element that merely contains {{command}} inside other text is rejected.

[wrap]
command = ["bwrap", "--ro-bind", "/usr", "/usr", "{{command}}"]

Note: {{command}} here is a wrap-only placeholder handled by the wrap machinery. It is not one of the template variables below and is not available in ordinary recipe strings.

*.keyring.pekit.toml #

A keyring file supplies coordinator values and explicitly granted worker inputs. Keyrings are opt-in per invocation (--keyring); a keyring named <name> resolves to <name>.keyring.pekit.toml, searched in the workspace root then the recipe root (a path-like value is used verbatim).

Schema #

The file is a tree of nested TOML tables whose leaves are strings or { value = "...", access = "..." } entries. Requested worker inputs use an environment-variable name derived from their path:

• Prefix PEKIT_KEYRING_, then the dotted path uppercased.
• Every run of non-alphanumeric characters (including the . separators) collapses to a single _.
• Trailing _ is trimmed.

# placeholders only — never commit real secrets
token = "REPLACE_ME"

[github]
token = "REPLACE_ME"

[registry]
api-key = "REPLACE_ME"

Restrictions #

Well-known entries #

Targets receive only entries listed in keyring_inputs and permitted by their access grant. Inline overrides are coordinator-only. The following entry is read by Pekit itself:

Without a configured signing key, package writes unsigned artifacts, and publish refuses peipkg-format packages unless --allow-unsigned is passed (unsigned_publish).

A build target's sign table reads further entries, but which ones is the recipe's choice: each sign.pip value is the dotted path of a leaf holding the path to an ML-DSA-65 private key. Those private-key entries are never exported to workers.

lint.pekit.toml #

Enables and parameterises the rules pekit lint checks. pekit turns no rule on by itself; a tree with no lint file has nothing to lint.

Files are found from the recipe directory up to the workspace root, plus a delegated recipe's source root, and merge outermost first with the nearest file winning per key. A nearer file may not set a rule an outer file enabled to false (lint_rule_disabled); it exempts it through [allow] instead. Every rule, its accepted values and the merge order are on Linting.

pekit.lock #

The machine-written source lockfile, created and updated by pekit in the recipe directory beside pekit.toml. It pins fetched source inputs trust-on-first-use: the first resolve of a version records what was fetched, and every later resolve verifies against the record — see Sources for the behaviour. Commit it, and do not edit it by hand: pekit lock --repin --version <v> is the one supported way to change an existing ordinary git or URL entry. Tracked-path git history is append-only, so changed bytes get a new date version and --repin is rejected. Loading is strict — an unknown key is unknown_key and an unsupported schema is lock_schema.

Schema #

Each [[source]] entry carries the keys for its source kind:

Each [[input]] entry is addressed by name and version, and asserts what a url [[source]] entry does. The entries include inputs declared by a delegated source tree, which are pinned here, in the delegating recipe's lock:

Worked example #

schema = 1

[[source]]
  version = "0.5.12"
  url = "https://example.org/dash-0.5.12.tar.gz"
  sha256 = "6a474ac46e8b0b32916c4c60df694c82058d3297d8b385b74508030ca4a8f28a"
  signature_key = "9f0b7ddc1325a3e2c40e5f0a88b1c62f3d94ab07"
  locked_at = "2026-08-10T11:00:00Z"

  [[source.patch]]
    url = "https://example.org/dash-0.5-patches/dash05-001"
    sha256 = "9b44d9f7a36d1a20537817f92da72bf10eb81f66df860f23298b2d4e830a6d8d"
    signature_key = "9f0b7ddc1325a3e2c40e5f0a88b1c62f3d94ab07"

[[source]]
  version = "1.2.0"
  ref = "v1.2.0"
  commit = "8f3a1bc99e2f6d41c07b21ac1886d63b7f2e5d10"
  locked_at = "2026-08-10T11:00:00Z"

[[source]]
  version = "2026.09.06.2"
  repository = "https://github.com/example/upstream.git"
  ref = "refs/heads/release"
  path = "security/trust/certdata.txt"
  commit = "6b839fbb82801a7a5f5e37df0864c149fddda2b7"
  blob = "65fddc0b380650ee16aa47e4e28e3a5e2c95f201"
  blob_sha256 = "fa5092f93c2d5352ebf6c9f4f26f4232a2e2bc0fd8a8950756c1984984b490e0"
  locked_at = "2026-09-06T12:00:00Z"

The patches directory #

The directory named by [source] patches = "<dir>" in pekit.toml (conventionally patches, and always a single path segment). pekit applies its series to the materialised source tree before any target runs — see Sources for the behaviour — and the whole directory ships in the recipe's source package under patches/.

The series file #

<dir>/series lists the patches in apply order: one slash-separated relative path per line. # starts a comment, whole-line or trailing; blank lines are ignored; entries must not contain whitespace. Subdirectories are allowed (misc/fix.patch).

Loading is strict:

Application is git apply per entry, in series order, with no fuzz: a failed hunk is patch_apply and a patch that matches nothing is patch_skipped.

Worked example #

patches/
  series
  misc/
    mke2fs-root-sd.patch

with a series of:

# Applied in dependency order:
misc/mke2fs-root-sd.patch   # stamp the root inode's SD at format time

Give each patch file a short header — what it changes and its upstream status (submitted, backport, Peios-specific). The series ships with the corresponding source, where that header is a third party's only context.

Template variables #

Recipe and package value strings (source refs, ref, package metadata, file/symlink paths, excludes, claims, multipack enum.files.path, publish path) are run through the template engine before use. The syntax is {{name}}, where name matches [A-Za-z0-9_]+. An unknown name is an error.

A version string has one or more dot-separated numeric components, an optional unseparated alphanumeric suffix beginning with a letter (for example 2026c), and optional -prerelease and +buildmeta tails. {{version}} preserves the full string. {{major}}, {{minor}}, and {{patch}} expose the first three numeric components for compatibility, so {{minor}} / {{patch}} are only present when the version actually carries them; fourth and later components are available through {{version}} only.

Shell targets use $PEKIT_* instead #

The {{...}} engine applies to recipe configuration strings, not to the shell bodies of build/test/install/clean commands. Target commands instead read the pekit-managed environment. The version equivalents are:

Alongside these, the managed environment also exports PEKIT_RECIPE_ROOT, PEKIT_SOURCE_ROOT, PEKIT_LITERAL_ROOT, PEKIT_ROOT, PEKIT_OUT_BASE, PEKIT_OUT, PEKIT_COMMAND, PEKIT_TARGET, PEKIT_WORKSPACE_ROOT, PEKIT_BUILD_TIMESTAMP, PEKIT_SOURCE_TIMESTAMP, a PEKIT_<DEP>_OUT per declared needs dependency, and any PEKIT_KEYRING_* from active keyrings. The full environment contract is documented in the command-line reference.

Source-ref roots #

Package files sources, excludes, and multipack.enum.files.path are references whose leading token selects which root the path is resolved against. A reference is ROOT:path (or a bare path, which normalises to the owner's default root).

Any reference containing a : that is not one of the @-prefixed roots is a build reference; the token before the : is the target name. See packages for how these are used in a package's [files] table.

Publish targets #

The publish command sends a package's freshly built artifact to its declared destinations. There are two publish kinds: localdir and peipkg. Any other [publish.*] key is rejected (unknown_key). A package selected for publishing that declares no target is an error.

localdir #

Targets are an array of tables:

[[publish.localdir]]
path = "dist/{{version}}"
overwrite = false

Resolution details:

peipkg #

The singular [publish.peipkg] target publishes all peipkg artifacts selected for one package/version plan that name the same directory as one batch through the Peipkg repository publisher:

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

A direct relative signing_key path resolves from the base root. A path read from a keyring resolves from the invocation's working directory, like signing.package_key. Both raw 32-byte Ed25519 seeds and PKCS#8 PEM files are accepted.

If the directory named by path is absent or empty, Pekit initializes a complete repository there: signed descriptor, public keys, and empty active and archive indexes. The repository metadata key becomes a trust key. When the freshly built packages use a different signing.package_key, its public half is also recorded as a trusted key, so consumers can verify those packages. An existing repository is never reinitialized or given new trust implicitly; its descriptor must already trust both the metadata-signing key and the package-signing key.

Pekit then publishes that batch into the repository's canonical p/<name>/<version>/ tree and regenerates both signed indexes once for the batch. The batch is published only after every selected package of the recipe has been written and has passed the lint gate: if any of them fails, none is published, so a partly failed publish --all cannot leave a family at mixed revisions. Separate selected versions and workspace members are serialized but remain separate repository publications, so a workspace run that stops at a failing member keeps the members already published before it. The target rejects non-peipkg artifacts and already-published name/version/architecture identities. Workspace members sharing one repository are serialized so their whole-index updates cannot overwrite each other.

The directory is the repository and can be served or copied verbatim. This target does not upload it to remote storage; combine deployment with a separate step when the serving tree is not locally mounted.

Selectors #

Several names above are validated as selectors: target names, package selectors, multipack values, and dependency_provider. A selector must match ^[A-Za-z0-9_.+-]+$, must not be empty, must not start with -, and must not contain / or :.

See also #

• Recipe format reference — the pekit.toml and package-file schemas.
• Environments and keyrings — how env and keyring files are selected and layered.
• Signing and provenance — signing.package_key and pekit.lock in the trust chain.

This is the exhaustive reference for pekit's command line and the environment it exports to the commands it runs. Every flag listed here is a real flag accepted by the parser; there are no others. For a narrative walk-through of the grammar and recipe location, see Invocation and flags; for what each command does, see Commands and targets.

Synopsis #

pekit [global flags] <command> [args and flags]
pekit [global flags] workspace [workspace flags] <command> [args and flags]

<command> is exactly one of build, test, install, package, publish, clean, gen, verify, lock, lint, workspace, help, or version. Flags may appear before or after the command word and are parsed identically on both sides — the sole exception is the workspace tail (see Workspace flags). A bare -- ends flag parsing; every following token is captured verbatim as a positional selector. Positional selectors may not begin with -.

Help and version #

--help wins over validation: pekit clean --version 1 --help prints help rather than unsupported_flag. help and version accept the global flags and no others; workspace cannot delegate to either.

Flag value forms #

The shape of a flag determines how its value may be written.

Global flags #

Accepted by every command, before or after the command word. These are never subject to the capability matrix below.

The renderer is chosen from these flags: --json selects the JSON renderer (with --dry-run it buffers and prints a single plan object); otherwise the human renderer runs, in quiet mode when --quiet is set.

Version, source, and build flags #

These are command-specific: each is only accepted by the commands marked in the capability matrix. Passing one to a command that does not support it is unsupported_flag unless --allow-unused is set.

--version/-V, --latest, and --all-versions form one mutually-exclusive group ("version selection"); --local and --prefer-local form the "local source flags" group.

Workspace flags #

workspace delegates to another command. Its tail is parsed specially: the two workspace-only flags must appear after workspace and before the delegated command word. Everything after the delegated command is parsed as an ordinary invocation of that command.

Two member-selection flags follow the delegated command, with its own flags. Outside workspace they are an error (invalid_flags).

A selection that matches no member fails with empty_workspace.

Global flags (--dry-run, --json, --recipe, …) may also appear in the tail before the delegated command. A version/source/build flag placed there is an error (missing_workspace_command, "workspace command flag … must appear after the delegated command"): those belong after the delegated command. The same code fires when no delegated command follows at all. See Workspaces.

Capability matrix #

Which command accepts which flag group. Global flags and workspace flags are omitted (global flags are accepted everywhere). A blank cell means the flag group is unsupported for that command.

"clean mode" is the --output-only / --target-only pair. Plain lint acquires delegated recipe files automatically. Its version-selection and local-source flags make that source choice explicit and additionally select an existing build stage for payload rules; it never builds.

Validation and mutual-exclusion rules #

The parser rejects contradictory or malformed invocations before doing any work.

--allow-unused relaxes only the "recognised-but-unused" and "clean --output-only unused env/keyring" checks; it never excuses unknown flags, malformed values, the mutual-exclusion rules, or bad selectors.

Exit codes #

There are no other exit codes.

Environment contract #

Before running a target's command, pekit constructs its environment in layers: managed PEKIT_* variables, then keyring exports, then user-declared env (workspace → source → recipe → env-file). The process inherits the parent environment with these overlaid. User env may not define any PEKIT_* variable — doing so is reserved_env. The command runs with its working directory set to the source root (or the recipe root for a clean target).

Always set #

Exported for every target pekit runs.

Set only in an isolated workspace #

When the workspace enables isolation, the profile's root preparer and the sandboxed target see a few more variables.

Set only when a version is selected #

Exported only when the run resolves a non-empty version.

Per-dependency and per-keyring variables #

A keyring export that collides with a managed PEKIT_* variable or with a normal env variable is env_collision.

See also #

• Invocation and flags — the narrative walk-through of the grammar.
• Commands and targets — what each command selects and runs.
• Environments and keyrings — the layers behind the environment contract.