In a Cargo.toml, how do `[dev-dependencies]`, `[build-dependencies]` and `[target.'cfg(...)'.dependencies]` differ from `[dependencies]` in which code may use them?
answer
- who compiles against which table
- tests, examples and benchmarks only
- build.rs sees one table
- cfg evaluated per target platform
basics
~10 sNormal dependencies serve the package and its dependents; dev-dependencies only tests, examples and benchmarks; build-dependencies only build.rs; and a target cfg table adds dependencies only when compiling for a matching platform.
solid answer
~40 s`[dependencies]` are compiled for the library and binaries and propagate to every package that depends on yours. `[dev-dependencies]` are used only when compiling **tests, examples and benchmarks**, so a library that names one outside `#[cfg(test)]` code fails with E0433, and they never reach dependents. `[build-dependencies]` are visible **only to `build.rs`**: the build script cannot use normal or dev-dependencies, and the package cannot use a build-dependency unless it is also listed under `[dependencies]`. `[target.'cfg(windows)'.dependencies]` (or a full triple) adds a dependency only when compiling for a target whose `cfg` matches; `dev-dependencies` and `build-dependencies` can be target-specific too. `cfg(feature = ...)`, `cfg(test)` and `cfg(debug_assertions)` do not work in those headers; Cargo warns, and optional dependencies with `[features]` are the tool instead.
code
toml · 16 lines[package]
name = "ledger-api"
version = "0.1.0"
edition = "2024"
[dependencies]
serde = "1"
[dev-dependencies]
serde_json = "1"
[build-dependencies]
cc = "1"
[target.'cfg(windows)'.dependencies]
anyhow = "1"go deeper
Recall the split: dev-dependencies for tests, examples and benchmarks; build-dependencies for build.rs; normal dependencies for the code you ship.
Explain why a dev-dependency fails with E0433 outside cfg(test) code, why build.rs and the package have separate lists, and how a target cfg table is evaluated.
Diagnose a cfg(test) or cfg(feature) target header that silently never applies, and move the crate to dev-dependencies or an optional dependency.
Keep test and build tooling out of normal dependencies so dependents compile only what the library needs at run time.
## Four tables, four audiences A `Cargo.toml` can list dependencies in several tables. They share one syntax (a version requirement, a `git` or `path` source, `features`, and so on) but differ in **which compiled code may name the crate**: | Table | Who can use the crate | Reaches dependents? | |---|---|---| | `[dependencies]` | the library, binaries, and the package's tests, examples and benchmarks | yes | | `[dev-dependencies]` | tests, examples and benchmarks only | no | | `[build-dependencies]` | the build script `build.rs` only | no | | `[target.'cfg(...)'.dependencies]` | like `[dependencies]`, but only when compiling for a matching target | yes, on matching targets | ## Dev-dependencies The Cargo book says dev-dependencies "are not used when compiling a package for building, but are used for compiling tests, examples, and benchmarks", and that they are not propagated to packages depending on yours. Two consequences follow: - Unit tests inside the library can use them, because a `#[cfg(test)] mod tests` block is compiled only when Cargo builds the library as a test. Code outside such a block is part of the normal build, so naming a dev-dependency there makes `cargo build` fail with rustc's `E0433` ("use of unresolved module or unlinked crate"). - Test-only crates, such as a JSON parser used only to check output, cost dependents nothing: they are never compiled for them. - Integration tests in `tests/`, examples in `examples/` and benchmarks in `benches/` are each compiled as their own crate, and each of them sees both the normal and the dev-dependencies. When a crate is packaged for publishing, only dev-dependencies that carry a `version` are kept in the packaged manifest; a path-only dev-dependency is dropped. Because dev-dependencies are excluded from crates.io's rule against non-registry dependencies, a path-only dev-dependency does not block publishing. ## Build-dependencies A **build script** (`build.rs`) is compiled and run separately from the package it builds, and it gets its own dependency list. The Cargo book is explicit that the build script "does not have access to the dependencies listed in the dependencies or dev-dependencies section", and that build dependencies are not available to the package itself unless listed under `[dependencies]` as well. The usual example is the `cc` crate, which a build script uses to compile C code. When a build-dependency is written under a target header, as in `[target.'cfg(unix)'.build-dependencies]`, it is built only when the **host** platform matches, because the build script runs on the machine doing the build; what a build script does is a lesson of its own. ## Target-specific tables A platform-specific dependency goes under `[target.<spec>.dependencies]`, where `<spec>` is either a `cfg(...)` expression or a full target triple: 1. `[target.'cfg(windows)'.dependencies]` or `[target.'cfg(target_arch = "x86_64")'.dependencies]`, with `not`, `any` and `all` available to combine conditions. 2. `[target.x86_64-pc-windows-gnu.dependencies]` for one exact triple. 3. `[target.'cfg(unix)'.dev-dependencies]` and `[target.'cfg(unix)'.build-dependencies]` for target-specific variants of the other tables. The condition is evaluated for the platform being compiled for, using the values `rustc --print=cfg --target=<triple>` reports. `cargo tree --target x86_64-pc-windows-msvc` shows the Windows-only dependency that a plain `cargo tree` on macOS omits, and `--target all` shows every platform's. `Cargo.lock` records the target-specific dependencies of every platform, not only the host's, so one lockfile serves every platform the team builds for. ## What a target header cannot select The headers look like Rust's `#[cfg]`, but not every `cfg` value works there. The Cargo book states that `cfg(feature = "...")`, `cfg(debug_assertions)`, `cfg(test)` and `cfg(proc_macro)` "will not work as expected" and always take the value `rustc --print=cfg` reports. Cargo 1.99.1 warns about them; for `cfg(test)` it prints "This value is not supported for selecting dependencies and will not work as expected", and a test that names the crate then fails with `E0433` because the dependency is never added. The fixes: - a test-only crate belongs in `[dev-dependencies]`; - a feature-gated crate is an `optional = true` dependency enabled from `[features]`, which is how Cargo's features work. ## Adding them from the command line `cargo add` writes to these tables with `--dev`, `--build` and `--target`, for example `cargo add anyhow --target 'cfg(windows)'`, which produced a `[target."cfg(windows)".dependencies]` table in the run behind this answer.
- A library's `build.rs` needs `serde_json` to read a config file, and the library also uses it at run time. Where must it be listed?In both `[build-dependencies]` and `[dependencies]`. The build script and the package are compiled separately with independent dependency lists, so listing it in only one table leaves the other side with an E0433 error.
- Does a target-specific dependency for Windows change `Cargo.lock` when the project is only ever built on Linux?Yes. `Cargo.lock` records the dependencies of every target platform, not just the host's, so the Windows-only crate is locked even though it is never compiled on Linux. That keeps one lockfile valid for every platform the team builds on.
- Dev-dependencies are the crates used in the dev profile, dropped by --release.
- A build script can use anything listed under [dependencies].
- Listing a crate under [build-dependencies] also makes it available to src/lib.rs.
- [target.'cfg(test)'.dependencies] adds a crate only for test builds.
- Downstream crates inherit your dev-dependencies when they run their tests.
- A [target.'cfg(...)'.dependencies] table is evaluated for the host, not the compile target.