Principle:Nautechsystems Nautilus trader Cargo Manifest Conventions
| Knowledge Sources | |
|---|---|
| Domains | Build_Tooling, Rust |
| Last Updated | 2026-02-10 08:00 GMT |
Overview
A set of enforced rules governing Cargo.toml structure, dependency ordering, and version alignment across a multi-crate Rust workspace.
Description
Cargo Manifest Conventions define a strict schema for how all Cargo.toml files in a large Rust workspace must be organized. In a project with 40+ crates spanning core libraries and exchange adapters, unchecked manifests lead to dependency version drift, undiscoverable configuration, and inconsistent build behavior. This principle codifies nine rules covering section ordering, dependency alphabetization, lint configuration, documentation suppression for binaries, package field ordering, crate-type ordering, unused dependency detection, version alignment for related crate families, and adapter dependency isolation.
Usage
Apply this principle in any Rust workspace with more than a handful of crates where manual manifest review is impractical. It is especially important when workspace dependencies are centralized and multiple crate families (e.g., capnp/capnpc, arrow/parquet) must stay version-aligned.
Theoretical Basis
The enforcement model is a rule-based static analysis over TOML structure:
# Abstract algorithm (NOT real implementation)
for cargo_toml in workspace_manifests:
ast = parse_toml(cargo_toml)
for rule in [ordering, sections, lints, docs, fields, types, unused, alignment, isolation]:
violations += rule.check(ast)
if violations:
fail("Cargo manifest conventions violated")
Key invariants enforced:
- Dependency groups are alphabetically sorted — prevents merge conflicts and improves readability
- Related crate versions are aligned — prevents ABI/API incompatibility at compile time
- Workspace lints are inherited — ensures uniform clippy/rustc lint configuration
- Adapter dependencies are isolated — prevents core crates from acquiring adapter-specific transitive dependencies