Vendoring and offline mode
cabin vendor materializes the external versioned dependencies the selected packages need into a
deterministic local file-registry directory. The output is an ordinary Cabin file registry, the
same shape cabin publish --registry-dir writes, so every existing read-path command knows how to
consume it without any new protocol.
The core offline-consumption workflow is:
cabin vendor # populate ./vendor
cabin build --offline --index-path ./vendor # build with no network
cabin fetch --offline --index-path ./vendor # populate the cache offline
cabin test --offline --index-path ./vendor can use the vendored registry only when the selected
tests do not require additional registry packages from [dev-dependencies]; the vendor sweep
follows the same selection policy as cabin build and does not include dev-only dependencies.
What cabin vendor produces
The default vendor directory is vendor/ next to the project manifest. Pass --vendor-dir <path>
to override it.
The directory layout is the existing Cabin file registry:
vendor/
config.json # {"schema":2, "kind":"file-registry", ...}
packages/<scope>/<name>.json # per-package version index
archives/<scope>/<name>/ # verified source archives
<scope>-<name>-<version>-<revision>.zip
cabin-vendor.json # deterministic summary of this run
A bare-name package (from a legacy source registry) keeps the flat shape: packages/<name>.json
and archives/<name>/<name>-<version>-<revision>.zip.
A vendor directory written by the Cabin 0.18.0 release or earlier uses the file registry’s
schema 1 and is refused: delete it and run cabin vendor
again, or, without network access, edit its config.json as that section describes.
cabin-vendor.json records the (name, version, checksum, artifact) set this invocation wrote, in
stable (name, version) order. Re-running cabin vendor against the same inputs produces a
byte-identical summary.
A vendor directory reproduces exactly the packaging revision
the lockfile pins, including one that has since been superseded upstream. Each vendored version
entry therefore lists only the fetched revision, as its current one, with source.path rewritten to
the vendored artifact; the superseded siblings’ archives are not in the directory, so nothing there
can silently resolve to different bytes. A vendored superseded revision’s entry carries no
license: the index records that field for the current revision only, and the superseded
revision’s own declaration is in its archive’s cabin.toml.
Every archive is re-verified against the checksum recorded in the source index; a checksum mismatch surfaces as an explicit error and never overwrites the destination.
Selection
cabin vendor accepts the same selection bundle as cabin build / cabin fetch:
cabin vendor --workspace
cabin vendor -p app
cabin vendor --workspace --exclude lldb
cabin vendor --features simd,ssl
cabin vendor --no-default-features
cabin vendor --no-patches
Only the packages reachable from the resolved selection are vendored. A workspace member you did
not pick is ignored. cabin vendor matches the cabin build policy: dev dependencies are not
vendored unless they are in the selection’s build closure.
Locked, frozen, and offline semantics
| Flag | Lockfile | Artifact cache | Vendor directory | Network / HTTP index source |
|---|---|---|---|---|
| (default) | written | populated | written | not used; HTTP index rejected |
--locked | required, kept | populated | written | not used; HTTP index rejected |
--frozen | required, kept | not populated | written (explicit output) | not used; HTTP index rejected |
--offline | written | populated | written | forbidden |
cabin vendor reads per-package metadata from a local file-registry index so the documents it
copies into the vendor directory are byte-stable. The rule applies to the index source left after
[source-replacement]: --index-path, [registry] index-path, or a [registry] index-url that a
[source-replacement] entry maps to a local index-path all vendor. When the replacement chain
ends at an HTTP URL, cabin vendor refuses before any network attempt; it never vendors from an
HTTP index. Under --offline a configured index-url is refused before replacement applies, as
for every other command, so pass the local index with --index-path instead.
cabin vendor --frozen is the documented “rebuild a vendor directory from the existing artifact
cache without touching the lockfile or refreshing the cache” flow. The vendor directory is the
explicit user-requested output of the command, so it is still written under --frozen; the
lockfile and the artifact cache are not.
--offline and --frozen compose: cabin vendor --offline --frozen succeeds when the closure is
fully cached and the lockfile is current, and fails with an actionable diagnostic otherwise.
Patches and source replacement
cabin vendor honors every patch / override mechanism:
- Manifest
[patch]entries point at a local working copy. Patched packages do not flow through the resolver and are therefore not vendored - the vendor directory is for the registry-supplied versions only. Consumers of the vendor directory still see the patched local copy because the manifest’s[patch]table is read from the consuming project, not from the vendor directory. - Config
[patch]/[source-replacement]is honored identically. --no-patchesdisables the entire local-policy layer for the vendor invocation - the resolver picks the registry versions and Cabin vendors those.
Local path dependencies (dep = { path = "../local" }) are not copied into the vendor
directory. They remain local references; the consuming project must continue to provide them on
disk. cabin vendor does not invent a packaging path for local sources because publishing them
would require a different identity contract (no checksum / no index entry).
C/C++ first-class support
Vendored builds preserve every C/C++ contract documented in docs/toolchains.md and
docs/targets.md:
- CC and CXX remain separate;
cflags/cxxflags/ldflagskeep their argv-space separation;- C/C++ standard flags do not leak across language slots;
- the link driver is selected per target by the planner regardless of how the dependency’s archive was sourced;
- public include directories propagate from a vendored dependency to its consumers exactly as they would from a registry consumer;
- a system library is not vendored: the build script of the package that supplies it still looks for the library on the machine when the build runs.
Because vendoring re-uses the existing artifact pipeline, every fingerprint input documented in
docs/toolchains.md continues to participate in BuildConfiguration::fingerprint for vendor
builds.
Scope
cabin vendor operates on the registry-package closure of the resolved selection. Local path
dependencies are not copied into the vendor directory, and the command mirrors cabin build’s
closure policy (dev dependencies are not swept).
Direct ninja invocation
cabin build --offline --index-path ./vendor regenerates build.ninja and compile_commands.json
from the vendored inputs every time. Direct ninja -C <build-dir> invocations still work for
incremental rebuilds. Ninja reads the generated files; it does not re-read cabin.toml, config
files, or environment changes. Run cabin build after manifest / config / toolchain edits so the
build configuration fingerprint and the generated commands reflect the new inputs.
Environment variables
cabin vendor shares the fetch / index / artifact-cache / offline environment policy used by the
dependency-fetching pipeline. It does not resolve a compiler toolchain or build anything, so CC,
CXX, AR, CFLAGS, CXXFLAGS, LDFLAGS, and LD are not consumed by cabin vendor itself.
Subsequent build commands that use the vendored index still honor their normal toolchain and profile
environment policy.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
--offline forbids network access, but the resolved index source is the URL … | A [registry] index-url config setting is active. | Pass --index-path <vendor-dir> or remove the URL setting from the active config. |
--offline forbids network access, but no index source is configured, so versioned dependencies would resolve through the default registry … | Nothing names an index, so the default hosted registry applies. | Pass --index-path <vendor-dir> (a cabin vendor output) and re-run. |
cabin vendor requires a local index source … | The index source left after [source-replacement] is a URL. | Pass --index-path, map the URL to a local index-path with [source-replacement], or fix the offending entry. |
vendor directory already contains <path> with checksum sha256:… which does not match … | A previous run left a stale archive on disk. | Delete the offending file (or the whole vendor/archives/<scope>/<name>/ subdir) and re-run. |
refusing to vendor through symlink <path> inside the vendor directory … | A symlink inside the vendor directory, or a default vendor/ that is itself a symlink (for example one a checkout shipped). | Remove the symlink and re-run. To vendor into a symlinked directory on purpose, name it with --vendor-dir. |
checksum mismatch while vendoring … | The artifact in the cache no longer matches the index’s recorded checksum. | Clear the cache (--cache-dir <new-dir>) or refresh the index, then re-run cabin vendor. |
vendoring requires the source index to expose <name>'s metadata at … | The local --index-path is missing per-package metadata. | Re-publish the package with cabin publish --registry-dir <dir> so the file appears. |