Skip to main content
Documentation menu

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]

FieldTypeRequiredDescription
namestringyesPackage 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.
versionstringyesValid SemVer string.
licensestringnoSPDX 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-standardstringnoPackage-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-standardstringnoPackage-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-standardstring or { min, max } tablenoPackage-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-standardstring or { min, max } tablenoPackage-wide default C++ interface requirement for library / header-only targets; same forms as the C field.
gnu-extensionsbooleannoPackage-wide default for the per-target GNU-extensions dialect knob (default false). See Language standards.
includearray of stringsnoThe 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)"
FormMeaning
MITOne 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.0Either license, at the recipient’s choice.
MIT AND BSD-3-ClauseBoth licenses apply.
GPL-3.0-or-later WITH GCC-exception-3.1A 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 license means 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 metadata reports it as license on each package in packages (the workspace’s members and local-path dependencies).
  • cabin package and cabin publish --dry-run write it to the canonical metadata document (package-format.md).
  • A registry’s package index carries it on each version entry, as versions.<version>.license in 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.

FieldTypeRequiredDescription
urlstringyesHTTPS URL of the pinned upstream archive, at most 2048 bytes. Other schemes and URLs embedding credentials are rejected.
checksumstringyesAlgorithm-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).
formatstringyesArchive container format: "tar.gz" or "zip".
strip-prefixstringnoSingle 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).
patchesarray of stringsnoUnified-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 tablesnoDeclarative 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, so tool. would write tool’s files;
  • have a Windows device name before its first . - CON, PRN, AUX, NUL, COM1 to COM9, or LPT1 to LPT9, in any letter case (nul, Con.txt); COM0 and LPT0 are 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 Tool and tool the 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.

FieldTypeRequiredDefaultDescription
typestringyes-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.
sourcesarray of stringsno[]Source files, relative to the manifest directory (no ..).
include-dirsarray of stringsno[]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.
definesarray of stringsno[]Preprocessor definitions for this target’s own compiles, e.g. "FOO=1"; never reach consumers. Rejected on header-only, which compiles nothing.
interface-definesarray of stringsno[]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.
depsarray of strings or tablesno[]Target dependencies. A string entry declares a private edge; the table form adds per-edge visibility: { name = "foo", public = true }. See Target dependencies.
required-featuresarray of stringsno[]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-standardstringnopackage valuePer-target C implementation standard override. See Language standards.
cxx-standardstringnopackage valuePer-target C++ implementation standard override.
interface-c-standardstring or { min, max } tablenoeffective c-standardC 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-standardstring or { min, max } tablenoeffective cxx-standardC++ interface requirement; same forms as the C field; library / header-only only.
gnu-extensionsbooleannopackage value, else falsePer-target GNU-extensions dialect override.
linksstringno-Native-library identity this target claims, e.g. "z" for a target embodying zlib; library only. See links.
instruction-setstableno{}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 = "<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, or workspace = true. The source may be combined with features, 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.3 per cargo’s convention)
  • comparisons: >1.2.3, >=1.2.3, <1.2.3, <=1.2.3
  • combined: >=1.2.3 <2.0.0 or >=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 default is 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 a cabin.toml;
  • a single trailing-* glob (packages/*); every immediate subdirectory of packages/ that contains a cabin.toml becomes 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 by members;
  • 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 with dep = { workspace = true };
  • c-standard - shared C implementation-standard default (literal value only) that member packages opt into per field with c-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 and name is a declared package dependency, the entry resolves to that dependency’s sole library or header-only target, whatever it is named - "zlib" links zlib:z when z is the only library target zlib declares, 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 explicit package:target spelling.
  • "package:target" - qualified reference. The package part must be either the current package or a declared package dependency; the target part 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. name takes either reference spelling above; public (default false) 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].version is 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 type is unknown
  • the same target name appears twice
  • a links value is empty or contains a character outside ASCII letters, digits, ., _, +, and -
  • a links key appears on a non-library target
  • two targets of one package claim the same links value
  • [package].license is not a valid SPDX license expression (see license)
  • the same dependency key appears twice
  • a dependency entry has neither path, version, nor workspace
  • 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-bearing url, a checksum that is not sha256: followed by 64 lowercase hexadecimal characters, a format other than "tar.gz" / "zip", a strip-prefix that is not a single relative path component, more than 16 copy steps, or a copy step whose from / to is not a plain portable forward-slash relative path or names the same file twice
  • a [package.upstream] patches list 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 root cabin.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" }