Foundation ports
Foundation ports are curated packages that adapt important existing C/C++ libraries - libraries
that do not yet ship a native cabin.toml - to Cabin’s build model. Their sources live in the
ports/ directory of the
cabin-ports/ports repository and are explicitly not a
public registry; that repository is closed to arbitrary submissions and its ports are intended to
be retired incrementally as upstreams adopt native cabin.toml.
cabinpkg.com lists the packages the hosted registry serves to everyone (The catalog); during the registry’s private alpha it lists none.
Consuming a foundation port
Foundation ports are consumed as ordinary registry packages under the cabin-ports scope:
[dependencies]
"cabin-ports/zlib" = "=1.3.1"
The dependency key needs quotes (scoped names contain /), and the requirement names the plain
upstream version: packaging revisions are not part of the
version string, and consumers pin them through the lockfile’s checksum instead. Registry
dependencies resolve through the hosted registry by default (no flag; see
remote-registry.md). The hosted registry is in private
alpha: it is restricted to its maintainer, so hosted foundation ports are not available to the
public yet, and resolving one fails with an explanation of that status. The recipes in
cabin-ports/ports stay public, and local builds and local file registries (--index-path) are
unaffected.
There is no port-specific dependency form. A port is an ordinary registry package, and a manifest
that tries to name one specially (port = true, port-path = "...") is rejected as an unknown
dependency field.
Anatomy of a foundation port
A port is an ordinary Cabin package directory: one cabin.toml, plus a patches/ subdirectory
when it declares any and a tests/ consumer test when it has one.
ports/<prefix>/<name>/<version>/
cabin.toml - the published manifest: scoped identity,
[package.upstream] provenance, and the
upstream sources described as Cabin targets
patches/ - optional unified-diff files declared by
[package.upstream].patches
tests/ - optional consumer test the preflight probe
compiles and runs; never published
<prefix> is the first two characters of <name>, as in ports/zl/zlib/1.3.1/.
The manifest publishes verbatim, so its committed bytes are the published bytes - a comment
edit changes the published archive. Its identity must agree with the directory layout: <name>/
fixes [package].name at exactly cabin-ports/<name>, so the directory is itself a valid package
name, and <version>/ fixes [package].version. A port may declare only unconditional registry
dependencies: no system = true, no path or workspace sources, and no cfg(...) dependency
table, because publication ordering reads the declared edges without evaluating conditions. The
publisher refuses each of these with a message naming it.
Provenance
Every port declares [package.upstream]: the pinned archive URL,
its algorithm-prefixed checksum, the container format, an optional strip-prefix, declarative
[[package.upstream.copy]] placements, and declared patches. There is no port-specific
provenance vocabulary - that published table is the whole of it, and
manifest.md is its normative reference.
Zip support exists for upstreams whose only official release artifact is a zip (miniz’s
amalgamation, for example); prefer .tar.gz when the upstream publishes one.
Manifest
zlib’s manifest declares a single library target with the 15 canonical zlib C sources and the
archive root on the include path. The target key is the artifact stem, so it is z (producing
libz.a / z.lib), not zlib. A port is a published package, so it declares the
license of the upstream sources it ships:
[package.upstream]
url = "https://github.com/madler/zlib/releases/download/v1.3.1/zlib-1.3.1.tar.gz"
checksum = "sha256:9a93b2b7dfdac77ceba5a558a580e74667dd6fede4585b91eefb60f03b72df23"
format = "tar.gz"
strip-prefix = "zlib-1.3.1"
[package]
name = "cabin-ports/zlib"
version = "1.3.1"
license = "Zlib"
[target.z]
type = "library"
sources = [
"adler32.c", "compress.c", "crc32.c", "deflate.c",
"gzclose.c", "gzlib.c", "gzread.c", "gzwrite.c",
"infback.c", "inffast.c", "inflate.c", "inftrees.c",
"trees.c", "uncompr.c", "zutil.c",
]
include-dirs = ["."]
c-standard = "c11"
links = "z"
Library ports claim the native identity they embody via links (zlib
claims "z", libpng claims "png"), judged against upstream conventions - the identity, not the
target key, and only where a real native library exists. Header-only ports claim nothing, and an
alternative implementation with its own symbol namespace claims its own identity (miniz claims
"miniz", not "z": its objects export only mz_* symbols).
Materialization pipeline
A port materializes through
cabin_artifact::materialize_upstream - the one upstream-provenance
materialization pipeline, and the same implementation the hosted registry’s external verifier
replays against a published package’s [package.upstream] declaration. What publishes is
therefore assembled by exactly what verifies:
- Fetch the pinned archive. Published provenance pins a credential-free
https://URL, downloaded via the same HTTP clientcabin-index-httpuses, with a five-hop redirect budget. Following redirects is safe because the declared SHA-256 is verified against the final response bytes, and upstream release archives commonly hop from a forge (e.g. GitHub) to a CDN. Compressed archives larger than 64 MiB are refused by the HTTP client; no foundation port currently approaches that limit. A cached archive already hashing to the pin short-circuits the download, so repeat invocations stay network-free. - Verify the archive’s SHA-256 against the declaration.
- Safely extract the archive with the declared
strip-prefix, under the full extraction safety contract - decompression-bomb caps, path-traversal protection, duplicate and conflicting entries - applied identically to both formats. - Apply the declared
[[package.upstream.copy]]steps, placing prebuilt files under their build-time names inside the extracted tree. - Apply the declared
patchesas byte-exact unified diffs, then place each patch file itself into the tree at its declared path, so the published archive carries the patches its declaration names. - Write the committed
cabin.tomllast, so an upstream archive shipping its own root manifest can never displace the published one.
Every step is declarative: no commands run, and the only inputs are the pinned archive and the
port’s own committed files - its cabin.toml and its declared patches. The result is an ordinary
Cabin package directory, which is what the publisher packages and uploads. A port whose upstream
archive carries documentation or test trees consumers never build lists the paths they need in
[package] include (for example include = ["include", "src"], plus
"patches" when it declares patches), which keeps the rest out of the published archive; the
verifier expects only those paths.
Cache layout
Pinned upstream archives live under the same root the rest of Cabin’s artifact cache uses:
<cache>/ports/
archives/sha256/<hex>.tar.gz (or <hex>.zip for zip sources)
The cache root resolution follows the documented chain: --cache-dir - > CABIN_CACHE_DIR - >
CABIN_CACHE_HOME - > $XDG_CACHE_HOME/cabin - > $HOME/.cache/cabin. The default on a Unix-like
system with no overrides is $HOME/.cache/cabin/, so the example layout above lives at
~/.cache/cabin/ports/archives/sha256/<hex>.tar.gz. The cache is shared across projects on the
same machine - content is checksum-addressed, and every entry is re-hashed against the declared
pin before use, so a stale or corrupt entry is a miss, never a substitution.
What foundation ports are not
- Not Cabin’s public registry. Cabin’s registry layer is documented in
registry-design.mdand evolves independently. - Not a private metadata dialect. A port’s provenance is the ordinary
[package.upstream]table every package may declare (manifest.md), which the hosted registry’s external verifier checks against the pinned upstream archive. - Not a submission queue. New foundation ports require a curated review; this directory is intentionally small.
- Not a vehicle for binary distribution. Only source archives are supported.
- Not a place for build scripts. Ports describe libraries whose source layout
already fits Cabin’s target model (a fixed list of sources plus include directories), optionally
placing a prebuilt file with a static
[[package.upstream.copy]]step or correcting one with a declared byte-exact patch. A registry package’s build script runs for whoever depends on it, but no port carries one, so libraries that need configure-time generation, CMake / Meson / Autotools driving, or custom build commands are not ported. A port whose upstream archive ships a rootbuild.corbuild.cppdeletes that file with a declared patch: the verifier refuses an upstream file as a build script (upstream_build_script). - Not a variant-selection mechanism. A published port carries whatever
[features]its manifest declares (cabin-ports/sqlite3ships asingle-threadedfeature), but nothing in the port vocabulary selects a shared or static build.
Error catalog
Every diagnostic below is refused by the publisher before anything is uploaded. The first group is refused during planning, before any port is staged; the symlinked-patch and cache-miss diagnostics come from materialization, which may already have extracted a scratch tree (the publisher owns and clears that whole scratch root).
| Diagnostic | Trigger |
|---|---|
must publish under the `cabin-ports` scope | [package].name carries a different scope, or none. |
disagrees with its `<name>/` directory | [package].name is not cabin-ports/<name> for the port directory’s name. |
disagrees with its `<version>/` directory | [package].version does not equal the version directory’s name. |
package directory `<name>/` | The port directory’s name is not a valid package name ([a-z0-9][a-z0-9_-]*); the message suggests the lowercase spelling when that alone fixes it. |
declares no [package.upstream] provenance | The manifest has no provenance table; every port is materialized from a pinned upstream archive. |
declares the system dependency | A dependency sets system = true; a port resolving through host pkg-config would make its published build host-dependent. |
depends on ... through a non-registry source | A dependency uses a path or workspace source. |
may only depend on other `cabin-ports/*` packages | A registry dependency names a package outside the scope. |
under a cfg-conditional table | A dependency sits in a [target.'cfg(...)'.dependencies] table; ordering does not evaluate conditions. |
which no committed port version satisfies | A declared requirement matches no version published in the same run. |
inter-port dependency cycle among | The declared edges do not form a DAG. |
is not a regular file / is a symlinked directory | A manifest or port directory is a symlink; published bytes must be the committed files. |
is (or crosses) a symlink | A declared patch path resolves through a symlink. |
no cached archive for ... and downloads are disabled | A hermetic (cache-only) staging run found no archive matching the declared SHA-256. |
Provenance-shape diagnostics - an unparsable or non-HTTPS URL, a malformed SHA-256, an unsafe
strip-prefix, copy, or patch path, an inapplicable patch - come from the manifest parser and the
shared materializer, and are catalogued with
[package.upstream] itself.
Publishing ports as registry packages
The port-publish tool of cabin-ports/ports, a
repository-owned package that is not part of the shipped cabin binary, publishes every port
committed there as an ordinary registry package under the cabin-ports scope, verbatim from
the manifest committed in it. The rules that manifest must meet:
- Identity.
cabin-ports/<name>, declared by the manifest itself, with<name>spelled exactly as the port directory (cjson/declarescabin-ports/cjson; the upstreamcJSONspelling stays in the upstream URL and sources). The publisher refuses a directory that is not a valid package name and a manifest that declares any other name. The published version is the upstream version, verbatim. - Target keys. A target key directly determines its artifact stem, so a port states the
intended native artifact name directly:
cabin-ports/zlibkeys its sole library targetz(producinglibz.a/z.lib),cabin-ports/googletestkeys its targetgtest. No target mangling and no output-name mechanism exist; the key is the stem. - Links identities. A declared
linksclaim is independent of the target key. The two often coincide (z,png) but need not -cabin-ports/catch2keys its targetcatch2while claiming"Catch2", upstream’s case-sensitive library name. The post-resolution uniqueness check reads the published claims from the index. - Provenance. A port declares
[package.upstream],[[package.upstream.copy]], and[package.upstream].patchesitself and publishes them verbatim, so the hosted registry’s verifier can check the published tree against the upstream archive. The patch files themselves ship inside the published package at their declared paths. - Dependencies. A published port names its dependencies as scoped registry packages
(
cabin-ports/libpngdepends on"cabin-ports/zlib" = "^1.3"), and targetdepsreferences use the bare-package shorthand when the dependency exposes exactly one library-like target, or an explicitpackage:targetselector otherwise. - Order. Publication order derives from those declared edges (zlib publishes before libpng), and they enter the cycle and satisfiability checks like any other package’s.
Each version stands alone - published verbatim and probed on its own targets - so two versions of
one port may expose different library targets. The preflight probe links the library targets
available with the package’s default features: one gated behind a non-default
required-features entry still publishes, but the probe does not compile it, because the probe
enables no extra features. A target declaring interface-cxx-standard = "none" is linked by a C
consumer and the rest by a C++ one, so a package mixing the two is probed from both languages; one
of the rest that declares an interface-c-standard other than "none" is linked by the C
consumer as well.
Each probe compiles at the lowest standard the linked targets’ declared interfaces accept (c11 /
c++17 when they declare no interface), except that an MSVC host raises a floor below C11 / C++14 to
those: cl.exe has no /std: flag for C99 or C++11.
--dry-run and --publish run the local preflight first: fetch or reuse every pinned upstream
archive (SHA-256 verified, reusing the standard <cache>/ports archive cache), run the standard
safe materialization pipeline (extraction, strip-prefix, copy steps, patches),
package each port and publish it into a temporary file registry in publication order, and build
every port against the generated packages. A dry-run given --changed-since <rev> or
--port <name> narrows that to a selection after validating the whole catalog (that repository’s
docs/maintaining.md, “Selective dry-runs”); --publish never narrows it. The probe
builds run in parallel, one worker per CPU
with two build jobs each, each probe starting as soon as its port is staged; a failure still
reports the earliest failing port in publication order, and a successful run ends with each phase’s
time summed over the ports and the slowest ports. Each port is built through a generated probe
package that depends on the
just-published version, so the build consumes the registry artifact itself - resolution, checksum,
archived manifest, source materialization, and compilation of every compiled library target.
Exercising a port’s API (including its headers, calling its symbols) needs per-library
knowledge a generic converter does not have, so that knowledge is committed in the port: a probe
consumer compiles the port’s tests/main.cc (or tests/main.c for the C consumer) when it has
one, and an empty main otherwise; any other file in tests/ except a dotfile (a misspelled name,
or main.c for a port with no C consumer) fails the preflight rather than being
skipped. --dry-run then runs every probe, and a non-zero exit fails the preflight, so a consumer
test is an ordinary program that returns non-zero on failure. --publish builds the probes but
never runs them: running upstream code in the job that holds the trusted-publishing OIDC token
would hand that code the token, so running them is the pull-request dry-run’s job. Packaging
copies only the manifest and its declared patches from the port directory, so tests/ is never
published: editing a test changes no archive bytes.
$ cargo run --locked -- --dry-run --cabin <cabin>
$ cargo run --locked -- --publish --cabin <cabin> --index-url https://registry.cabinpkg.com
Run them from a cabin-ports/ports checkout. <cabin> is a cabin binary built from the Cabin
commit the tool’s own Cabin crates are pinned to; that repository’s CONTRIBUTING.md (“Checks”)
has the commands that install it.
--dry-run stops after the preflight. --publish preflights every port (building, not
running, the probes) and then uploads
every package through the registry API in publication order, in consecutive batches of 50 (sized
for the operator quota class’s publish rate): each batch is one cabin publish invocation, which
under GitHub Actions exchanges for its own trusted-publishing token and revokes it, best-effort, on
exit, so a large set never rides one token’s 30 minutes. A failed batch - including one slow
enough to outlive its token - stops the run before the next one and fails it; the next
--publish resumes by uploading every package again. It never skips a version based on the
public index - pending (not yet verified) revisions are hidden there - and instead relies on the
registry’s idempotency rule: re-publishing byte-identical bytes is a no-op. Every upload
passes --new-revision, because a change that has been merged to main is the deliberate
respin (see Packaging revisions) - which is why editing a port’s
manifest or patches changes the published bytes; an unchanged tree still produces byte-identical
archives, so a rerun stays a no-op either way.
Publish automation
The cabin-ports/ports workflows automate the tool. Every pull request and merge-queue run there
runs the --dry-run preflight with no secrets, on Linux, macOS, and Windows (ci.yml), with the
Cabin commit the tool is pinned to. That pin moves only when a ports maintainer adopts a newer
Cabin commit through such a pull request (that repository’s docs/maintaining.md, “Cabin
revision”). A change that only adds new package names, editing at most the files “Selective
dry-runs” there names (documentation such as README.md, and publish-holds.txt) besides,
preflights every version of those names and their dependency closure. A change that only edits
those files preflights nothing. Any other change preflights the whole catalog: a new
version of an existing port, any edit under an existing port, the Cabin pin, the tooling, or
CI. Every run still loads and validates the whole catalog first. Cabin’s own CI runs no
full-catalog dry-run - its scheduled real-upstream example tests and benchmarks build only the ports
they use - so a Cabin change is checked against every port only once that pin adopts it: a green
Cabin CI run promises nothing about building every port.
Only main publishes, through publish.yml, and only to https://registry.cabinpkg.com (a run
on any other ref publishes nothing). A dispatch in its default mode publishes the whole set, so a
correction to an already-published port reaches the registry at the next such dispatch - and the
same dispatch is the recovery path after a pre-launch registry wipe. While that repository’s
PORTS_AUTO_PUBLISH variable is true, a schedule also uploads versions that have not been
uploaded yet, never a packaging revision (that repository’s docs/publishing.md, “Automatic
publishing”). A run first waits for a registry deploy whose
Cabin commit contains the one the tool is pinned to, so the client never sends metadata the
running registry does not accept. Dispatching with the exchange-check input
instead exchanges and immediately revokes a trusted-publishing token, proving the registered
binding end to end while publishing nothing. Upload jobs are serialized and queued, never
cancelled; a whole-set run superseded by a newer commit on main skips its upload instead
of immutably publishing an intermediate state, and the whole set is not published again until the
next dispatch. The check runs before the publish command’s own preflight, which still takes
minutes - a commit landing inside that residual window
can make a stale run publish first, in which case the next dispatch’s differing bytes land as a
new packaging revision (see below) rather than overwriting anything, never silent divergence.
Once that repository’s receipts log exists, a run whose upload failed is not resumed by a rerun:
it keeps the log’s lock, and nothing uploads again until an operator reconciles it (its
docs/publishing.md, “Reconciling the log”).
The publish job holds no long-lived credential: it grants permissions: id-token: write, and
cabin publish exchanges the run’s own OIDC token for a short-lived registry token confined
to the cabin-ports scope, revoking it on the way out (see
Trusted publishing; which workflows may exchange is
operator-registered registry data). Upstream archives restored from the CI cache are never trusted: the
tool re-hashes every cached archive against the checksum its port’s [package.upstream] pins,
and re-downloads on a mismatch. The cabin-ports GitHub organization owns that repository and
is the registry scope’s authority; registered trusted publishing admits only its publish.yml
on main.
Packaging revisions
A published version always preserves the upstream version, and the bytes published under it are
immutable. A packaging-only correction - a manifest fix, a [[package.upstream.copy]] addition, a
new or revised patch under [package.upstream].patches - therefore reaches the
registry as a new packaging revision of the same version:
the archive’s changed bytes give it a new revision id, and both revisions stay listed and
fetchable. There is no version-string marker and no sidecar file to maintain; edit the port’s
committed cabin.toml and merge it. It publishes verbatim, so a comment is a byte change like
any other.
Consumers are unaffected until they ask to be. A lockfile that already pins the old revision keeps
resolving its graph and fetching exactly those bytes; a fresh resolution, or an explicit
cabin update, picks up the corrected revision.
Because a whole-set publish always passes --new-revision, the merged change is the intent
signal - including an edit to the committed manifest itself, which publishes verbatim. A correction landing on main is by construction a deliberate respin,
and a rerun over an unchanged tree still produces byte-identical archives and stays a no-op. A
respin may also correct what resolution consumes - the published package’s dependencies,
features, standards, or links: each revision keeps its own, so the old revision’s pins keep
their graph. The package’s index document then becomes schema 2, which earlier clients refuse
rather than misread.
The pinned catalog
The repository-root ports-revision file pins one commit on the main branch of
cabin-ports/ports as a test input: the real-upstream
example tests, cargo perf run --ports, and cargo fuzz-seeds read the ports of that commit, and
neither the cabin CLI nor the website reads it. They take the ports/ directory of a checkout of
the pinned commit, which must be on main:
$ git clone https://github.com/cabin-ports/ports ../cabin-ports
$ git -C ../cabin-ports merge-base --is-ancestor "$(cat ports-revision)" origin/main
$ git -C ../cabin-ports checkout --detach "$(cat ports-revision)"
$ FOUNDATION_PORTS_DIR=../cabin-ports/ports cargo test --test cabin_examples -- --ignored
$ cargo perf run --ports ../cabin-ports/ports
$ cargo fuzz-seeds --ports ../cabin-ports/ports
The catalog those consumers see changes only through a pull request that moves the pin to a newer
commit on that repository’s main.
Retiring a foundation port
When an upstream project ships and maintains a native cabin.toml, the corresponding foundation
port should be retired. The retirement steps are:
- Switch downstream
[dependencies]entries from"cabin-ports/<name>"to the appropriatepath/version/workspaceform pointing at the new upstream-maintained package. - Delete the
ports/<prefix>/<name>/<version>/directory. - Note the retirement in the relevant release notes.