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

cargo-fc passes --no-default-features to every invocation, then enables the features in the current row. The empty row ([]) therefore enables no features. A row containing default reproduces an ordinary Cargo default-feature invocation; do not exclude default when the matrix must cover that configuration.

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.

Running only maximal feature sets#

Use --maximal-features when a command needs broad feature reachability but not every feature interaction as a separate invocation. Cargo-fc keeps only the maximal feature sets of each package-target matrix: combinations that are not a subset of another generated combination. In an unconstrained matrix the full feature set is itself a combination, so everything collapses into a single all-features run. Mutually exclusive features, excluded combinations, isolated feature sets, and target-specific feature rules stay in force and keep one run per remaining maximal alternative. The same collapse applies to cargo fc matrix output.

Unused-dependency auditing with cargo-udeps is a useful example:

cargo +nightly fc udeps --maximal-features --all-targets -p my-crate

This makes dependencies behind valid feature gates visible without Cargo’s naive --all-features, which may combine backends or platform features that the matrix deliberately keeps apart. Cargo-fc has no udeps-specific behavior: it only supplies the generated --no-default-features --features=... arguments and forwards the custom command.

Like every other boolean flag, maximal_features can also be set as a config default in any scope. For example, to make cargo fc udeps always run maximal without the CLI flag:

[workspace.metadata.cargo-fc.subcommands.udeps]
maximal_features = true

The flag resolves per package-target through the normal precedence chain, so one package can collapse while another keeps its full matrix; --maximal-features on the CLI still overrides config for a single invocation.

Maximal mode is not a replacement for an exhaustive matrix when feature interactions are the thing being tested. Keep ordinary cargo fc check, clippy, and test runs for that coverage.

Package selection#

In a workspace, cargo fc runs the selected packages. Use cargo’s own selection flags:

# One package
cargo fc check -p engine

# The whole workspace, excluding one package
cargo fc check --workspace --exclude examples

--exclude is accepted for Cargo-compatible workspace selection. You can also exclude packages permanently in workspace metadata — see Configuration basics.

Toolchains#

A leading +toolchain works exactly like it does with cargo, and it may come either before or after fc:

cargo +nightly fc check
cargo fc +nightly check

cargo fc resolves the override through rustup and pins every invocation to that toolchain via RUSTUP_TOOLCHAIN and CARGO, so the toolchain also reaches rustc, any build driver, and the Cargo a wrapper alias spawns. A child env setting for either variable wins. When cargo fc installs missing target components (see Installing targets), it passes the same override to rustup.

Because the token never has to survive as an argument, the second form works from a cargo alias body — which the first form cannot do, since rustup only reads +toolchain from the very first argument, long before the alias is expanded:

# .cargo/config.toml
[alias]
unused = "fc +nightly udeps --maximal-features --all-targets"

# Runs cargo-udeps on nightly, no `+nightly` needed at the prompt
cargo unused

An unknown toolchain is an error rather than a silent fallback to the current one. If rustup is not installed at all, +toolchain is left in the forwarded arguments for the build driver to interpret.

Built-in commands and aliases#

cargo fc recognizes these built-in cargo commands, including their short aliases: build (b), check (c), clippy, doc (d), test (t), and run (r). Recognized commands automatically gain capabilities such as configured targets.

cargo fc also resolves aliases from your .cargo/config.toml before running. If an alias expands to a built-in, it inherits that built-in’s behavior:

# .cargo/config.toml
[alias]
lint = "clippy --all-targets --no-deps"

# Behaves like `cargo fc clippy`
cargo fc lint

A custom command that does not resolve to a built-in runs across the matrix all the same, but you must opt in explicitly to give it target or diagnostics capabilities. See Per-command configuration.

Pointing at another project#

For local development you can inspect a manifest elsewhere:

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