Getting started

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. clean, gen, and verify skip the version and source stages entirely — they operate on the recipe directly.

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 #

Ten commands, each with a defined job:

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 also carries the supply-chain half of producing packages: fetched sources are pinned trust-on-first-use in a lockfile, upstream release signatures can be verified against committed keys, artifacts are Ed25519-signed, binaries can be PIP-signed for the kernel, and every manifest records the provenance of its inputs, recipe, and builder. See Signing and provenance.

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 complete flag surface is tabulated in the command-line reference.
• Exit status is 0 or 1. Pekit exits 0 on success and 1 on any error. It does not use finer exit codes.
• Events go to stdout. Pekit's own events print as timestamped lines on stdout (structured JSON with --json); a target's output streams through on its original stdout and stderr, and fatal errors go to stderr.

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.

This page takes you from an empty directory to a working .peipkg in about five minutes. You will write a two-file recipe, run pekit build, inspect the staged output, then run pekit package and look inside the artifact it writes. At the end you have a complete, minimal recipe you can grow into a real one.

Prerequisites #

• A pekit binary on your PATH. Pekit is a single binary built from its source repository with go build ./cmd/pekit; there is no separate installer. Note that pekit has no --help or version banner — the docs are the manual.
• A POSIX shell (sh). Target commands run under sh -euc; any Linux system has this.
• zstd and tar, for the final inspection step only.

Create the recipe #

A recipe is a directory, and only one file in it is required: pekit.toml. Make a directory and write the recipe:

$ mkdir hello && cd hello

# hello/pekit.toml
out_dir = "out"

[build]
command = '''
mkdir -p "$PEKIT_OUT/bin"
printf '#!/bin/sh\necho "Hello from Peios"\n' > "$PEKIT_OUT/bin/hello"
chmod +x "$PEKIT_OUT/bin/hello"
'''

Two things are going on here:

• out_dir names the directory pekit manages, relative to the recipe. Everything pekit stages or writes lands under it, and pekit clean may remove it wholesale — keep nothing precious there.
• [build] in this bare form defines a single build target named main. Its command is an ordinary shell script; pekit runs it with a set of PEKIT_* environment variables exported, of which the important one is $PEKIT_OUT — the target's own staging directory. A build's job is to put its artifacts in $PEKIT_OUT. Here the "build" just writes a shell script; a real recipe would run make, cargo build, or similar and copy the results in.

This recipe has no [source] section, so it builds against its own directory. Fetching real source trees is covered in Sources.

Run the build #

From hello/ (or any directory beneath it — pekit walks upward to find the nearest pekit.toml):

$ pekit build

You should see three timestamped lines, ending in success:

[14:30:01] [build] loaded recipe
[14:30:01] [main] running target
[14:30:01] [main] target succeeded

Nothing else prints because the build command itself is silent; anything your build writes to stdout or stderr is streamed through with a [build:main] prefix. Pekit exits 0 on success and 1 on any error.

Inspect the staged output #

Each build target stages into out/build/<target>/. Look at what the run produced:

$ find out -type f

out/.pekit/dependencies/build.main.json
out/build/main/bin/hello

out/build/main/ is target main's $PEKIT_OUT, and it now holds exactly what the command wrote (the out/.pekit/ entry is pekit's own bookkeeping). This staged tree is what packaging draws from. The script even runs:

$ out/build/main/bin/hello
Hello from Peios

Describe the package #

Packaging is declared in a second file beside the recipe. Write hello/package.pekit.toml:

# hello/package.pekit.toml
format = "peipkg"

[package]
name = "hello"
version = "0.1.0-1"
architecture = "noarch"
description = "A friendly greeting."
license = "MIT"

[files]
":bin/hello" = "usr/bin/hello"

The peipkg format requires [package].version, [package].architecture, and [package].license; the rest of the metadata is optional. The [files] table maps sources to destinations: the left side ":bin/hello" is a build ref meaning "bin/hello from build target main's staged output", and the right side is where the file lands inside the package. Destinations must sit under the peipkg layout's permitted top levels (usr/bin/, usr/share/, etc/, and so on) — see Packaging files.

Write the package #

$ pekit package

package stages the builds the package needs (re-running build.main), then writes the artifact:

[14:31:12] [package] loaded recipe
[14:31:12] [main] running target
[14:31:12] [main] target succeeded
[14:31:12] [main] wrote package: /home/you/hello/out/package/main-e33807f0ae9abdc7/hello_0.1.0-1_noarch.peipkg

The artifact is named <name>_<version>_<architecture>.peipkg and lands in a per-package stage directory under out_dir (the hash in the directory name is derived from the package's identity). Add --dry-run to any command to see this plan without writing anything.

Look inside #

A .peipkg is a Zstandard-compressed tar archive: reserved .peipkg/ metadata entries followed by the payload as it will be installed.

$ zstd -d --stdout out/package/main-*/hello_0.1.0-1_noarch.peipkg | tar tf -

.peipkg/manifest.json
.peipkg/files.json
usr/
usr/bin/
usr/bin/hello

That file is a real package: peipkg can install it, and pekit publish can copy it to a configured destination. To start over, pekit clean removes the whole out/ directory.

Where to go next #

• Anatomy of a recipe — every file in the recipe directory, all of pekit.toml's sections, and the full PEKIT_* environment contract.
• Commands and targets — the commands, named targets, needs ordering, target selection, and the gen/verify source-generation pair.
• Invocation and flags — the command line: --dry-run, --json, and how recipes are located.
• Recipe format reference — the exhaustive schema for pekit.toml and package files.