# cargo-matrix
## Current Releases
### cargo-matrix
[](https://crates.io/crates/cargo-matrix)
[](https://crates.io/crates/cargo-matrix)
[](https://crates.io/crates/cargo-matrix)
### CI/CD
[](https://github.com/rustyhorde/cargo-matrix/actions)
`cargo-matrix` is a Cargo subcommand that runs feature matrices against cargo commands. For each
crate in your workspace it discovers all features, generates every valid combination (the powerset),
and runs `cargo build`, `check`, `clippy`, `test`, or `llvm-cov` against each combination with
`--no-default-features`. This ensures your crate compiles and tests correctly regardless of which
subset of features a user enables.
## Installation
```sh
cargo install cargo-matrix
```
## Usage
```sh
# Check every feature combination across the entire workspace
cargo matrix check
# Build every combination
cargo matrix build
# Lint every combination (pass extra flags after --)
cargo matrix clippy -- -- -D warnings
# Test every combination
cargo matrix test
# Measure coverage across every combination
cargo matrix llvm-cov
# Dry run — print what would be run without executing anything
cargo matrix --dry-run check
# Run against a specific package only
cargo matrix --package my-crate check
# Select a named channel (see Configuration below)
cargo matrix --channel nightly clippy
# Point at a workspace that isn't in the current directory
cargo matrix --manifest-path path/to/Cargo.toml check
# Split the workspace into chunks for parallel CI jobs (e.g. three jobs, run the second)
cargo matrix --num-chunks 3 --chunk 2 test
```
Any flags after the subcommand `--` separator are forwarded verbatim to cargo:
```sh
cargo matrix test -- --test-thread=1
cargo matrix clippy -- -- -D warnings -A clippy::pedantic
```
## Configuration
Configure each crate via `[package.metadata.cargo-matrix]` in its `Cargo.toml`. All fields are
optional — without any configuration `cargo-matrix` uses the full feature powerset.
Configuration is grouped into named *channels*, which lets you maintain different filter sets for
different toolchains or purposes (e.g. `default`, `nightly`, `llvm-cov`). Select a channel at
runtime with `--channel <name>`. When a named channel does not define a field, the value falls back
to the `"default"` channel.
```toml
[package]
name = "my-crate"
# ...
[features]
foo = []
bar = []
baz = ["dep:serde"]
unstable = []
__internal = []
[dependencies]
serde = { version = "1", optional = true }
[package.metadata.cargo-matrix]
# ── default channel ────────────────────────────────────────────────────────────
[[package.metadata.cargo-matrix.channel]]
name = "default"
# Never include these features in any generated combination.
always_deny = ["unstable"]
# Always add these features to every combination.
always_include = []
# Drop these exact combinations from the matrix.
skip = [["foo", "baz"]]
# Feature groups — any combination containing two or more features from the
# same group is excluded. Useful for mutually exclusive backends or runtimes.
mutually_exclusive = [["foo", "bar"]]
# Override the powerset seed entirely. When set, only these features are
# combined; the package's full feature list is ignored.
# seed = ["foo", "bar"]
# Include features whose names start with "__" (hidden/internal features).
# Defaults to false.
include_hidden = false
# Automatically include every optional dependency as a feature.
include_all_optional = false
# Include specific optional dependencies as features, independent of
# include_all_optional.
include_optional = ["serde"]
# ── nightly channel ────────────────────────────────────────────────────────────
[[package.metadata.cargo-matrix.channel]]
name = "nightly"
# Override just what differs from the default channel.
always_deny = []
always_include = ["unstable"]
include_hidden = true
```
### Channel field reference
| `name` | `string` | Channel identifier. `"default"` is the fallback for all other channels. |
| `seed` | `[string]` | If set, use only these features as the powerset input instead of the package's full feature list. |
| `always_deny` | `[string]` | Features excluded from every generated combination. |
| `always_include` | `[string]` | Features added to every generated combination. |
| `skip` | `[[string]]` | Exact feature sets to drop from the matrix. |
| `mutually_exclusive` | `[[string]]` | Feature groups where at most one member may appear in any combination. |
| `include_hidden` | `bool` | Include `__`-prefixed features in the powerset. Defaults to `false`. |
| `include_all_optional` | `bool` | Add every optional dependency as a feature. Defaults to `false`. |
| `include_optional` | `[string]` | Add specific optional dependencies as features. |
## License
Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or
[MIT license](LICENSE-MIT) at your option.