Dependency kinds
Cabin classifies every dependency into one of three kinds, each declared under its own manifest section:
| Section | Kind | What it means |
|---|---|---|
[dependencies] | normal | Linked into ordinary builds. |
[dev-dependencies] | dev | For tests / examples / local development tasks. |
[build-dependencies] | build | Tools built for the build machine; never linked into the dependent. |
A library the machine already holds, such as one an OS package manager installed, is not a kind of
its own: a package’s build script supplies it, and that package is declared under whichever section
fits. See system-dependencies.md.
Every kind also accepts the platform-conditional form [target.'cfg(...)'.<kind>]. Resolution
and the lockfile include the declaration whatever its condition; the build evaluates the condition
for the platform it builds for (the build machine, or the --target platform) and leaves
non-matching declarations out. The full grammar and
evaluation rules live in target-dependencies.md.
Manifest syntax
[package]
name = "demo"
version = "0.1.0"
[dependencies]
fmt = ">=10 <11"
[dev-dependencies]
gtest = "^1.14"
[build-dependencies]
gen = { path = "../gen" }
[dependencies], [dev-dependencies], and [build-dependencies] accept the following value forms:
- bare version-requirement string (
name = ">=10"), { version = "..." },{ path = "../local" },{ workspace = true }(looks up the matching[workspace.<kind>-dependencies]table - see below).
Resolver behavior
The Cabin resolver runs over the union of dependency kinds that participate in ordinary commands:
- Normal dependencies - included.
- Build dependencies - included, with everything they reach, so
cabin.lock,fetch,vendor,--locked, and--offlinecover build tools. A package used as a build tool and as a library resolves to one version for both. - Dev dependencies - excluded by default. Declaration only for ordinary commands. They
round-trip through metadata but are not resolved, fetched, or built.
cabin testactivates them as real graph edges for the selected primary packages so test executables can link against test-only packages - seedocs/testing.md. The activation never propagates: a transitive dep’s own dev-deps stay declaration-only.
The same package name may appear under multiple kinds (e.g. a package used both as a normal dep and
as a dev dep). The resolver sees the normal- and build-kind requirements during ordinary commands;
cabin test joins the selected packages’ dev-kind requirements on top.
Build dependencies
A build dependency is a tool for the build machine, such as a code generator. Cabin builds its package in the build context, apart from the packages it links for the platform it builds for (the target context):
- The build dependency’s default targets (libraries and executables), or the targets its entry
lists in
targets, and the packages they link are built for the build machine, under<build-dir>/<profile>/build-machine/packages/<pkg>/. A package both contexts use is built twice, once per context, and the two never share objects. - Features unify per package within a context, never across: an edge in one context cannot turn on a feature of the other context’s copy.
- A
[features]entry that names a build dependency reaches the build machine’s copy:dep:genenables an optionalgen, andgen/xrequests featurexof it. When the package also lists the name under[dependencies], the entry applies to both declarations, each in its own context. - A
[target.'cfg(...)'.build-dependencies]condition is evaluated for the platform of the package that declares it; everything inside the build context evaluatescfg(...)for the build machine. linksuniqueness applies per context: a build tool and the program may each link one package claiming an identity, but neither may link two.- Without
--target, the build context uses the build’s compilers and environment flags (CFLAGSand friends). With--target, it uses the build machine’s own toolchain, chosen byHOST_CC,HOST_CXX, andHOST_AR, and no environment flags. See toolchains.
A build-dependency entry may name the targets to build with targets:
[build-dependencies]
gen = { path = "../gen", targets = ["gen"] }
The build machine then builds the listed targets, and the libraries a listed executable links,
instead of the dependency’s other targets. Each name must be a library, header-only, or executable target of that dependency;
an unknown name, a test or example target, or a target whose required-features the build context
leaves off is an error. When several edges reach one dependency, the build machine builds every
listed target, plus the default targets if any edge omits targets. A member’s
{ workspace = true } entry may add targets. targets is rejected on [dependencies] and
[dev-dependencies], and an empty list is an error. cabin metadata reports the list as the
dependency’s targets.
cabin build, run, and test build build dependencies. What runs a build dependency’s
executable, or links its library, is the package’s build script; without one,
the build runs nothing. A package taken from a registry has its build dependencies resolved,
fetched, and built the same way, for the build script its index entry
declares. cabin check checks
only the selected packages’ own sources, and builds build dependencies only when a build script has
to run first.
Lockfile behavior
The lockfile records resolved package versions; dependency-kind metadata is not duplicated there because the resolver re-runs from the manifest on every command and re-decides which kinds to include.
Workspace dependency inheritance
[workspace] roots may declare shared requirements per kind:
[workspace]
members = ["packages/*"]
[workspace.dependencies]
fmt = ">=10"
[workspace.dev-dependencies]
gtest = "^1.14"
[workspace.build-dependencies]
gen = "^1"
A member then opts into the workspace requirement with { workspace = true }:
[package]
name = "app"
version = "0.1.0"
[dependencies]
fmt = { workspace = true } # looks up [workspace.dependencies]
[dev-dependencies]
gtest = { workspace = true } # looks up [workspace.dev-dependencies]
The lookup is strictly kind-specific: a { workspace = true } under [dev-dependencies] does
not fall back to [workspace.dependencies]. If the matching workspace table does not declare the
dependency, Cabin reports an explicit error naming the section pair.
Command behavior
| Command | Behavior |
|---|---|
cabin add | Adds an entry to [dependencies] (or [dev-dependencies] with --dev), preserving the manifest’s formatting and comments. Writes registry deps (<scope>/<name>@<req> - the scoped name and an explicit requirement are both required, because cabin add never queries the registry for names or versions) and local path deps (--path <dir>). --features / --no-default-features set those fields. Prints a note reminding you to add the dependency to a target’s deps to link it (declaring it here only makes it available - see Command behavior above). |
cabin remove | Deletes a named entry from [dependencies] (or [dev-dependencies] with --dev); removes the table when it becomes empty. Errors if the dependency is absent. |
cabin metadata | Reports each dependency with its dependency_kind. |
cabin resolve / update / fetch | Walks normal and build deps; excludes dev deps. |
cabin build | Same resolution as above. Only normal-kind edges link into ordinary C/C++ targets - dev and build deps cannot resolve through target.<X>.deps. Build deps build for the build machine (see Build dependencies). |
cabin test | Walks normal deps plus [dev-dependencies] of the selected primary packages, so test targets can depend on test-only packages. Dev-dep activation never propagates to transitive deps. |
cabin package | Includes per-kind dependency tables in the canonical metadata document. |
cabin publish --dry-run | Validates the same metadata; never touches the registry. |
cabin publish --registry-dir | Publishes the per-kind metadata into the local file registry. |
Output ordering is deterministic in every command: dependency kinds iterate in canonical order
(normal, dev, build), and names sort ascending within each kind.
Package and index metadata
cabin package emits a canonical per-version metadata document that round-trips dependency kinds.
The on-disk shape is:
{
"schema": 1,
"name": "demo",
"version": "0.1.0",
"dependencies": { "fmt": ">=10 <11" },
"dev-dependencies": { "gtest": "^1.14" },
"build-dependencies": { "gen": "^2" },
"yanked": false,
"checksum": "sha256:...",
"source": { "type": "archive", "path": "...", "format": "zip" }
}
Empty kind tables are omitted, so manifests that only use [dependencies] produce the exact
byte-for-byte metadata they always did.
The local file index and the sparse HTTP index carry the same dependency tables. They differ only
in where the archive identity sits: an index version entry replaces the document’s top-level
checksum / source with the per-revision map described in
package-index.md.
Optional dependencies
Cabin package dependencies in [dependencies] and [build-dependencies] may declare
optional = true:
[dependencies]
openssl = { version = "^3", optional = true }
Optional dependencies only enter ordinary resolution / fetch / build when a feature enables them via
dep:<name> or <name>/<feature> from [features]. Until then they appear in package / index
metadata but never in the resolver’s selection or the lockfile. Per-edge features = [...] and
default-features = false are also supported and are applied additively across all dependency edges
that include the same package - see features.md for the full feature-resolution
behavior.
An optional build dependency is built for the build machine, and offered to the package’s
build script, only once enabled. optional = true is not supported on
[dev-dependencies]. The manifest layer reports the violation as OptionalNotSupportedForKind.
Scope
- Registry optional dependencies follow feature requests. Dependency resolution unifies the
feature requests on every selected edge, local or registry, and enables a registry package’s
optional dependencies exactly when those features do (see
features.md).