These docs are under active development.
Peios Learn
On this page
Concept 4 min read

What pekit is

Pekit is the tool that turns source into packages. You describe a piece of software once — where its source comes from, how to build it, and how to split the result into .peipkg files — in a set of declarative recipe files, and pekit does the rest: fetches the source, selects versions, runs the build, stages the output, and writes packages you can install or publish.

Everything in the Peios tree is built with pekit. The kernel, the registry store, the init system, the package manager itself — each is a recipe, and pekit package produces the .peipkg files that peipkg-compose and peiso assemble into a running system.

The one idea: plan before execute

Pekit's guiding principle is predictability. Every command declares exactly which flags it accepts, every source declares what it can do, and every build is planned before any side effect happens. Before pekit clones a repository, runs a shell command, or writes a package, it has already resolved which recipe is selected, which source tree is needed, which versions apply, which build targets will run, and which artifacts will be produced.

That plan is inspectable. Add --dry-run to any command and pekit builds the same plan it would execute, prints it, and stops — no clones, no downloads, no writes. Strictness is the other half of the same idea: unknown flags, unknown recipe keys, and flags a command does not support are errors, caught up front, not halfway through a build.

The pipeline

A single invocation runs through a fixed sequence:

argv
  → invocation        parse and validate flags against the command
  → recipe            locate and load the recipe (walking up from the cwd)
  → versions          resolve the version selector into concrete versions
  → source            materialise the source tree for each version
  → delegation        merge any behaviour borrowed from the source tree
  → execute           run targets, or stage builds and write packages
  → artifacts         staged output and .peipkg files under out_dir

build, package, and publish may run this for several versions at once; test and install require the selector to resolve to exactly one.

The shape of a recipe

A recipe is a directory. At minimum it holds one file:

mypkg/
├── pekit.toml                 # the recipe: source, build/test/install/clean targets, env
├── package.pekit.toml         # what to package: files, symlinks, dependencies, metadata
├── packages.pekit/            # (optional) extra package members for multi-package recipes
├── env.pekit.toml             # (optional) reusable environment / wrapper definitions
└── prod.keyring.pekit.toml    # (optional) named keyring for signing and secrets

pekit.toml is the recipe proper — it declares the source, the build/test/install/clean targets, and shared environment. The package files describe how staged build output is mapped into one or more .peipkg payloads. A workspace.pekit.toml one level up turns a directory of recipes into a workspace that pekit can drive as a unit.

The Anatomy of a recipe page walks through every file; the recipe format reference is the exhaustive schema.

The commands

Seven commands, each with a defined job:

Command What it does
build Run build targets and their build dependencies.
test Stage the builds a test needs, then run test targets.
install Stage the builds an install needs, then run install targets.
package Stage builds and write .peipkg package artifacts.
publish Package, then publish the artifacts to a configured destination.
clean Run a clean target and/or remove pekit's managed output directory.
workspace Run any of the above across every member of a workspace.

The Commands and targets page covers what each command selects, its version behaviour, and how target selection works.

Where pekit fits

Pekit is the producer-side build tool. It stops at the .peipkg file. What happens next is other tools' work:

  • peipkg installs .peipkg files onto a live system.
  • peipkg-compose assembles a set of packages into an offline package root.
  • peiso turns a composed root into a bootable image.

Pekit produces packages in the peipkg format and understands peipkg concepts directly: recipes declare package dependencies, automatic ELF dependencies are scanned from built binaries, and packages can declare the shared-name claims they participate in. See Dependencies and claims.

Pekit supersedes the old peipkg-build recipe system. Earlier Peios used a peipkg.toml + build.sh recipe built by a separate peipkg-build binary. Pekit replaces that entirely; a pekit recipe (pekit.toml + package files) is the current and only supported way to build a package. Documentation describing peipkg-build and its build.sh recipes is legacy.

What to know before you start

A few facts about the tool as it ships today:

  • No --help yet. Pekit does not currently print usage text. This page and the invocation reference are the manual; the command and flag surface is documented in full there.
  • Exit status is 0 or 1. Pekit exits 0 on success and 1 on any error. It does not use finer exit codes.
  • Diagnostics go to stderr. Target output streams live to its normal streams; pekit's own events are timestamped on stderr, or structured when you pass --json.

Where to start

To learn the recipe format, begin with Anatomy of a recipe and follow the recipes section in order.

To use pekit against an existing recipe, read Commands and targets and Invocation and flags.

For the exhaustive schema and CLI surface, the reference section has one page per file format plus the full command-line reference.

See also