A Cargo.toml [[bin]] named tile-admin has required-features = ["admin"]; why does cargo build skip it silently, and how do you keep it compiling?
answer
- skipped, not failed
- explicit selection turns the skip into an error
- CI never compiles what it never selects
- manual targets add to discovered ones
- inferred path from the target name
basics
~20 srequired-features makes Cargo skip the target whenever a listed feature is off, so cargo build without --features admin never compiles it. Only naming it with --bin errors. CI must build with the feature, or the tool silently rots.
solid answer
~30 s`required-features` on a `[[bin]]`, `[[example]]`, `[[test]]` or `[[bench]]` table tells Cargo to build that target only when every listed Cargo feature is enabled. A plain `cargo build`, `cargo test` or `--all-targets` run therefore drops `tile-admin` without a word; Cargo does not even check that its source file exists. Only an explicit `cargo run --bin tile-admin` or `cargo build --bin tile-admin` reports that the target requires the features `admin`. Build it with `--features admin` (or `--all-features`) and add that to CI so the gated tool keeps compiling. Declaring `[[bin]]` does not turn off auto-discovery since the 2018 edition; `autobins = false` does.
code
toml · 12 lines[package]
name = "geo-tiles"
version = "0.4.2"
edition = "2024"
[features]
admin = []
[[bin]]
name = "tile-admin"
path = "tools/tile_admin.rs"
required-features = ["admin"]go deeper
Recall that a binary can be tied to a Cargo feature and is built only when that feature is enabled with --features.
Explain implicit versus explicit target selection, why the skip is silent, and how [[bin]] tables, path inference and autobins interact.
Show the production habit: every feature-gated target is compiled by some CI job, and a missing binary is diagnosed from required-features, discovery and path before anything else.
Weigh feature-gated binaries against a separate tools package: gating keeps one release, but every gate is a build combination someone must keep green.
## What `required-features` does A package often ships a tool that only some users need: an admin binary that pulls in a database driver, an example that needs a TLS backend. Cargo's answer is the `required-features` key on a target table. It lists Cargo features (entries of `[features]`) that must **all** be enabled for the target to be built. It applies to `[[bin]]`, `[[example]]`, `[[test]]` and `[[bench]]`, and has no effect on `[lib]`. ```toml [features] admin = [] [[bin]] name = "tile-admin" path = "tools/tile_admin.rs" required-features = ["admin"] ``` How features themselves are designed, defaulted and unified is the material on Cargo features; here the point is what the key does to target selection. ## Why the binary vanishes without an error When Cargo selects targets implicitly, a target whose features are missing is **skipped, not failed**: - `cargo build` builds the library and every binary except `tile-admin`, and prints nothing about it. - `cargo test` builds and runs the unit tests of every other target; `tile-admin`'s are not compiled. - `cargo build --all-targets` skips it too. - While the target is skipped, Cargo does not even check that `tools/tile_admin.rs` exists; a deleted or broken file goes unnoticed. Only **explicit** selection turns the skip into an error, and the message names the fix: ```console $ cargo run --bin tile-admin error: target `tile-admin` in package `geo-tiles` requires the features: `admin` Consider enabling them by passing, e.g., `--features="admin"` ``` So the production risk is bit-rot: a refactor in the library breaks `tile-admin`, every default CI job stays green, and the failure appears weeks later when someone needs the tool. ## Building and protecting the gated target 1. Build or run it with the feature: `cargo build --features admin`, `cargo run --features admin --bin tile-admin`. 2. Give CI at least one job that enables it, either `--features admin` or `--all-features` (the latter only helps when the package's features can all be enabled together). 3. If the tool should normally be built, put the feature in `default` instead; users who want a slim build then opt out with `--no-default-features`. ## Two neighbouring manifest surprises Declaring targets by hand comes with two rules that explain many "where did my binary go" reports: - **Manual tables add to discovery.** Since the 2018 edition, writing a `[[bin]]` table does not stop Cargo from discovering `src/main.rs` and `src/bin/*.rs`; the `geo-tiles`, `tile-seed` and `tile-stats` binaries keep building beside `tile-admin`. To build only the binaries you list, set `autobins = false` in `[package]` (the siblings `autolib`, `autoexamples`, `autotests` and `autobenches` exist too). With the 2015 edition, one manual target switched discovery off, which is why old manifests behave differently. - **A `[[bin]]` without `path` is looked up by name.** Cargo infers `src/bin/<name>.rs` or `src/bin/<name>/main.rs`. Name the table `tile-admin` while the file is `src/bin/tile_admin.rs`, and the manifest fails to parse: Cargo cannot find `tile-admin` at either path, asks you to specify `bin.path` and suggests the similar `tile_admin`. Either rename the file, set `path`, or name the table after the file. | Situation | What Cargo does | |---|---| | `required-features` missing, implicit selection | skips the target silently | | `required-features` missing, `--bin tile-admin` | errors and suggests `--features` | | `[[bin]]` added, 2018 edition or later | discovered binaries still build | | `autobins = false` | only listed `[[bin]]` tables build; `src/main.rs` is no longer discovered | | `[[bin]]` name without a matching file and no `path` | manifest parse error with a suggestion | ## The same rule on examples, tests and benches `required-features` behaves identically on the other target tables. Give `[[example]] name = "render"` the line `required-features = ["admin"]` and `cargo test`, which normally compiles every example to keep it from rotting, compiles `render` no more; `cargo run --example render` reports that the target `render` requires the features `admin`. A gated integration test is the sharpest version of the trap: the test that was meant to guard the feature never runs in a default `cargo test`, and the summary shows nothing missing. ## Reading the symptom When a binary is "missing" from `target/debug`, check in this order: does its table have `required-features`; did a manual table or `autobins = false` change discovery; does the inferred path match the file. A stale executable from an earlier `--features` build can still sit in `target/debug`, so the presence of a file there proves nothing about the current build.
- Why might a CI job with --all-features not be enough to protect the tool?`--all-features` only works when every feature can be on at once. A package with alternative backends that cannot coexist needs explicit jobs per combination instead, each including `admin`, so the gated binary is compiled in at least one of them.
- How do you build only the binaries listed in [[bin]] tables?Set `autobins = false` in `[package]`. Cargo then stops discovering `src/main.rs` and `src/bin/*.rs`, and only the manually declared binaries remain. Without it, any 2018-or-later package builds the discovered binaries as well.
- Cargo prints an error whenever a target's required features are off.
- Adding a [[bin]] table stops Cargo discovering src/main.rs and src/bin files.
- required-features on [lib] gates the library behind a feature.
- If CI is green, every binary in the package still compiles.
- A [[bin]] name may differ from its file name without setting path.