skip to content

As a lead, how do you decide how finely to split a Rust codebase into crates in a Cargo workspace, and what does each extra crate cost?

level: principalimportance: should knowfreq 27%

answer

  1. the crate is the compilation unit
  2. edits rebuild everything downstream
  3. wide graph versus deep chain
  4. orphan rule, proc-macro crates
  5. measure with --timings

basics

~20 s

Split where it buys something measurable: crates Cargo can compile in parallel, a stable base that edits above it do not rebuild, isolated heavy dependencies, enforced API boundaries. Each crate costs a manifest, a public API, possible orphan-rule friction and lost inlining.

solid answer

~40 s

The crate is rustc's unit of compilation, so granularity is mostly a build-graph decision. Cargo compiles independent crates in parallel, and an edit recompiles that crate plus every crate that depends on it. So split where the graph gets **wider** (siblings that build at once), where a **stable base** stops edits above it from rebuilding it, where a **heavy dependency** can be kept away from crates that do not need it, and where a **proc macro** forces a crate anyway. Each extra crate costs a manifest, an API that must be `pub`, orphan-rule limits on trait impls, possible lost cross-crate inlining and, if published, its own release. I start coarse, measure with `cargo build --timings`, and split on evidence.

code

console · 6 lines
console
$ cargo build --workspace --timings
      Timing report saved to .../target/cargo-timings/cargo-timing-20261027T175411084Z-9f93719d42fbd3f4.html
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.09s
$ ls target/cargo-timings
cargo-timing-20261027T175411084Z-9f93719d42fbd3f4.html
cargo-timing.html

go deeper

for a junior

Recall that each crate compiles as one unit and that an edit recompiles the crates that depend on it.

for a middle

Explain parallel compilation of independent crates, and why a long dependency chain or a churning base crate defeats it.

for a senior

Read a cargo build --timings report and identify the crate on the critical path or the edit pattern that rebuilds too much.

for a principal

Own the trade-off: start coarse, split on measured evidence, keep heavy dependencies at the edges, and align crate boundaries with team ownership.

## Why the crate boundary matters to Cargo A **crate** is what one `rustc` invocation compiles; a **package** is what a `Cargo.toml` describes, and it contains one or more crates. In a workspace, Cargo turns the members' dependency graph into a schedule: - crates with no dependency between them are compiled **in parallel**, up to `build.jobs`, which defaults to the number of CPUs; - type checking and borrow checking of one crate happen inside its own `rustc` invocation; only that crate's code generation is split into codegen units, so one huge crate spreads its work across cores far less than several independent crates do; - an edit to a crate recompiles that crate and **every crate downstream** of it. In the `ledger` trio, an edit to `ledger-core` recompiled `ledger-api` and `ledger-cli`; an edit to `ledger-cli` recompiled only `ledger-cli`. So splitting is not free modularity; it reshapes both the clean build and the edit-compile loop. ## What a split can buy 1. **Width.** Two crates that both depend on `core` but not on each other build at the same time. A long chain, where each crate depends on the previous one, builds strictly in sequence and gains nothing from more cores. 2. **A stable base.** If the domain types change rarely and the HTTP handlers change daily, putting the types in their own crate means a handler edit does not recompile them. The reverse layout, a frequently edited crate at the bottom that everything depends on, makes every edit rebuild the whole workspace. 3. **Isolated heavy dependencies.** If only `ledger-api` needs a large web stack, keeping it out of `ledger-core` means `ledger-cli` and the core tests never compile it. 4. **Enforced boundaries.** Code in another crate can use only what is public, so a crate boundary is a hard API line that `pub(crate)` keeps honest; the visibility rules themselves belong to the language. 5. **Forced splits.** A procedural macro must live in its own `proc-macro` crate, and anything published separately must be its own package. ## What each crate costs | Cost | Where it bites | |---|---| | Another manifest and directory | mitigated by `[workspace.package]` and `[workspace.dependencies]` inheritance | | A public API between crates | items need `pub`, and changes ripple to every dependent | | The orphan rule | a trait impl for a type from another crate, with the trait also foreign, fails with E0117 | | Generic code | instantiated in the crate that uses it, so splitting generic-heavy code moves compile time rather than saving it | | Inlining | rustc inlines small functions across crates on its own; larger hot paths may need `#[inline]` or LTO | | No cycles | Cargo rejects a cycle between packages with `cyclic package dependency` | | Publishing | each published crate has its own version and release; internal ones should say `publish = false` | ## How I decide - **Start coarse.** One crate per deployable binary plus a library for what genuinely shared code exists. A crate per module is the usual over-split: many tiny crates, most of the cost table, little parallelism. - **Split on evidence.** `cargo build --timings` writes an HTML report under `target/cargo-timings/` showing which crates sit on the critical path and how many compile at once. Split a crate that dominates the critical path or that a frequent edit forces to rebuild. - **Shape the graph wide and shallow.** A small, stable bottom layer (domain types), parallel adapters above it (`api`, storage), thin binaries on top (`cli`). - **Keep heavy dependencies at the edges** so the core and its tests stay fast to build. - **Make the boundary match ownership.** Teams that own a crate own its public API; a crate boundary that cuts through one team's daily work mostly adds friction. - **Revisit when it hurts.** Merging two crates is cheap inside a workspace; the shared lockfile and target directory mean no version coordination is lost. ## Trade-offs to state out loud There is no single right number. Fine splitting helps parallel clean builds and protects APIs, but it increases cross-crate friction and can hurt runtime performance on hot paths without inlining hints or LTO. Coarse crates are simpler and optimise well within one crate, but they serialise compilation and make every edit rebuild more code. The decision is a team's build-time budget, the stability of its core types and who owns what. Monorepo-wide policy such as one version of everything is a broader organisational question; this decision is how Cargo's crate graph should look.

  • A team split its service into 40 crates and clean builds got no faster. What would you look at first?
    The shape of the graph in a `cargo build --timings` report. If the crates form a long chain, each waits for the previous one and the split added cost without width. Also check whether most code is generic and instantiated in the final crate anyway, and whether one crate everything depends on is edited constantly. Merging chained crates often helps more than splitting further.
  • When is splitting a crate the wrong fix for slow builds?
    When the time goes into code generation of a few large generic instantiations in the final binary, or into one heavy dependency every crate needs. Splitting moves that work around without removing it. Profile settings, fewer generic instantiations or dropping the heavy dependency address the cause; splitting only adds manifests and APIs.

Splitting a codebase into crates is like dividing a kitchen into stations: separate stations let several cooks work at once, but every hand-off between them needs a counter and a clear order ticket.

  • More crates always make builds faster.
  • Splitting generic code into its own crate saves its compile time.
  • A crate per module is the idiomatic Rust layout.
  • Crate boundaries cost nothing at runtime.
  • Member crates can depend on each other in a cycle.