cabin.toml Reference
This document describes the cabin.toml schema currently understood by the manifest parser, the
workspace loader, the build planner, the resolver, and the artifact layer.
Registry packages declared with versioned dependencies must, after fetch and extraction, contain a
valid cabin.toml at the archive root. cabin-artifact rejects an extracted package whose
[package].name or [package].version disagrees with the resolved entry. See
artifacts.md for the source-archive contract.
Top-level structure
A manifest may contain these top-level sections:
- at most one
[package]table - zero or more
[target.<name>]tables - zero or more
[target.'cfg(...)'.<kind>]conditional dependency or toolchain tables - zero or more
[target.'cfg(...)'.profile]general conditional flag layers - zero or more
[target.'cfg(...)'.profile.<name>]named conditional flag overlays - zero or more
[target.'cfg(...)'.sources]platform-conditional target sources (see Targets) - zero or one
[dependencies]table - zero or one
[dev-dependencies]table - zero or one
[build-dependencies]table (see Dependency kinds) - at most one
[workspace]table - at most one
[features]table - at most one
[profile]table plus[profile.<name>]tables - at most one
[toolchain]table - at most one
[patch]table - at most one
[standard-header-shadowing]table
A manifest must contain at least one of [package] and [workspace]. Package-specific tables such
as targets, dependencies, features, conditional dependency, source, and profile flag tables, and
the flag fields of the bare [profile] table require [package]; without it they are rejected.
Workspace policy tables such as [workspace], [profile.<name>], [toolchain], [patch], and
[standard-header-shadowing] may appear on a workspace root without [package].
Naming convention: manifest field names and value strings are kebab-case (include-dirs,
header-only, opt-level, dev-dependencies). The single exception is cfg(...) predicate keys
(target_os, cc_version, cxx_version), which follow the cfg grammar’s snake_case convention.
[package]
name = "my-project"
version = "0.1.0"
cxx-standard = "c++17"
[dependencies]
greet = { path = "../greet" }
fmt = ">=10.0.0 <11.0.0"
[target.my-app]
type = "executable"
sources = ["src/main.cc"]
deps = ["greet", "fmt"]
[package]
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Package name: a bare <name> or a scoped <scope>/<name> with exactly one /. <name> matches [a-z0-9][a-z0-9_-]*: lowercase ASCII letters, digits, _, and -, starting with a letter or digit. The scope has its own grammar: lowercase letters, digits, and interior - only, at most 39 characters (a claimable GitHub login). Uppercase and . are rejected, and names are compared exactly, never case-folded. Each part names a build directory, so neither may be a Windows device name (con, prn, aux, nul, com1 to com9, or lpt1 to lpt9); the registry refuses the same names. Registry packages are always scoped; bare names are local-only and rejected by cabin publish. |
version | string | yes | Valid SemVer string. |
license | string | no | SPDX license expression describing the package’s licensing, such as "MIT OR Apache-2.0". Omitted means unspecified. A package that is published must declare it; see license. |
c-standard | string | no | Package-wide C implementation standard (c89, c99, c11, c17, c23; c90 is an alias of c89). There is no built-in default: every target that compiles C sources needs an effective value from this field or its own [target.<name>] override. See Language standards. |
cxx-standard | string | no | Package-wide C++ implementation standard (c++98 … c++26; c++03 is an alias of c++98). There is no built-in default: every target that compiles C++ sources needs an effective value from this field or its own [target.<name>] override. |
interface-c-standard | string or { min, max } table | no | Package-wide default C interface requirement for library / header-only targets: a string minimum ("c11"), a bounded inclusive range ({ min = "c99", max = "c17" }, max optional), or "none" (headers not consumable from C). |
interface-cxx-standard | string or { min, max } table | no | Package-wide default C++ interface requirement for library / header-only targets; same forms as the C field. |
gnu-extensions | boolean | no | Package-wide default for the per-target GNU-extensions dialect knob (default false). See Language standards. |
include | array of strings | no | The files and directories, relative to the package root, that cabin package archives besides the root cabin.toml and the root build script; omitted, the whole tree is archived. Each entry is a literal forward-slash path (no . or .. component, no trailing /, and no * or ?); list the patches directory too when the package declares patches. See Package format. |
Inside a workspace, each of the four standard fields also accepts the { workspace = true } opt-in
form, inheriting the literal declared on the workspace root’s [workspace] table - see
Language standards. gnu-extensions has no marker form.
Source-language classification stays per-file (target kinds, .c vs .cc extensions - see
Targets); the standard each language compiles with is governed by the fields above and
their per-target overrides (Language standards).
license
An optional SPDX license expression describing the licensing of the package’s contents.
[package]
name = "acme/coro"
version = "1.0.0"
license = "Apache-2.0 AND (GPL-3.0-or-later WITH GCC-exception-3.1)"
| Form | Meaning |
|---|---|
MIT | One license from the SPDX License List. Identifiers are matched case-sensitively. |
Apache-2.0+ | That version of the license or any later one. GNU licenses have dedicated identifiers for this (GPL-3.0-only, GPL-3.0-or-later); prefer them to the deprecated GPL-3.0+ spelling, which is still accepted. |
MIT OR Apache-2.0 | Either license, at the recipient’s choice. |
MIT AND BSD-3-Clause | Both licenses apply. |
GPL-3.0-or-later WITH GCC-exception-3.1 | A license modified by an exception from the SPDX exceptions list. |
LicenseRef-<id>, AdditionRef-<id> | A license, or an exception after WITH, that is on neither SPDX list. <id> consists of ASCII letters, digits, -, and .; either form may carry a DocumentRef-<id>: prefix. |
WITH binds tighter than AND, which binds tighter than OR; parentheses group explicitly.
Cabin validates the expression whenever it loads the manifest, against the SPDX lists bundled with
that Cabin release. A malformed expression, or an identifier that is on neither list, fails the
load with a diagnostic that names the offending term. Terms are separated by plain spaces; tabs,
line breaks, and other whitespace are rejected. Identifiers the SPDX list has deprecated (such as
GPL-2.0) are still accepted, so a deprecation never invalidates a published package; prefer the
current identifiers. An identifier added to the SPDX lists after a Cabin release is unknown to that
release, which rejects a manifest declaring it, a dependency’s included, until Cabin is upgraded.
Cabin keeps the expression exactly as written and never normalizes it.
A package that is only built locally may omit the field. A published package must declare it:
cabin publish, including --dry-run, refuses a manifest without one before any registry work,
and the hosted registry refuses an upload without one. A version entry published before this
requirement may lack a license; index readers still load such entries during the hosted registry’s
private alpha and require the field before the public launch.
The field is a declaration, and Cabin treats it as metadata only:
- An omitted
licensemeans unspecified. It does not mean the package is in the public domain or free of license terms, and Cabin never infers a value from source files or dependencies. - The expression describes the licensing of what the package ships. Cabin checks its syntax and identifiers, not its accuracy. It never accepts, rejects, or prefers a package because of its license, and it does not evaluate license compatibility across a dependency graph.
- Declaring a license does not satisfy the license’s conditions. License texts, copyright notices, and attribution files must still be distributed as their licenses require; the field does not replace them.
Tools can read the declaration without unpacking a source archive:
cabin metadatareports it aslicenseon each package inpackages(the workspace’s members and local-path dependencies).cabin packageandcabin publish --dry-runwrite it to the canonical metadata document (package-format.md).- A registry’s package index carries it on each version entry, as
versions.<version>.licensein the package’s index document (package-index.md). This is how to read the license of a registry dependency, on a file registry and on the hosted registry alike.
cabin metadata and cabin package omit the key for a package that declares no license, and so
does an index entry published before a license was required.
[package.upstream]
An optional machine-verifiable claim that the package’s source tree came from a pinned upstream archive. The URL must be credential-free HTTPS and the archive format is declared explicitly, never inferred from the URL. Every foundation port declares one.
[package.upstream]
url = "https://example.com/library-1.2.3.tar.gz"
checksum = "sha256:1f9d0a4b2c8e63b7f0d5a9c8e7b6a5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8"
format = "tar.gz"
strip-prefix = "library-1.2.3"
patches = ["patches/0001-fix-msvc-build.patch"]
[[package.upstream.copy]]
from = "scripts/config.h.prebuilt"
to = "config.h"
The assembly pipeline is fixed and normative: extract the archive, strip the declared prefix, apply the copy steps in declaration order, then apply the patches in declaration order. Every step is a declarative, deterministic transformation - never a script or build hook.
| Field | Type | Required | Description |
|---|---|---|---|
url | string | yes | HTTPS URL of the pinned upstream archive, at most 2048 bytes. Other schemes and URLs embedding credentials are rejected. |
checksum | string | yes | Algorithm-prefixed checksum of the archive bytes. The value is self-describing: exactly sha256: followed by 64 lowercase hexadecimal characters (sha256 is the only supported algorithm today). |
format | string | yes | Archive container format: "tar.gz" or "zip". |
strip-prefix | string | no | Single directory component stripped from every archive entry before comparison; omit it when the archive root is the source root. Must be a portable component the extractor could accept (no / or \, at most 254 bytes so a child entry fits the 256-byte path cap, none of the Windows-hostile shapes). |
patches | array of strings | no | Unified-diff patch files applied to the assembled tree after every copy step, in declaration order. Each entry is a plain portable forward-slash relative path naming a file inside this package (the patch ships in the published archive; cabin package refuses to stage a declaration whose file is absent). At most 16 entries and at most 1 MiB per file; an entry must not duplicate, case- or normalization-collide with, or nest with a copy path, another patch, or the root cabin.toml. A patch names each file at most once, each patched file is capped at 16 MiB, and the whole list may carry at most 1024 file entries and read or rewrite at most 128 MiB of the tree in total. Application is byte-exact - fixed -p1 strip, no fuzz, no offset search, no newline normalization, text diffs only (binary hunks are rejected) - and paths inside diff headers must resolve safely within the assembled tree. A patch file must contain nothing but the diff itself (git’s per-file preamble lines are accepted in their exact shape; commit-message text or any other surrounding content is rejected - use git diff output, not git format-patch): patch files are exempt from the registry’s upstream tree comparison, so their bytes must never be able to double as compilable source. Note the key must appear before any [[package.upstream.copy]] table. |
[[package.upstream.copy]] | array of tables | no | Declarative file placements applied to the extracted upstream tree, in declaration order: copy from to to. Both are plain forward-slash relative paths with portable components (no absolute paths, no . / .. components, no \), from and to must differ (including under case folding), steps’ paths must not case-collide or nest one under another, at most 16 steps are accepted, and strip-prefix plus / plus from must fit the 256-byte archive entry-path cap. Static file-to-file copies only - never a build script or codegen hook. |
The declaration is inert for consumers: resolving, fetching, and building a package never touch the
upstream URL. It rides through the package’s canonical metadata and registry index entries
(package-format.md), and the hosted registry’s external verifier downloads
the pinned archive and requires the published source tree to match it
(remote-registry.md). The pinned archive must be at
most 256 MiB: the verification pipeline downloads it under that cap, and a larger archive cannot be
verified - its versions stay pending until an operator intervenes.
[target.<name>]
The table key (<name>) is the target name. Target names must be non-empty, must not contain
whitespace, must consist only of ASCII letters, digits, _, -, and ., must not start with .
or -, must not be . or .., and must be unique within the manifest. This grammar is separate
from, and looser than, the package-name grammar. A target name also names the target’s output files
and object directory, so on every platform it must not:
- end with
., which Windows drops, sotool.would writetool’s files; - have a Windows device name before its first
.-CON,PRN,AUX,NUL,COM1toCOM9, orLPT1toLPT9, in any letter case (nul,Con.txt);COM0andLPT0are not device names; - differ from another target name in the manifest only in letter case: a case-insensitive filesystem
(the Windows and macOS default) would give
Toolandtoolthe same files.
Mixed-case names and internal dots are fine (MyTool, tool.v2). Before writing any output, a
build also refuses two outputs that would land on one path, or one output’s file where another needs
a directory: an executable named libfoo.a beside a library foo (GCC/Clang names the archive
libfoo.a), an executable named obj (the object directory), or one source listed twice. Paths
one letter case apart count as one where the build directory’s filesystem ignores letter case, as
Windows’ and macOS’s do by default, and stay apart where it does not, as on Linux or a
case-sensitive macOS volume, so C foo.c and C++ foo.C both build there. Cabin tells by looking
up an entry of the profile’s output directory under its name with letter case swapped, or, before
that directory exists, an entry of its nearest existing parent, whose setting a new directory
inherits (Linux casefold and Windows per-directory case sensitivity included); the build directory
holds Cabin’s lock file by then. A directory holding nothing to look up, a failed lookup, or an
entry whose swapped name is a second entry counts as ignoring letter case. The answer covers the
whole output tree: a directory in it given another setting by hand, or a symlink in it to another
volume, is not looked up on its own.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | string | yes | - | Target kind. One of library, header-only, executable, test, example. Each kind describes artifact role only; a target may freely mix .c and C++ sources. See Targets. |
sources | array of strings | no | [] | Source files, relative to the manifest directory (no ..). |
include-dirs | array of strings | no | [] | Additional include directories, relative to the manifest directory (no .., no absolute paths). A dependency’s entries reach its consumers’ compile lines, so they may never point outside the declaring package. |
defines | array of strings | no | [] | Preprocessor definitions for this target’s own compiles, e.g. "FOO=1"; never reach consumers. Rejected on header-only, which compiles nothing. |
interface-defines | array of strings | no | [] | Preprocessor definitions for consumers’ compiles, not this target’s own: NAME or NAME=value, NAME a C identifier, no control characters; library / header-only only. List a macro in both fields when the target’s own sources need it too. See Edge visibility. |
deps | array of strings or tables | no | [] | Target dependencies. A string entry declares a private edge; the table form adds per-edge visibility: { name = "foo", public = true }. See Target dependencies. |
required-features | array of strings | no | [] | Package features (declared in this package’s [features] table) that must all be enabled for this target to be built or used. Unknown names are rejected at manifest load. See Feature-gated targets. |
c-standard | string | no | package value | Per-target C implementation standard override. See Language standards. |
cxx-standard | string | no | package value | Per-target C++ implementation standard override. |
interface-c-standard | string or { min, max } table | no | effective c-standard | C interface requirement: a string minimum, a bounded { min, max } range, or "none"; library / header-only only. A header-only target must have at least one interface standard (either language, target or package level). |
interface-cxx-standard | string or { min, max } table | no | effective cxx-standard | C++ interface requirement; same forms as the C field; library / header-only only. |
gnu-extensions | boolean | no | package value, else false | Per-target GNU-extensions dialect override. |
links | string | no | - | Native-library identity this target claims, e.g. "z" for a target embodying zlib; library only. See links. |
instruction-sets | table | no | {} | x86 instruction sets one of this target’s C or C++ sources may use beyond the platform baseline, keyed by its path: { "src/sum_avx2.c" = ["avx2"] }. See Per-source instruction sets. |
include-dirs of a library or header-only target apply to its own compiles and, with its
interface-defines, to every target that depends on it - transitively only along public edges
(Edge visibility).
links
links = "<identity>" declares that the target embodies the named native library. The claim is an
explicit opt-in and is never derived from the target name: target names are artifact stems, while a
links value names the native identity, and the two can legitimately differ (a target ssl may
link "openssl"). Identities are non-empty, case-sensitive strings of ASCII letters, digits, .,
_, +, and -.
After dependency resolution, Cabin refuses a graph in which two distinct packages of one context -
the program’s, or the build tools’ of build dependencies -
claim the same identity, because duplicate native symbols fail at the final link regardless of
dependency visibility - the check sees private edges too. The diagnostic names the shared identity
and every claimant (package, version, target); keep exactly one claimant per context, or move the
extras behind features so they never resolve together. Platform conditions do not separate claimants, because resolution
covers every platform. Claims are declared, not selection-aware: a target whose required-features
are disabled still claims, but a package reachable only through a disabled optional dependency does
not. Resolution unifies feature requests across the two contexts, so an optional dependency that
either context’s features enable claims in every context that reaches the package declaring it.
Resolution refuses collisions among the claims of everything it selects: local claims under the
selected features and the claims of every selected registry package and [patch] fork, including
a fork’s optional dependencies that its dependents’ feature requests enable. The building commands
re-check the final loaded graph.
links is uniqueness enforcement only. There is no metadata passing between packages and no
build-hook integration, and only library targets may claim (header-only targets emit no linkable
artifact, so two wrappers of one library must not conflict).
[dependencies]
[dependencies]
# Local path dependency
greet = { path = "../greet" }
# Versioned dependency, string form
fmt = ">=10.0.0 <11.0.0"
# Scoped registry dependency: `/` is not a bare-key character,
# so the key must be quoted
"fmtlib/fmt" = ">=10.0.0 <11.0.0"
# Versioned dependency, table form
spdlog = { version = "^1.13.0" }
# Foundation port - an ordinary scoped registry package
"cabin-ports/zlib" = "=1.3.1"
Each entry declares a package-level dependency. The dependency value is either:
- a string - interpreted as a SemVer requirement;
- a table - must specify exactly one source:
path,version, orworkspace = true. The source may be combined withfeatures,default-features,optional,ignore-interface-standard, or, on build dependencies,targets(see Dependency kinds), subject to per-source rules below. Unknown keys are rejected by the manifest parser.
Foundation ports have no dependency form of their own: they are published
registry packages, named like any other ("cabin-ports/zlib" = "=1.3.1").
The dependency key (greet, fmt, spdlog above) must equal the depended-on package’s
[package].name (path deps) or the registry package name (version deps), and follows the
package-name grammar. Registry dependency keys are always the scoped <scope>/<name> name:
cabin publish rejects a bare versioned dependency key in [dependencies] or
[dev-dependencies] (dev-dependency keys denote registry packages too - they resolve when
building the package’s own tests), and the hosted registry enforces the same rule server-side.
ignore-interface-standard
ignore-interface-standard = true exempts exactly this dependency edge from the
post-resolution standard-compatibility check (see
language-standards.md).
The check still evaluates the edge and prints a downgraded note that the edge is unchecked, so the
override cannot silently rot. An override declared in a registry dependency’s own manifest
belongs to that dependency’s maintainers, so its note prints only at verbose output (-v,
CABIN_TERM_VERBOSE, or [term] verbose); an override in the root package, a workspace member,
or a path or [patch] package always prints it. The exemption covers this check only: the always-on build-time
interface enforcement is unaffected, so it can unblock the interface-"none" and cross-language
violation classes but not interface-range violations - below the declared minimum or above the
declared maximum - which that enforcement independently rejects. The field is deliberately per-edge: there is no package-wide or global variant. It is accepted on every package-sourced
form (path, version, workspace) in [dependencies] and [dev-dependencies].
Version requirement syntax
Cabin uses the semver crate for parsing, with one extra
convenience: comparators may be separated by whitespace as well as by commas. Recognized forms:
- exact / compatible:
=1.2.3,1.2.3(treated as^1.2.3per cargo’s convention) - comparisons:
>1.2.3,>=1.2.3,<1.2.3,<=1.2.3 - combined:
>=1.2.3 <2.0.0or>=1.2.3, <2.0.0 - caret:
^1.2.3,^0.2.3,^0.0.3 - wildcard:
*
Other syntaxes (~1.2.3, npm-style OR ||, pre-release metadata, …) are not part of the
documented surface and may or may not work depending on what the semver crate accepts.
[features]
Public, additive, named-boolean capabilities. The reserved default key holds the list of features
Cabin enables when --no-default-features is not passed.
[features]
default = ["simd"]
simd = []
ssl = []
full = ["simd", "ssl"]
Rules:
- feature names must be non-empty ASCII letters / digits /
_/-;/,.,:, and whitespace are rejected; - a feature value is a list of feature names (possibly empty); every referenced name must be a declared feature in the same package;
- cycles are rejected;
- declaring a normal feature called
defaultis rejected.
Feature entries may also use dep:foo to enable an optional package dependency, or
dependency/feature to request a feature on a dependency package. See features.md
for the full resolver semantics.
[workspace]
[workspace]
members = ["packages/*", "tools/hello"]
A cabin.toml with a [workspace] table is a workspace root. Member patterns may be:
- exact relative paths (
tools/hello); the directory must contain acabin.toml; - a single trailing-
*glob (packages/*); every immediate subdirectory ofpackages/that contains acabin.tomlbecomes a member.
More complex glob syntaxes (**, ?, multiple *s) are intentionally not supported.
The workspace table accepts these additional fields, all optional:
exclude- paths or trailing-*globs removed from the member set even when matched bymembers;default-members- the subset of members commands operate on when no package-selection flags are passed at the workspace root;[workspace.dependencies],[workspace.dev-dependencies], and[workspace.build-dependencies]- shared version requirements that member entries reference withdep = { workspace = true };c-standard- shared C implementation-standard default (literal value only) that member packages opt into per field withc-standard = { workspace = true };cxx-standard- shared C++ implementation-standard default (same opt-in form);interface-c-standard- shared C interface-requirement default (same opt-in form);interface-cxx-standard- shared C++ interface-requirement default (same opt-in form). See Language standards.
See workspaces.md for member expansion, selection flags, and inheritance
semantics.
[standard-header-shadowing]
[standard-header-shadowing]
allow = ["acme/polyfill"]
A build refuses a registry package with a file directly in one of its include-dirs, or in an
include directory its build script reports, that a C or C++ standard library
header include would open - its name matches the header’s ignoring letter
case, or the host file system resolves the header’s name to it - because every compile that
depends on the package would open that file instead of the standard header. Implementation-internal
headers (__config, bits/*, sys/cdefs.h, …) are not checked: this guards against accidental
collisions such as an upstream VERSION file, not against a malicious dependency (see
Standard header shadowing). allow lists the registry
packages exempt from that refusal, for a package meant to provide standard headers, such as a
polyfill. The table is read only from the workspace root manifest and ignored in member,
path-dependency, and registry manifests, so a dependency cannot exempt itself.
Target dependencies
Inside a target’s deps array, each entry is a reference string or a table wrapping one:
"name"- a same-package target. When no local target matches andnameis a declared package dependency, the entry resolves to that dependency’s solelibraryorheader-onlytarget, whatever it is named -"zlib"linkszlib:zwhenzis the only library targetzlibdeclares, and a scoped"fmtlib/fmt"resolves the same way. Non-library targets (such as executables) are never candidates. A dependency that declares several library or header-only targets makes the bare name ambiguous - a hard error listing the qualified candidates - and one that declares none has nothing a bare name could link; both cases require the explicitpackage:targetspelling."package:target"- qualified reference. Thepackagepart must be either the current package or a declared package dependency; thetargetpart must exist in that package. This is the only spelling for a non-library dependency target, and the required one when the dependency declares several library or header-only targets.{ name = "<reference>", public = <bool> }- table form.nametakes either reference spelling above;public(defaultfalse) declares the edge’s visibility. A string entry is exactly equivalent to{ name = "<reference>", public = false }.
Edge visibility
Every dependency edge is private unless the entry declares public = true:
[target.net]
type = "library"
sources = ["src/net.cc"]
deps = [
"util", # private edge
{ name = "fmt", public = true }, # public edge, bare dependency package
{ name = "foo:opt", public = true } # public edge, qualified reference
]
Rule of thumb: an edge is public iff the target’s public headers include headers of that
dependency. If only the target’s .c / .cc files include the dependency’s headers, the edge
is private. Visibility applies to the resolved edge - the bare-name shorthand resolves first, so
{ name = "fmt", public = true } declares a public edge to the fmt package’s sole library
target.
Visibility decides which compiles see a dependency’s consumer interface - its include-dirs,
interface-defines, and interface standards (Language standards):
- a private edge applies it to the depending target’s own compiles only;
- a public edge applies it there too and re-exports it to that target’s consumers, and theirs, as long as the chain of edges stays public.
So with app -> net -> util above, app compiles against net’s interface but not util’s,
while fmt’s reaches app through the public edge. Linking ignores visibility: every library in
the dependency closure joins the final link of each executable that depends on it, private edges
included, in dependency order (dependents first).
Two dependencies that reach one compile with different values for the same macro fail the build,
naming both dependency paths; agreeing values (FOO and FOO=1) count once. A target’s own
defines and its package’s [profile] defines override an incoming interface definition of the
same macro.
A consumer that includes a header reachable only through another target’s private edge (as
app reaches util above) misses it - or, worse, silently finds a system copy of it while
linking the dependency’s archive. The fix depends on who
includes the header:
when the consumer’s own sources do, it declares that dependency itself; when a library’s public
headers do, the library marks its edge public. A registry library needs a corrected release (or
packaging revision) for the latter. No linter flags under-declaration yet.
Declaring a package under [dependencies] only makes it available; nothing links until a target
names one of its targets in deps. Features never add deps entries either - a
consumer that wants a feature-gated target both enables the
feature and lists the target explicitly.
Versioned dependencies resolve through the configured local or sparse HTTP index and are
materialized through the artifact cache when a buildable graph needs them. Resolved versioned
dependencies are recorded in cabin.lock next to the manifest - see
docs/lockfile.md.
Validation
The parser and downstream tools reject manifests when:
- the manifest contains neither
[package]nor[workspace] [package].name/[package].versionis missing or invalid- a package name or dependency key is outside the package-name grammar (the diagnostic suggests the lowercase spelling when that alone would make it valid)
- a name is empty or contains whitespace
- a target’s
typeis unknown - the same target name appears twice
- a
linksvalue is empty or contains a character outside ASCII letters, digits,.,_,+, and- - a
linkskey appears on a non-librarytarget - two targets of one package claim the same
linksvalue [package].licenseis not a valid SPDX license expression (seelicense)- the same dependency key appears twice
- a dependency entry has neither
path,version, norworkspace - a dependency entry combines mutually exclusive source forms
- a dependency entry sets
system, which Cabin no longer reads - a versioned dependency requirement is not parseable
- a referenced local manifest does not exist
- a dependency key does not match the referenced package’s name
- two loaded packages share a
[package].name - the package or target dependency graph contains a cycle
- a
[package.upstream]table has a non-HTTPS or credential-bearingurl, achecksumthat is notsha256:followed by 64 lowercase hexadecimal characters, aformatother than"tar.gz"/"zip", astrip-prefixthat is not a single relative path component, more than 16 copy steps, or a copy step whosefrom/tois not a plain portable forward-slash relative path or names the same file twice - a
[package.upstream]patcheslist has more than 16 entries, an entry that is not a plain portable forward-slash relative path, or an entry that duplicates, case-collides with, or nests with a copy path, another patch, or the rootcabin.toml
Example - direct version dependency
[package]
name = "app"
version = "0.1.0"
[dependencies]
fmt = ">=10.0.0 <11.0.0"
Resolving versioned dependencies uses --index-path / --index-url, the [registry] config
setting, or - when none of those apply - Cabin’s default hosted registry
(remote-registry.md).
Example - local path dependency
# app/cabin.toml
[package]
name = "app"
version = "0.1.0"
[dependencies]
greet = { path = "../greet" }
cabin build works; no resolver involvement is needed.
Example - mixed
[package]
name = "app"
version = "0.1.0"
[dependencies]
greet = { path = "../greet" }
fmt = ">=10.0.0 <11.0.0"
cabin metadata reports both. cabin resolve --index-path index resolves fmt; cabin build --index-path index fetches and builds the resolved dependency when its archive metadata is present.
Example - workspace
# Workspace root cabin.toml
[workspace]
members = ["packages/*"]
# packages/app/cabin.toml
[package]
name = "app"
version = "0.1.0"
[dependencies]
greet = { path = "../greet" }