cargo-feature-combinations

Basics

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

Configuration basics#

Where configuration lives#

Configuration goes in Cargo.toml metadata tables. There are two scopes:

Package — [package.metadata.cargo-fc], in a crate’s Cargo.toml. Shapes that package’s feature matrix.
Workspace — [workspace.metadata.cargo-fc], in the workspace root Cargo.toml. Applies across the workspace (package selection, targets, flag defaults).

# crate Cargo.toml
[package.metadata.cargo-fc]
exclude_features = ["default"]

# workspace root Cargo.toml
[workspace.metadata.cargo-fc]
exclude_packages = ["examples"]

Excluding workspace packages#

Remove packages from every run in the workspace metadata:

[workspace.metadata.cargo-fc]
exclude_packages = ["package-a", "package-b"]

Package exclusion is a workspace-level decision — a package can’t exclude its siblings.

Configured targets

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

Configured targets#

Declaring a target list#

Declare workspace-wide targets in the workspace Cargo.toml:

[workspace.metadata.cargo-fc]
targets = [
 "x86_64-unknown-linux-gnu",
 "x86_64-pc-windows-msvc",
 "aarch64-apple-darwin",
]

Now cargo fc check visits every combination on every target.

Per-package target lists#

A package can override the workspace list, or opt out of it:

[package.metadata.cargo-fc]
# Run this package only on wasm (overrides the workspace list, does not merge).
targets = ["wasm32-unknown-unknown"]

The three states:

Value	Meaning
key missing	inherit the workspace target list
`targets = []`	opt out of the workspace list; use the single effective target
`targets = ["…"]`	this package’s own list (overrides, does not merge)

targets only selects which targets are visited. The target.'cfg(...)' overrides still shape the feature matrix for each concrete target.

GitHub Actions

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

GitHub Actions#

GitHub Actions’ matrix feature pairs naturally with cargo fc matrix to test feature combinations in parallel.

Approach 1 — fan out one job per combination#

First, a reusable workflow that computes the feature matrix:

# .github/workflows/feature-matrix.yaml
name: feature-matrix
on:
 workflow_call:
 outputs:
 matrix:
 description: "feature matrix"
 value: ${{ jobs.matrix.outputs.matrix }}
jobs:
 matrix:
 name: Generate feature matrix
 runs-on: ubuntu-24.04
 outputs:
 matrix: ${{ steps.compute-matrix.outputs.matrix }}
 steps:
 - uses: actions/checkout@v4
 - uses: romnn/cargo-feature-combinations@main
 - name: Compute feature matrix
 id: compute-matrix
 run: |-
 MATRIX="$(cargo fc matrix)"
 echo "${MATRIX}"
 echo "matrix=${MATRIX}" >> "$GITHUB_OUTPUT"

Then consume it to build every combination in parallel:

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:

Introduction

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

Introduction#

cargo-feature-combinations is a plugin for cargo that runs a command against selected — or all — combinations of a crate’s features. You invoke it as cargo fc.

The problem#

Cargo features are meant to be additive, but real crates rarely behave that way. A crate can:

compile with its default features but fail with --no-default-features,
compile with each feature alone but fail when two are enabled together,
pass cargo build yet fail cargo test for a particular combination,
compile on your host but not when cross-compiled.

Checking only the default set, or only --all-features, hides every one of these cases. --all-features in particular enables everything at once, which is exactly the combination least likely to expose a conflict between two mutually-exclusive features.

Running commands

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

Running commands#

Use cargo fc as if it were cargo. The command and its arguments are forwarded to each combination’s invocation:

cargo fc check
cargo fc clippy
cargo fc build
cargo fc test
cargo fc doc

Forwarded arguments#

Every cargo argument is passed through except the three that would conflict with the matrix cargo fc builds for you:

--features
--all-features
--no-default-features

Everything else is forwarded verbatim, so this works as expected:

cargo fc check -p my-crate --all-targets
cargo fc test --release -- --nocapture

Arguments after -- are passed to the invoked program (for example the test binary), never interpreted by cargo fc.

Build drivers

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

Build drivers#

A “driver” is the program cargo fc invokes in place of cargo for each build. The default depends on whether you’re cross-compiling.

Why a driver#

Cross-compiling a crate with native-C build dependencies (for example aws-lc-sys, pulled in via rustls) needs a cross C toolchain — the host cc can’t target another OS. To make that transparent, when any non-host target is planned, cargo fc invokes cargo-zigbuild instead of plain cargo, so zig supplies the cross C compiler and linker for every target.

Installation

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

Installation#

cargo-feature-combinations installs a cargo subcommand. Once it’s on your PATH, cargo fc works from any crate or workspace.

