Configuration on 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.

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.

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.

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:

Configuration on cargo-feature-combinations

Basics

Configuration basics#

Where configuration lives#

Excluding workspace packages#

Shaping the feature matrix

Shaping the feature matrix#

At a glance#

exclude_features#

The override model

The override model#

The precedence chain#

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#

`exclude_features`#

`cargo fc` flags in config#