Skip to content

The crate map

A big workspace declares its structure in a crate map: the layers, which layers each may depend on, the layer of every crate, and a few properties per crate. The graph lints check the real cargo graph against it, edge by edge.

The map lives in spirit_level.toml as [map], or in its own file named by map-file.

[map.layers.utils]
desc = "Tiny helpers with no workspace dependencies outside utils"
allow = ["utils"]
licence = "MIT OR Apache-2.0"

[map.layers.model]
allow = ["utils", "model"]

[map.layers.app]
allow = ["utils", "model", "app"]
licence = "AGPL-3.0-only"

[map.crates]
foo_ids = { layer = "utils" }
foo_core = { layer = "model", deps = ["foo_ids"] }
foo_gpu = { layer = "app", unsafe = true }
foo_proto = { layer = "model", generated = true }
foo_api = { layer = "model", stable = true }
foo_math = { layer = "utils", no_std = true, deterministic = true }
foo_proto_types = { layer = "utils", contract = true }
foo_cli = { layer = "app", cli = true }
foo_ui = { layer = "app", ui = true }
foo_theme = { layer = "app", theme = true }
foo_fw = { layer = "app", tiers = ["embedded"] }
foo_gen = { layer = "app", workspace = "tools" }   # a member of the workspace in tools/
foo_fonts = { layer = "app", licence = "MIT OR Apache-2.0" }

[map.forbid]
foo_cli = ["foo_gpu", "wgpu"]       # the CLI never reaches these, directly or through others

[map.external]
exact_units = { git = "https://github.com/romixlab/exact_units", branch = "main", role = "utils" }

[map.third-party]
wgpu = ["foo_gpu"]                  # only these crates may depend on wgpu directly

Keys

Key Meaning
layers.<name>.allow layers its crates may depend on; list its own name when crates of one layer may see each other
layers.<name>.desc what lives in the layer
layers.<name>.licence the licence of its crates, an SPDX expression as license in Cargo.toml takes it (map-licence)
crates.<name>.layer the crate's layer (required)
crates.<name>.deps the workspace crates it may depend on; absent: any its layer allows
crates.<name>.discipline its discipline inside a large layer: the folder between the layer folder and the crate's own (crate-folder-layer)
crates.<name>.desc its description, when the map is where it is written
crates.<name>.licence its licence, where it differs from its layer's
unsafe may allow unsafe code, in a [lints] table of its own that copies the workspace lints; every other crate forbids it
generated generated code, checked in: exempt from size limits
stable a published, stable API: semver-checked
no_std builds without std
wasm builds for wasm32-unknown-unknown
deterministic promises bit-identical results on every platform
contract holds the serde types that cross a process or node boundary; sized integers only (sized-ints-in-contracts), a VERSION and a schema snapshot per version (contract-snapshot)
cli its binaries are command-line tools the CLI checks build and run; false leaves them out. Absent: a crate with a binary target that depends on clap is one
ui a user interface crate, held to the UI practices; absent: a crate that depends on a UI toolkit is one, false exempts such a crate
theme the theme crate: colours and sizes are written as values here and nowhere else in UI code
tiers tiers that hold this crate beside the project's own, such as ["embedded"] for a firmware crate (Tiers for some crates)
workspace the directory of the nested workspace the crate is a member of, relative to the project root; absent: a member of the checked workspace (Nested workspaces)
forbid.<crate> crates (workspace or third-party) its closure must never reach
external.<crate> a crate of another project taken by git: its URL, its branch (optional) and the layer that may use it; how it is pinned is git-dependency-pins' policy
third-party.<crate> workspace crates that alone may depend on a heavy third-party crate

Unknown keys are errors, like everywhere in the configuration; the next section is the one way around that. Dev-dependencies are exempt from the layer rule but not from forbid. To fix an edge that points the wrong way, move a crate; do not reorder the layers.

Nested workspaces

A repository may keep a second Cargo workspace beside the main one, such as its own tools in tools/ with their own Cargo.lock. Its crates go in the same map, each with workspace = "tools".

  • map-complete reads the members of every workspace the map names: a member missing from the map, an entry with no such member, a crate in another workspace than its entry says, and a named workspace that cargo cannot read are findings.
  • layer-edges, forbidden-closure, external-form, third-party-placement, unsafe-allow-list and map-licence check each nested workspace as they check the main one.
  • The other lints check the main workspace only. spl check tools checks a nested workspace on its own, with a spirit_level.toml of its own there.

A map another tool owns

A workspace whose own generator or linter reads the map keeps keys spl does not know beside spl's: a coverage cell, a release, an owning area, whole tables of its own. Name those keys in foreign, and spl leaves them to their owner:

[map-file]
path = "crates.toml"
foreign = ["meta", "domains", "deferred", "crates.*.cell", "crates.*.area", "crates.*.when"]
  • Each entry is a dotted key path; * stands for any one key, a crate's or a layer's name. A path that ends at a table hands the whole table over.
  • spl reads its own keys as everywhere else. A key that is neither spl's nor listed is an error, so a typo in an spl key (depz for deps) still stops the run, with the nearest key spl knows.
  • An entry that names a key spl reads (crates.*.deps) is an error: a key has one owner.
  • The owner checks its keys; spl never looks at them. map-file = "crates.toml" is the same table with no foreign entries.