Supporting files and reference tables

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. Loaded by LoadWorkspace.

[policy] #

The [policy] table currently carries exactly one sub-table. Any other key under [policy] is rejected.

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

[policy.symbol_versions]
"libc.so.6"     = "GLIBC_"
"libstdc++.so.6" = "GLIBCXX_"

---

env.pekit.toml #

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

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

--env <name> selection #

The active env file is chosen from the --env <name> flag (default main), resolved relative to the recipe root:

So --env prod loads prod.env.pekit.toml, and it must exist. The default env.pekit.toml is optional.

[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"

[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 (enforced by validateWrapCommand):

• 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 secrets to the build environment as PEKIT_KEYRING_* variables. 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. Each leaf's dotted path is converted into an environment-variable name:

• 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 #

---

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 parses as major[.minor[.patch]][-prerelease][+buildmeta], so {{minor}} / {{patch}} are only present when the version actually carries them.

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 recipe-format.

---

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 copies a package's built artifact to declared destinations. There is exactly one publish kind: localdir. Any other [publish.*] key is rejected (unknown_key). A package selected for publishing that declares no target is an error.

Targets are an array of tables:

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

Resolution details:

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 :.