In a Cargo build, why does an app enabling only `tls-native` on db-client, with `default-features = false`, still hit the crate's both-backends `compile_error!`?
answer
- one build of the crate
- union, not intersection
- who asked for the default?
- cargo tree -e features -i
basics
~20 sCargo builds db-client once with the union of every dependent's features. Another crate in the graph depends on it with defaults, so tls-rustls is on beside tls-native, which is why Cargo features must be additive and never mutually exclusive.
solid answer
~40 sCargo compiles a normal dependency once per build, with the **union** of the features every dependent requested. The app's `default-features = false, features = ["tls-native"]` is one request; a connection-pool crate the app also uses depends on `db-client` with a plain entry, which requests `default` and so `tls-rustls`. The crate is built with both, and its `compile_error!` for the pair fires. `cargo tree -e features -i db-client` shows the pool as the source of `default`. The lesson is the Cargo book's rule: enabling a feature must not disable functionality, and any combination should be safe, so the crate should let both backends compile and pick one by precedence or at run time.
code
toml · 8 lines# app/Cargo.toml
[dependencies]
db-client = { path = "../db-client", default-features = false, features = ["tls-native"] }
pool = { path = "../pool" }
# pool/Cargo.toml
[dependencies]
db-client = { path = "../db-client" }go deeper
Recall that Cargo builds a shared dependency once and that the features it gets are everything anyone asked for.
Explain the union rule with this scenario and why default-features = false in one entry cannot keep the default off for the whole build.
Diagnose with cargo tree -e features -i, name the dependent that pulled the default in, and argue that the crate's exclusive features, not the pool, are the bug to fix.
Weigh the downstream workarounds, a forwarded feature, a local patch or accepting the default, against fixing the crate's design so no future consumer meets the conflict.
## What feature unification does A **Cargo feature** is a flag a package declares in `[features]`; dependents ask for features in their dependency entries. When several packages in one build depend on the same crate, Cargo does not build a private copy for each. It builds the crate **once**, with the **union** of all requested features. The Cargo book gives the reason — it keeps a single copy of the dependency in the build — and states the consequence: features should be **additive**. Enabling a feature should not disable functionality, and it should usually be safe to enable any combination. Take the scenario: - `db-client` declares `default = ["tls-rustls"]`, plus `tls-rustls` and `tls-native`, and its source rejects the pair with `compile_error!` under a `cfg(all(...))` condition; - `app` depends on `db-client` with `default-features = false, features = ["tls-native"]`; - `app` also depends on `pool`, whose manifest says `db-client = { path = "../db-client" }`, a plain entry that requests the defaults. The app's opt-out only withdraws the app's own request for the defaults. The pool's entry still requests them, the union is `default`, `tls-native` and `tls-rustls`, and the build stops at the crate's own error. ## Finding who enabled the feature `cargo tree` can answer "who asked for this?" directly: 1. `cargo tree -e features -i db-client` inverts the graph and shows each enabled feature of `db-client` with the packages that requested it — here `default` comes from `pool`, `tls-native` from `app`. 2. `cargo tree -f "{p} {f}"` prints the final feature list beside each package, `default,tls-native,tls-rustls` in this case. 3. A feature marked `(command-line)` was enabled by the invocation itself; here it is `app`'s own default, on because `app` is the selected package. ## Fixing it at the source The feature design is the bug, not the pool. A feature that removes or forbids something cannot survive unification, because any crate anywhere in the graph can switch it on. Better designs, all named in the Cargo book's section on mutually exclusive features: - **Let both backends compile** and choose at run time, from configuration or an argument, so any combination is valid. - **Pick by precedence** when both are enabled: one backend wins, and the other is merely unused. - **Split the functionality into separate packages** when the choices truly cannot coexist. - Keep a `compile_error!` only as a last resort, accepting that it pushes coordination onto every dependent in the graph. The same reasoning rules out negative features. A `no-std` feature that removes std-dependent APIs breaks any other dependent that calls those APIs the moment one crate turns it on. The Cargo book's advice is a positive `std` feature that adds them. ## Fixing it downstream, and its limits The application can sometimes work around a non-additive crate: | Move | What it does | Limit | |---|---|---| | Ask the pool to write `default-features = false` and forward features | removes the second request for `default` | needs a change in someone else's crate | | Patch or fork the pool locally | same effect, under your control | a maintenance burden you now own | | Enable `tls-rustls` and live with it | the build passes | the app does not get the backend it wanted | None of these makes the crate safe for the next application, which is why the fix belongs in the crate's feature design. ## What changes with resolver "2" The newer feature resolver (resolver `"2"`, whose feature rules resolver `"3"` keeps) stops unifying in a few narrow cases: build-dependencies and proc-macros, dev-dependencies when no test or example is being built, and target-specific dependencies for a platform not being built. Two normal dependencies of the same build, as here, are **still unified**, so a newer resolver does not rescue a non-additive feature. Unification also crosses workspace members. Building several members in one invocation, with `--workspace` or several `-p` flags, unifies the features of their shared dependencies, so a crate that builds alone can fail when built beside a sibling. The Cargo book's only escape hatch is to build those members in separate `cargo` invocations, which is another sign that the feature set itself needs fixing.
- Would switching the workspace to resolver "2" or "3" make that build pass?No. Those resolvers stop unifying only for build-dependencies and proc-macros, dev-dependencies outside test builds, and target-specific dependencies for other platforms. Two normal dependencies of one build still share one feature set.
- How would you redesign the crate so both TLS features can be on at once?Compile both backends when both features are enabled and choose one at run time through configuration, or let one win by precedence. Any combination then builds, which is what unification needs.
- Why is a `no-std` feature a design bug while a `std` feature is fine?A `no-std` feature removes APIs, so any crate that turns it on breaks every other dependent that calls them. A `std` feature only adds APIs, so whoever enables it cannot break anyone.
- Cargo builds a separate copy of the crate for each dependent's feature set
- Unification takes the intersection of the requested features
- default-features = false in the app overrides what other crates request
- Resolver 2 stops unifying features between normal dependencies
- A compile_error! guard makes mutually exclusive features safe to publish