| icon | circle-info |
|---|---|
| description | How packages are declared |
Packages in soarpkgs are declared in TOML. Nothing in the tree executes. A client resolves a package by parsing it, and verifies the download against a hash that was reviewed in a commit rather than measured after the fact.
Every package is a directory holding two kinds of file:
packages/<name>/
pkg.toml identity, metadata, update policy, how to find the artifact
<name>-<version>.toml the resolved URL, its hashes, and any side files
The recipe says where upstream publishes its artifact. The version file pins one release of it. sbuild turns the first into the second, and turns the whole tree into the index Soar reads.
recipe pkg.toml what upstream publishes, as a template
| resolve
version file <name>-<version>.toml one release, pinned by URL and hash
| meta
index metadata-<host>.json what Soar reads
A package may hold several version files. Each becomes its own entry in the generated index, so an older version stays installable after a newer one is pinned.
SBUILD was a YAML build script. It ran shell to produce a package, and the resulting hash was whatever that build happened to emit, recorded afterwards. It has been retired.
The declarative format drops the build step for everything upstream already publishes. The recipe names the release asset, and the hash of that asset is committed and reviewed like any other line in the repository. Anyone can check a package without trusting us: download the pinned URL, hash it, compare.
The handful of packages that genuinely need building are built in pkgforge/builds, which publishes ordinary GitHub releases that soarpkgs pins like any other upstream.
- Read the recipe reference and the version file reference
- Look at the examples, and at existing packages
- Scaffold a recipe with
sbuild new, fill it in, and open a pull request
The canonical spec lives with the tree it describes, in soarpkgs/docs/FORMAT.md. This section is the longer version of it.