#cargo-command #cargo-build #cargo #features #combination #cargo-subcommand

bin+lib cargo-feature-combinations

run cargo commands for all feature combinations

16 releases

0.0.20 Sep 22, 2024
0.0.19 Mar 8, 2024
0.0.16 Jan 20, 2024
0.0.15 Jul 3, 2023
0.0.5 Nov 20, 2022

#182 in Cargo plugins

Custom license

1MB
678 lines

cargo-feature-combinations

build status test status crates.io

Plugin for cargo to run commands against selected combinations of features.

Installation

cargo install cargo-feature-combinations

Usage

In most cases, just use the command as if it was cargo. However, there are a few optional flags and the matrix subcommand.

cargo feature-combinations check

To save time, you can also use the shortened name cargo fc:

cargo fc test
cargo fc --fail-fast test
cargo fc build
cargo fc --silent build
cargo fc matrix

For details, please refer to --help:

$ cargo fc --help

USAGE:
    cargo [+toolchain] [SUBCOMMAND] [SUBCOMMAND_OPTIONS]
    cargo [+toolchain] [OPTIONS] [CARGO_OPTIONS] [CARGO_SUBCOMMAND]

SUBCOMMAND:
    matrix                  Print JSON feature combination matrix to stdout
        --pretty            Print pretty JSON

OPTIONS:
    --help                  Print help information
    --silent                Hide cargo output and only show summary
    --fail-fast             Fail fast on the first bad feature combination
    --errors-only           Allow all warnings, show errors only (-Awarnings)
    --pedantic              Treat warnings like errors in summary and
                            when using --fail-fast

Configuration

In your Cargo.toml, you can configure the feature combination matrix:

[package.metadata.cargo-feature-combinations]
# Exclude groupings of features that are incompatible or do not make sense
skip_feature_sets = [ ["foo", "bar"], ]

# Exclude features from the feature combination matrix
denylist = ["default", "full"]

Usage with github-actions

The github-actions matrix feature allows more efficient testing of all feature set combinations in CI.

The following workflow file uses cargo-feature-combinations to automatically generate a feature matrix and runs up to 256 feature combinations in a matrix job.

# TODO: embed example

Local development

For local development and testing, you can point cargo fc to another project using the --manifest-path flag.

cargo run -- cargo check --manifest-path ../path/to/Cargo.toml
cargo run -- cargo matrix --manifest-path ../path/to/Cargo.toml --pretty

Linting

cargo clippy --tests --benches --examples -- -Dclippy::all -Dclippy::pedantic

Acknowledgements

The cargo-all-features crate is similar yet offers more complex configuration and is lacking a summary.

TODO

  • allow adding custom data to matrix output
  • embed the help output using embedme.
  • add a github actions workflow file example.

Dependencies

~9–19MB
~260K SLoC