Recipes on cargo-feature-combinations

Incompatible features

Mon, 01 Jan 0001 00:00:00 +0000

Incompatible features#

Scenario: an HTTP client crate offers two TLS backends, native-tls and rustls. A consumer picks one — enabling both is a real conflict (here the code even compile_error!s on it). You want the matrix to skip that combination.

[package]
name = "http-client"
version = "0.1.0"
edition = "2024"

[features]
native-tls = []
rustls = []

[package.metadata.cargo-fc]
# native-tls and rustls are two TLS backends — never both at once.
exclude_feature_sets = [["native-tls", "rustls"]]

[workspace]

Any generated combination that is a superset of {native-tls, rustls} is removed. Every other combination — each backend alone, and neither — is still checked. cargo fc check visits exactly three combinations; the {native-tls, rustls} pair never appears:

Optional dependencies

Mon, 01 Jan 0001 00:00:00 +0000

Optional dependencies#

Scenario: a store crate has two optional storage backends and one real compression feature. Cargo turns each optional dependency into an implicit feature (redis-backend, sled-backend), which would multiply the matrix — but you only want to vary compression.

[package]
name = "store"
version = "0.1.0"
edition = "2024"

[features]
compression = []

[dependencies]
redis-backend = { path = "../redis-backend", optional = true }
sled-backend = { path = "../sled-backend", optional = true }

[package.metadata.cargo-fc]
# Don't vary the implicit features of the optional backends.
skip_optional_dependencies = true

With skip_optional_dependencies = true, the implicit redis-backend and sled-backend features are removed from the matrix; only the real compression feature is varied. Checking just the store package shows two combinations:

Restrict the matrix

Mon, 01 Jan 0001 00:00:00 +0000

Restrict the matrix to specific configurations#

Scenario: a web app can be built in three rendering modes — hydrate, ssr, csr — but you only ever ship hydrate and ssr. You don’t want a powerset; you want exactly those two configurations.

[package]
name = "webapp"
version = "0.1.0"
edition = "2024"

[features]
hydrate = []
ssr = []
csr = []

[package.metadata.cargo-fc]
# Only ever test the two modes we ship — no powerset.
allow_feature_sets = [["hydrate"], ["ssr"]]

[workspace]

When allow_feature_sets is non-empty, the matrix is exactly those sets — no powerset, no empty set, and csr is never tested:

Large feature sets

Mon, 01 Jan 0001 00:00:00 +0000

Large, independent feature sets#

Scenario: a codec crate supports several serialization formats and, independently, several compression codecs. The two axes are orthogonal — the format code doesn’t care which codec is enabled — so a full powerset over all six features is mostly redundant.

[package]
name = "codec"
version = "0.1.0"
edition = "2024"

[features]
json = []
yaml = []
msgpack = []
gzip = []
zstd = []
brotli = []

[package.metadata.cargo-fc]
# Formats and compression codecs are independent axes — powerset within each
# group, never across them.
isolated_feature_sets = [
 ["json", "yaml", "msgpack"],
 ["gzip", "zstd", "brotli"],
]

[workspace]

Instead of one powerset over all six features, cargo fc builds a sub-matrix per group and merges them: the formats are varied among themselves, the codecs among themselves — but the two are never crossed. A combination appearing in more than one group is kept once.

Per-command differences

Mon, 01 Jan 0001 00:00:00 +0000

Build a feature you never test#

Scenario: a renderer crate has a heavy gpu feature. It should be compiled to catch build breakage, but its tests need a GPU that CI doesn’t have. You want cargo fc build to include gpu, but cargo fc test to skip it.

[package]
name = "renderer"
version = "0.1.0"
edition = "2024"

[lib]
doctest = false

[features]
gpu = []
simd = []

# gpu is part of the matrix by default (build, check, clippy).
[package.metadata.cargo-fc]

[package.metadata.cargo-fc.subcommands.test]
# ...but never test the gpu combinations.
exclude_features = { add = ["gpu"] }

[workspace]

cargo fc build varies both features — four combinations, including the gpu ones:

Cross-compilation in CI

Mon, 01 Jan 0001 00:00:00 +0000

Cross-compilation in CI#

Scenario: you want to check every feature combination on several target triples, from a single CI job, without a matrix of GitHub Actions jobs.

Declare the targets#

Declare the target list in the workspace Cargo.toml:

# Workspace that checks every feature combination across multiple target triples.
[workspace]
resolver = "2"
members = ["crates/*"]

[workspace.package]
version = "0.1.0"
edition = "2024"
publish = false

[workspace.metadata.cargo-fc]
# Check every feature combination on each of these targets.
targets = [
 "x86_64-unknown-linux-gnu",
 "wasm32-unknown-unknown",
]
# `check` never links, so plain cargo cross-checks fine without a C toolchain.
# (Cross-compiling native-C deps would use the cargo-zigbuild default instead.)
driver = "cargo"

A single cargo fc check then visits every feature combination on every target: