Skip to main content
Documentation menu

Dependency kinds

Cabin classifies every dependency into one of three kinds, each declared under its own manifest section:

SectionKindWhat it means
[dependencies]normalLinked into ordinary builds.
[dev-dependencies]devFor tests / examples / local development tasks.
[build-dependencies]buildTools 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 --offline cover 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 test activates them as real graph edges for the selected primary packages so test executables can link against test-only packages - see docs/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:gen enables an optional gen, and gen/x requests feature x of 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 evaluates cfg(...) for the build machine.
  • links uniqueness 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 (CFLAGS and friends). With --target, it uses the build machine’s own toolchain, chosen by HOST_CC, HOST_CXX, and HOST_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

CommandBehavior
cabin addAdds 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 removeDeletes a named entry from [dependencies] (or [dev-dependencies] with --dev); removes the table when it becomes empty. Errors if the dependency is absent.
cabin metadataReports each dependency with its dependency_kind.
cabin resolve / update / fetchWalks normal and build deps; excludes dev deps.
cabin buildSame 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 testWalks 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 packageIncludes per-kind dependency tables in the canonical metadata document.
cabin publish --dry-runValidates the same metadata; never touches the registry.
cabin publish --registry-dirPublishes 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).