skip to content

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?

level: seniorimportance: should knowfreq 25%

answer

  1. skipped, not failed
  2. explicit selection turns the skip into an error
  3. CI never compiles what it never selects
  4. manual targets add to discovered ones
  5. inferred path from the target name

basics

~20 s

required-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
toml
[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

for a junior

Recall that a binary can be tied to a Cargo feature and is built only when that feature is enabled with --features.

for a middle

Explain implicit versus explicit target selection, why the skip is silent, and how [[bin]] tables, path inference and autobins interact.

for a senior

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.

for a principal

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.