In a Cargo.toml, how do `optional = true`, `"dep:serde"` and `"serde?/std"` differ in what a feature turns on?
answer
- an optional dependency gets a free feature
- dep: hides that feature
- slash enables, question mark waits
- the error names the enabling feature
basics
~20 sAn optional dependency is left out of the build and gets an implicit same-named feature. Writing dep:serde anywhere in [features] removes that implicit feature, and serde?/std enables serde's std only if something else already pulled serde in.
solid answer
~40 s`optional = true` keeps a dependency out of the build until a feature enables it, and by default Cargo defines an implicit feature with the dependency's name, as if you had written `serde = ["dep:serde"]`. Once `"dep:serde"` appears anywhere in `[features]`, that implicit feature disappears, so the dependency can sit behind a better name such as `json`, and `--features serde` becomes an error. In a feature list, `"serde/std"` turns on serde's `std` feature *and* pulls the optional serde in; `"serde?/std"` is the weak form, which turns on `std` only if something else already enabled serde. That is what you want for a `std` feature that must not drag optional integrations into the build.
code
toml · 9 lines[dependencies]
serde = { version = "1", optional = true, default-features = false, features = ["derive"] }
[features]
default = ["tls-rustls"]
tls-rustls = []
tls-native = []
std = ["serde?/std"]
json = ["dep:serde"]go deeper
Recall that optional = true leaves a dependency out until a feature enables it, and that Cargo names an implicit feature after the dependency.
Explain what dep: changes, including the error a user gets for the vanished implicit feature, and contrast serde/std with serde?/std using a std feature as the example.
Spot a slash that should be a weak ?/ by reading cargo tree output, and explain why an exposed implicit feature turns a dependency swap into a breaking change.
Decide which optional dependencies become public feature names and which stay hidden behind capability features, so the crate can change its integrations without a major release.
## Optional dependencies and their implicit feature A dependency marked `optional = true` in `[dependencies]` is **not compiled by default**. Something has to enable it, and that something is a Cargo feature. To make that possible without extra typing, Cargo gives every optional dependency an **implicit feature** with the same name, behaving as if the manifest said: ```toml [features] serde = ["dep:serde"] ``` So with a plain `serde = { version = "1", optional = true }`, a user runs `cargo build --features serde`, or a dependent writes `features = ["serde"]`, and serde joins the build. Code tests for it with `cfg(feature = "serde")` — how that condition is written in Rust is covered with conditional compilation, not here. ## The dep: prefix `"dep:serde"` in a feature list means *the optional dependency serde*, as opposed to *a feature named serde*. Its second effect matters more: if `dep:serde` appears **anywhere** in `[features]`, Cargo **does not create** the implicit `serde` feature. That lets a library: - give an optional dependency a capability name, as in `json = ["dep:serde"]`; - group several optional dependencies under one feature; - keep an internal dependency out of its public feature list, so swapping it later is not a breaking change. A feature may still share the dependency's name when that is the clearest choice: writing `serde = ["dep:serde"]` explicitly is legal, and then `--features serde` works again because the feature now exists by declaration rather than implicitly. What `dep:` changes is that the name is a decision the maintainer made, visible in `[features]`, rather than a side effect of marking a dependency optional. A capability feature can also list several dependencies at once, so one switch brings in a parser and its companion crate together. With `json = ["dep:serde"]` declared, `cargo build --features serde` fails, and cargo 1.99.1 explains why: it says the package does not have feature `serde`, that an optional dependency with that name exists but is included with the "dep:" syntax, and that `json` would enable it. The `dep:` prefix belongs in the manifest only; passing `--features dep:serde` on the command line is rejected with "feature `dep:serde` is not allowed to use explicit `dep:` syntax". ## Enabling a dependency's feature: / and ?/ A feature can switch on a feature **of a dependency** with `"package-name/feature-name"`. For an optional dependency this has a side effect: it also **enables the dependency itself**. The weak form adds a question mark: | Entry in a feature list | Effect when the feature is on | |---|---| | `"dep:serde"` | adds the optional serde to the build | | `"serde/std"` | adds serde **and** enables its `std` feature | | `"serde?/std"` | enables serde's `std` only if serde is already in the build | The weak form fits the common `std` pattern. A database client might declare `std = ["serde?/std"]` and `json = ["dep:serde"]`. A user who enables only `std` gets no serde at all; a user who enables `std` and `json` gets serde with its `std` feature. Writing `"serde/std"` instead would make every `std` user compile serde. ## Reading the result `cargo tree -e normal -f "{p} {f}"` prints the features each package ends up with, which is the quickest way to confirm what a feature pulled in: 1. with `--features std` the database client shows `default,std,tls-rustls` and no serde line; 2. with `--features std,json` serde appears with `derive,serde_derive,std`; 3. with `cargo tree -e features`, every enabled feature shows as a node, under the package that enabled it. ## Why the choice matters - **Public surface.** Every implicit feature is part of the crate's interface. Cargo's SemVer guidance lists removing an optional dependency as possibly breaking because users may enable it through that implicit feature; `dep:` avoids exposing it in the first place. - **Compile cost.** A `/` where a `?/` was meant silently adds a dependency and its whole subtree to every build that turns the feature on. - **Lockfile.** Cargo resolves Cargo.lock as if every feature of the workspace members were on, so an optional dependency is locked even when no build uses it.
- Can a user enable that optional dependency with `cargo build --features dep:serde`?No. Cargo 1.99.1 rejects it with "feature `dep:serde` is not allowed to use explicit `dep:` syntax". `dep:` is manifest syntax; on the command line the user names a feature, here `json`.
- What changes if the `std` feature is written `std = ["serde/std"]` instead of the weak form?Enabling `std` then also enables the optional serde dependency, so every `std` user compiles serde and its derive macro stack. The weak `serde?/std` leaves serde out unless another feature such as `json` already brought it in.
- An optional dependency needs an explicit [features] entry before anyone can enable it
- dep:serde and the feature serde are interchangeable spellings of the same thing
- serde/std only enables a feature and never pulls in the dependency
- Users can type --features dep:serde on the command line
- Renaming an optional dependency's feature is harmless because nobody uses implicit features