skip to content

As maintainer of a Rust database-client crate, how would you design its Cargo features and defaults so downstream builds stay predictable?

level: principalimportance: should knowfreq 35%

answer

  1. defaults are a public promise
  2. positive capabilities, never negations
  3. hide internals behind dep:
  4. every combination must build
  5. removal is a major release

basics

~20 s

Keep features additive and named for capabilities, make the default set small but useful, hide optional dependencies behind dep:, use weak ?/ for cross-features, and build no-default, default and all-features in CI, since removing a feature is breaking.

solid answer

~40 s

I would treat the feature list as public API. Every feature only **adds** capability, so any combination compiles; that rules out a `no-std` switch in favour of a positive `std`, and means the two TLS backends can both be on with a run-time or precedence choice. The default set is what most users get, so it holds a working configuration (`std` and `tls-rustls`) and nothing heavy; users who want less write `default-features = false`. Optional integrations sit behind capability names with `dep:` so the dependency behind them can change, and cross-cutting features use `serde?/std` so they never drag integrations in. CI builds `--no-default-features`, the default set and `--all-features`, and I document each feature. Adding a feature is a minor release; removing one, or shrinking the default set, waits for a major.

code

toml · 17 lines
toml
[package]
name = "db-client"
version = "0.1.0"
edition = "2024"

[dependencies]
serde = { version = "1", optional = true, default-features = false, features = ["derive"] }

[features]
default = ["std", "tls-rustls"]
# Positive capability: no_std users opt out with default-features = false.
std = ["serde?/std"]
# Both backends may be on together; the code picks one at run time.
tls-rustls = []
tls-native = []
# Public capability name for an internal optional dependency.
json = ["dep:serde"]

go deeper

for a junior

Recall that the default feature is what users get without asking, and that features are meant to add functionality rather than take it away.

for a middle

Explain how dep:, the weak ?/ form and a positive std feature keep a library's feature list clean, and why intermediate libraries should write default-features = false.

for a senior

Show how a non-additive feature or a heavy default spreads through the ecosystem via unification, and which CI builds catch each problem before release.

for a principal

Own the trade-off between a default that works out of the box and one that stays light, set the CI feature matrix the team pays for, and plan feature removals for major releases.

## Why feature design is a lead decision A library's `[features]` table is part of its public interface. Every dependent writes feature names into its own Cargo.toml, and Cargo **unifies** all requests for a crate into one build with the union of features. So a feature decision made once by the maintainer is lived with by every application in the ecosystem that pulls the crate in, often through several layers of other libraries. There is no single correct design, but there is a set of trade-offs a maintainer should make on purpose. ## Principles - **Additive only.** Enabling a feature may add types, functions, backends or integrations, never remove or change them. Any combination of features should compile, because some application will end up with that combination. - **Positive names.** `std` that adds std-dependent APIs, not `no-std` that removes them. `json` or `serde` for an integration, not `no-json`. - **Capabilities, not dependencies.** Expose `json = ["dep:serde"]` rather than the implicit `serde` feature of an optional dependency, so the dependency can be swapped without renaming the feature. Cargo's SemVer guidance recommends exactly this, because removing an optional dependency with an exposed implicit feature can break users. - **Weak cross-features.** `std = ["serde?/std"]` turns on serde's `std` only when the integration is already enabled; the strong `"serde/std"` would add serde to every `std` build. - **Coarse enough to test.** Each extra feature doubles the possible combinations, so a handful of capability features beats one feature per function; crates.io also limits new crates and versions to 300 features, granting exceptions case by case. - **No mutual exclusion.** The two TLS backends must be able to coexist: compile both when both are requested and choose one at run time, or let one win by precedence. ## Choosing the default set The default feature is the configuration most users will compile without thinking. Weigh three pulls: 1. **Works out of the box.** A database client with no TLS by default leaves the first-time user with a failure; including `tls-rustls` gives a working connection. 2. **Stays light.** Every default dependency is compiled by every user who does not opt out, and intermediate libraries often forget to opt out, so a heavy default spreads through the ecosystem. 3. **Is hard to shrink.** Removing a feature from `default` is a major change under Cargo's SemVer guidance, because users may rely on what it enabled. Start small; adding to the default later is far safer than removing. A reasonable outcome for this crate is `default = ["std", "tls-rustls"]`, with `tls-native` and `json` opt-in. ## What it means for dependents - Libraries built on top of this crate should write `default-features = false` and forward only what they need, so the final application chooses the backend. - The crate's documentation should list every feature, which are stable and which are internal; the Cargo book encourages documenting features at the top of `lib.rs`. - docs.rs can be told, through package metadata, which features to enable when it builds the documentation; that setting is covered with documentation tooling. ## Verifying the matrix Features are conditional compilation, so the number of configurations grows exponentially. By default `cargo test`, Clippy and docs only see the default set. A practical CI matrix: | Build | Catches | |---|---| | `cargo build --no-default-features` | code that silently relies on `std` or a default backend | | `cargo build` / `cargo test` | the configuration most users run | | `cargo build --all-features` | non-additive features, such as a forbidden pair of backends | | each TLS backend alone, `--no-default-features -F tls-native` | a backend that only compiles beside the other | Testing every combination is rarely worth it; the trade-off is how many single-feature builds the team pays for in CI time. ## Evolving the set - **Minor release:** adding a feature, adding an optional dependency behind a feature, changing which features of a dependency are used. - **Usually a major release:** removing a feature, removing a feature from `default` or from another feature's list when that changes functionality, moving existing public code behind a new feature. - **Mitigation:** a feature being retired can stay as an empty, documented no-op until the next major version, which Cargo's SemVer guidance suggests.

  • A user asks you to drop `tls-rustls` from the default set in the next 1.x release; what do you answer?
    Removing a feature from `default` is a breaking change under Cargo's SemVer guidance, because users may rely on it without naming it. It waits for the next major release; until then users can opt out with `default-features = false`.
  • Why does `--all-features` belong in that crate's CI?
    Unification can hand any application any combination, so every combination must compile. `--all-features` is the cheapest build that catches two features that cannot coexist.

  • A no-std feature is the natural way to support embedded users
  • Put every integration in default so users never need to configure anything
  • Removing a feature from default is fine in a minor release
  • Mutually exclusive features are fine if the README explains them
  • Testing the default features in CI covers the whole crate