From crates.io#

cargo install --locked cargo-feature-combinations

--locked builds against the versions in the published Cargo.lock, which is the most reproducible option.

Homebrew#

A prebuilt binary is available through the author’s tap, which avoids compiling from source:

brew install --cask romnn/tap/cargo-fc

Nix#

There is an unofficial, community-maintained package (not maintained by the author of the tool):

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:

Output modes

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

Output modes#

A full matrix run can print a lot. These flags control how much you see. They are CLI flags, but most can also be set as defaults in Cargo.toml.

`--diagnostics-only`#

Show only warnings and errors per combination, suppressing build progress and “Finished” chatter.

cargo fc --diagnostics-only clippy

$ cargo fc --diagnostics-only clippy --workspace
 
 Linting [1/4] loader ( features = [] )
warning: function `checksum` is never used
 --> crates/loader/src/lib.rs:12:4
 |
12 | fn checksum(bytes: &[u8]) -> usize {
 | ^^^^^^^^
 |
 = note: `#[warn(dead_code)]` (part of `#[warn(unused)]`) on by default
 
 Linting [2/4] loader ( features = [experimental] )
error[E0425]: cannot find function `missing_helper` in this scope
 --> crates/loader/src/lib.rs:32:5
 |
32 | missing_helper()
 | ^^^^^^^^^^^^^^ not found in this scope
 
For more information about this error, try `rustc --explain E0425`.
 Linting [3/4] loader ( features = [experimental, validation] )
error[E0425]: cannot find function `missing_helper` in this scope
 --> crates/loader/src/lib.rs:32:5
 |
32 | missing_helper()
 | ^^^^^^^^^^^^^^ not found in this scope
 
For more information about this error, try `rustc --explain E0425`.
 Linting [4/4] loader ( features = [validation] )
warning: function `checksum` is never used
 --> crates/loader/src/lib.rs:12:4
 |
12 | fn checksum(bytes: &[u8]) -> usize {
 | ^^^^^^^^
 |
 = note: `#[warn(dead_code)]` (part of `#[warn(unused)]`) on by default
 
 
 Finished 4 feature combinations for 1 package in 0.00s
 
 WARN loader ( 0 errors, 1 warnings, features = [] )
 FAIL loader ( 1 errors, 0 warnings, features = [experimental] )
 FAIL loader ( 1 errors, 0 warnings, features = [experimental, validation] )
 WARN loader ( 0 errors, 1 warnings, features = [validation] )

The command must accept --message-format and emit rustc JSON diagnostics. That is true for build, check, clippy, and doc — and any alias or wrapper that does the same. It is not safe for test or run, which is why broad diagnostics defaults don’t apply to them automatically.

Shaping the feature matrix

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

Shaping the feature matrix#

By default the matrix is the powerset of a package’s features. These keys, all under [package.metadata.cargo-fc], change what gets generated.

At a glance#

Key	Effect
`exclude_features`	Remove features from the varied set.
`only_features`	Restrict the varied set to an allowlist.
`include_features`	Add features to every generated combination.
`exclude_feature_sets`	Drop specific combinations (e.g. incompatible pairs).
`include_feature_sets`	Always add specific exact combinations.
`allow_feature_sets`	Replace the powerset with an exact list of sets.
`isolated_feature_sets`	Build independent sub-matrices and merge them.
`skip_optional_dependencies`	Ignore implicit optional-dependency features.
`no_empty_feature_set`	Never include the empty (no-features) combination.
`max_combinations`	Raise the safety limit on generated combinations.
`matrix`	Attach custom metadata to `cargo fc matrix` rows.

`exclude_features`#

Features listed here are not varied in the matrix.

Installing targets

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

Installing missing targets#

By default cargo fc does not mutate the Rust toolchain. If a configured target’s rustup component isn’t installed, the build for that target fails as it normally would.

Opt in per invocation#

cargo fc check --install-missing-targets

This installs the missing target components with rustup before running. It’s an explicit opt-in because it may mutate the toolchain and use the network. When a +toolchain override is present, the same override is passed to rustup, so components land in the right toolchain.

Quick start

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

Quick start#

This walks through a first run and how to read the output. It assumes cargo fc is installed.

1. Run a command across the matrix#

From any crate or workspace, prefix a cargo command with fc:

cargo fc check

cargo fc enumerates the combinations of your features, runs cargo check against each, and prints a summary:

$ cargo fc --summary-only check --workspace
 
 Checking [1/6] cli ( features = [] )
 Checking [2/6] cli ( features = [color] )
 Checking [3/6] engine ( features = [] )
 Checking [4/6] engine ( features = [metrics] )
 Checking [5/6] engine ( features = [metrics, tracing] )
 Checking [6/6] engine ( features = [tracing] )
 
 Finished 6 feature combinations for 2 packages in 0.00s
 
 PASS cli ( 0 errors, 0 warnings, features = [] )
 PASS cli ( 0 errors, 0 warnings, features = [color] )
 PASS engine ( 0 errors, 0 warnings, features = [] )
 PASS engine ( 0 errors, 0 warnings, features = [metrics] )
 PASS engine ( 0 errors, 0 warnings, features = [metrics, tracing] )
 PASS engine ( 0 errors, 0 warnings, features = [tracing] )

Each row is one combination: the package, whether it passed, its error/warning counts, and the exact feature set. A non-zero exit status means at least one combination failed.

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:

The matrix subcommand

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

The `matrix` subcommand#

cargo fc matrix prints the feature matrix as JSON instead of running a command. It’s the bridge to CI: emit the matrix in one job, then fan out a build/test job per row.

cargo fc matrix
cargo fc matrix --pretty

Output shape#

The matrix is a JSON array with one object per combination. Each object carries the package name, the comma-joined features string, the effective target, and any configured metadata:

The override model

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

The override model#

Every setting resolves along one precedence chain, from broadest to narrowest. Once you know the chain and the three ways to write a value, per-target and per-command configuration are just the same rules applied at a narrower scope.

The precedence chain#

Broadest to narrowest:

workspace → package
 within each scope: base → subcommands.<cmd> → target.'cfg(...)' → target.'cfg(...)'.subcommands.<cmd>

A narrower scope overrides a broader one. So a target.'cfg(...)' override beats a bare subcommands.<cmd> one, and a package setting beats the workspace.

CLI reference

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

CLI reference#

The authoritative reference is cargo fc --help. This page mirrors it.

Usage#

cargo fc [+toolchain] [SUBCOMMAND] [SUBCOMMAND_OPTIONS]
cargo fc [+toolchain] [OPTIONS] [CARGO_OPTIONS] [CARGO_SUBCOMMAND]

Subcommands#

Subcommand	Description
`matrix`	Print the JSON feature-combination matrix to stdout. Add `--pretty` for indented JSON.
`version`	Print version information.

Options#

Flag	Description
`-h`, `--help`	Print help information.
`-V`, `--version`	Print version information.
`--manifest-path <path>`	Path to the `Cargo.toml` to inspect.
`-p`, `--package <name>`	Include only this workspace package (repeatable).
`--exclude <name>`	Exclude a workspace package (repeatable). Pairs with `--workspace` for Cargo-compatible selection.
`--diagnostics-only`	Show only diagnostics (warnings/errors) per combination. Requires a command that emits rustc JSON diagnostics (`build`, `check`, `clippy`, `doc`, or an equivalent alias/wrapper).
`--dedupe`	Like `--diagnostics-only`, but also deduplicate identical diagnostics across combinations.
`--summary-only`	Hide cargo output; show only the final summary.
`--fail-fast`	Stop on the first failing combination.
`--errors-only`	Allow all warnings, show errors only (`-A warnings`). Appends to `RUSTFLAGS`.
`--pedantic`	Treat warnings like errors in the summary and under `--fail-fast`.
`--show-pruned`	Show pruned (redundant) combinations in the summary.
`--no-prune-implied`	Disable automatic pruning of redundant combinations.
`--packages-only`	In `matrix` mode, emit one row per package-target instead of per combination.
`--only-packages-with-lib-target`	Only consider packages that have a library target.
`--aggregate-targets`	Batch a combination’s configured targets into a single Cargo invocation (one `--target` each). Faster on many cores; falls back to serial for `run` and pruned summaries.
`--no-targets`	Ignore configured target lists for this run; use Cargo’s default single target.
`--install-missing-targets`	Install missing Rust target components with `rustup` before running. Explicit opt-in — may mutate the toolchain and use the network.
`--driver <bin>`	Program invoked in place of `cargo` for each build (e.g. `cargo-zigbuild`, `cross`). See Build drivers.

Most boolean flags can also be set as defaults in Cargo.toml; CLI flags always win for a single invocation.

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-target configuration

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

Per-target configuration#

Override configuration for specific targets using Cargo-style cfg(...) selectors. This uses the same forms and precedence as everything else — see the override model — applied at a narrower scope.

Overrides live under:

[package.metadata.cargo-fc.target.'cfg(...)']

Example: different features per OS#

[package.metadata.cargo-fc]
exclude_features = ["default"]

[package.metadata.cargo-fc.target.'cfg(target_os = "linux")']
exclude_features = { add = ["metal"] }

[package.metadata.cargo-fc.target.'cfg(target_os = "macos")']
exclude_features = { add = ["cuda"] }

The base excludes default everywhere. On Linux, metal is also excluded (the add unions into the inherited value); on macOS, cuda is. Remember: an array like exclude_features = ["metal"] would have replaced the base instead of extending it.

Per-command configuration

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

Per-command configuration#

Just as you can override configuration per target triple, you can override it per cargo subcommand:

[package.metadata.cargo-fc.subcommands.<command>]

A subcommand override accepts the same feature-matrix keys as a target override — exclude_features, include_features, only_features, the *_feature_sets keys, skip_optional_dependencies, no_empty_feature_set, and matrix — with identical patch semantics.

Example: build it, but don’t test it#

Enable a heavy gpu feature when building, but skip those combinations when testing:

[package.metadata.cargo-fc]
# `gpu` is part of the matrix by default (e.g. for `cargo fc build`).

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

Or restrict cargo fc test to a single focused set:

Flags in config

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

`cargo fc` flags in config#

Most cargo fc boolean flags can be set as defaults in Cargo.toml, using the flag name with _ instead of -. Explicit CLI flags still win for a single invocation.

[workspace.metadata.cargo-fc]
dedupe = true
fail_fast = true

[package.metadata.cargo-fc]
pedantic = false

[package.metadata.cargo-fc.target.'cfg(target_os = "windows")']
errors_only = true

[package.metadata.cargo-fc.target.'cfg(target_os = "windows")'.subcommands.clippy]
dedupe = false

[workspace.metadata.cargo-fc.subcommands.my-custom-cmd]
dedupe = true

Configurable flag keys#

summary_only = true
diagnostics_only = true
dedupe = true
verbose = true
pedantic = true
errors_only = true
packages_only = true
fail_fast = true
prune_implied = true
show_pruned = true
aggregate_targets = true
no_targets = true
install_missing_targets = true
only_packages_with_lib_target = true

dedupe = true implies diagnostics-only output.
prune_implied = false turns off automatic pruning.

Precedence#

Flags resolve broad-to-narrow, with CLI flags last:

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:

FAQ & troubleshooting

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

FAQ & troubleshooting#

How is this different from `--all-features`?#

--all-features enables every feature at once — a single configuration. cargo fc runs many configurations: the combinations of your features. That’s what catches a conflict between two features that each work alone but not together, or a crate that breaks with --no-default-features.

How is this different from `cargo-all-features`?#

Both explore feature combinations. cargo fc adds a single readable summary, diagnostics de-duplication, automatic pruning of redundant combinations, a JSON matrix for CI, per-target and per-command configuration, and driver-based cross-compilation. The skip_optional_dependencies behavior is intentionally compatible.

cargo-feature-combinations

Basics

Configuration basics#

Where configuration lives#

Excluding workspace packages#

Configured targets

Configured targets#

Declaring a target list#

Per-package target lists#

GitHub Actions

GitHub Actions#

Approach 1 — fan out one job per combination#

Incompatible features

Incompatible features#

Introduction

Introduction#

The problem#

Running commands

Running commands#

Forwarded arguments#

Build drivers

Build drivers#

Why a driver#

Installation

Installation#

From crates.io#

Homebrew#

Nix#

Optional dependencies

Optional dependencies#

Output modes

Output modes#

--diagnostics-only#

Shaping the feature matrix

Shaping the feature matrix#

At a glance#

exclude_features#

Installing targets

Installing missing targets#

Opt in per invocation#

Quick start

Quick start#

1. Run a command across the matrix#

Restrict the matrix

Restrict the matrix to specific configurations#

The matrix subcommand

The matrix subcommand#

Output shape#

The override model

The override model#

The precedence chain#

CLI reference

CLI reference#

Usage#

Subcommands#

Options#

Large feature sets

Large, independent feature sets#

Per-target configuration

Per-target configuration#

Example: different features per OS#

Per-command configuration

Per-command configuration#

Example: build it, but don’t test it#

Flags in config

cargo fc flags in config#

Configurable flag keys#

Precedence#

Per-command differences

Build a feature you never test#

Cross-compilation in CI

Cross-compilation in CI#

Declare the targets#

FAQ & troubleshooting

FAQ & troubleshooting#

How is this different from --all-features?#

How is this different from cargo-all-features?#

`--diagnostics-only`#

`exclude_features`#

The `matrix` subcommand#

`cargo fc` flags in config#

How is this different from `--all-features`?#

How is this different from `cargo-all-features`?#