Documentation on cargo-feature-combinations

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.

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):

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.

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.

Documentation on cargo-feature-combinations

Introduction

Introduction#

The problem#

Installation

Installation#

From crates.io#

Homebrew#

Nix#

Quick start

Quick start#

1. Run a command across the matrix#

FAQ & troubleshooting

FAQ & troubleshooting#

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

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

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

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