• Stars
    star
    379
  • Rank 113,004 (Top 3 %)
  • Language
    Rust
  • License
    Apache License 2.0
  • Created about 5 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Cargo subcommand to provide various options useful for testing and continuous integration.

cargo-hack

crates.io license build status

Cargo subcommand to provide various options useful for testing and continuous integration.

Usage

Click to show a complete list of options
$ cargo hack --help
cargo-hack
Cargo subcommand to provide various options useful for testing and continuous integration.

USAGE:
    cargo hack [OPTIONS] [SUBCOMMAND]

Use -h for short descriptions and --help for more details.

OPTIONS:
    -p, --package <SPEC>...
            Package(s) to check.

        --all
            Alias for --workspace.

        --workspace
            Perform command for all packages in the workspace.

        --exclude <SPEC>...
            Exclude packages from the check.

            This flag can only be used together with --workspace

        --manifest-path <PATH>
            Path to Cargo.toml.

    -F, --features <FEATURES>...
            Space or comma separated list of features to activate.

        --each-feature
            Perform for each feature of the package.

            This also includes runs with just --no-default-features flag, and default features.

            When this flag is not used together with --exclude-features (--skip) and
            --include-features and there are multiple features, this also includes runs with just
            --all-features flag.

        --feature-powerset
            Perform for the feature powerset of the package.

            This also includes runs with just --no-default-features flag, and default features.

            When this flag is used together with --depth or namespaced features (-Z
            namespaced-features) and not used together with --exclude-features (--skip) and
            --include-features and there are multiple features, this also includes runs with just
            --all-features flag.

        --optional-deps [DEPS]...
            Use optional dependencies as features.

            If DEPS are not specified, all optional dependencies are considered as features.

            This flag can only be used together with either --each-feature flag or
            --feature-powerset flag.

        --skip <FEATURES>...
            Alias for --exclude-features.

        --exclude-features <FEATURES>...
            Space or comma separated list of features to exclude.

            To exclude run of default feature, using value `--exclude-features default`.

            To exclude run of just --no-default-features flag, using --exclude-no-default-features
            flag.

            To exclude run of just --all-features flag, using --exclude-all-features flag.

            This flag can only be used together with either --each-feature flag or
            --feature-powerset flag.

        --exclude-no-default-features
            Exclude run of just --no-default-features flag.

            This flag can only be used together with either --each-feature flag or
            --feature-powerset flag.

        --exclude-all-features
            Exclude run of just --all-features flag.

            This flag can only be used together with either --each-feature flag or
            --feature-powerset flag.

        --depth <NUM>
            Specify a max number of simultaneous feature flags of --feature-powerset.

            If NUM is set to 1, --feature-powerset is equivalent to --each-feature.

            This flag can only be used together with --feature-powerset flag.

        --group-features <FEATURES>...
            Space or comma separated list of features to group.

            To specify multiple groups, use this option multiple times: `--group-features a,b
            --group-features c,d`

            This flag can only be used together with --feature-powerset flag.

        --include-features <FEATURES>...
            Include only the specified features in the feature combinations instead of package
            features.

            This flag can only be used together with either --each-feature flag or
            --feature-powerset flag.

        --no-dev-deps
            Perform without dev-dependencies.

            Note that this flag removes dev-dependencies from real `Cargo.toml` while cargo-hack is
            running and restores it when finished.

        --remove-dev-deps
            Equivalent to --no-dev-deps flag except for does not restore the original `Cargo.toml`
            after performed.

        --ignore-private
            Skip to perform on `publish = false` packages.

        --ignore-unknown-features
            Skip passing --features flag to `cargo` if that feature does not exist in the package.

            This flag can only be used together with either --features or --include-features.

        --version-range <START>..[END]
            Perform commands on a specified (inclusive) range of Rust versions.

            If the given range is unclosed, the latest stable compiler is treated as the upper
            bound.

            Note that ranges are always inclusive ranges.

        --version-step <NUM>
            Specify the version interval of --version-range (default to `1`).

            This flag can only be used together with --version-range flag.

        --clean-per-run
            Remove artifacts for that package before running the command.

            If used this flag with --workspace, --each-feature, or --feature-powerset, artifacts
            will be removed before each run.

            Note that dependencies artifacts will be preserved.

        --clean-per-version
            Remove artifacts per Rust version.

            Note that dependencies artifacts will also be removed.

            This flag can only be used together with --version-range flag.

        --keep-going
            Keep going on failure.

        --print-command-list
            Print commands without run (Unstable).

        --no-manifest-path
            Do not pass --manifest-path option to cargo (Unstable).

    -v, --verbose
            Use verbose output.

        --color <WHEN>
            Coloring: auto, always, never.

            This flag will be propagated to cargo.

    -h, --help
            Prints help information.

    -V, --version
            Prints version information.

Some common cargo commands are (see all commands with --list):
    build       Compile the current package
    check       Analyze the current package and report errors, but don't build object files
    run         Run a binary or example of the local package
    test        Run the tests

cargo-hack is basically wrapper of cargo that propagates subcommand and most of the passed flags to cargo, but provides additional flags and changes the behavior of some existing flags.

--each-feature

Perform for each feature which includes default features and --no-default-features of the package.

This is useful to check that each feature is working properly. (When used for this purpose, it is recommended to use with --no-dev-deps to avoid cargo#4866.)

cargo hack check --each-feature --no-dev-deps

See also Options for adjusting the behavior of --each-feature and --feature-powerset section.

--feature-powerset

Perform for the feature powerset which includes --no-default-features and default features of the package.

This is useful to check that every combination of features is working properly. (When used for this purpose, it is recommended to use with --no-dev-deps to avoid cargo#4866.)

cargo hack check --feature-powerset --no-dev-deps

cargo-hack deduplicate any fully equivalent feature combinations based on how the cargo features work. Therefore, it may be more efficient than checking all feature combinations in other ways.

When using this flag results in a very large number of feature combinations, consider using --depth option.

See also Options for adjusting the behavior of --each-feature and --feature-powerset section.

Options for adjusting the behavior of --each-feature and --feature-powerset

The following flags can be used with --each-feature and --feature-powerset.

--optional-deps

Use optional dependencies as features.

This flag treats all option dependencies as features by default. To treat only specific dependencies as features, pass a space or comma separated list.

cargo hack check --feature-powerset --optional-deps deps1,deps2

--exclude-features, --skip

Space or comma separated list of features to exclude.

cargo hack check --feature-powerset --exclude-features feature1,feature2
cargo hack check --feature-powerset --skip feature1,feature2

--depth

Specify a max number of simultaneous feature flags of --feature-powerset.

If the number is set to 1, --feature-powerset is equivalent to --each-feature.

--group-features

Space or comma separated list of features to group.

To specify multiple groups, use this option multiple times: --group-features a,b --group-features c,d

--version-range

Perform commands on a specified (inclusive) range of Rust versions.

$ cargo hack check --version-range 1.46..1.47
info: running `cargo +1.46 check` on cargo-hack (1/2)
...
info: running `cargo +1.47 check` on cargo-hack (2/2)
...

This might be useful for catching issues like termcolor#35, regex#685, rust-clippy#6324.

If the upper bound of the range is omitted, the latest stable compiler is used as the upper bound.

If the lower bound of the range is omitted, the value of the rust-version field in Cargo.toml is used as the lower bound.

You can specify the version interval by using --version-step.

--no-dev-deps

Perform without dev-dependencies.

This is a workaround for an issue that dev-dependencies leaking into normal build (cargo#4866).

Also, this can be used as a workaround for an issue that cargo does not allow publishing a package with cyclic dev-dependencies. (cargo#4242)

cargo hack publish --no-dev-deps --dry-run --allow-dirty

Note: Currently, using --no-dev-deps flag removes dev-dependencies from real manifest while cargo-hack is running and restores it when finished. See cargo#4242 for why this is necessary. Also, this behavior may change in the future on some subcommands. See also #15.

--remove-dev-deps

Equivalent to --no-dev-deps except for does not restore the original Cargo.toml after execution.

This is useful to know what Cargo.toml that cargo-hack is actually using with --no-dev-deps.

This flag also works without subcommands.

--ignore-private

Skip to perform on publish = false packages.

--ignore-unknown-features

Skip passing --features to cargo if that feature does not exist.

--clean-per-run

Remove artifacts for that package before running the command.

This also works as a workaround for rust-clippy#4612.

Improvement of the behavior of existing cargo flags

cargo-hack changes the behavior of the following existing flags.

--features, --no-default-features

Unlike cargo (cargo#3620, cargo#4106, cargo#4463, cargo#4753, cargo#5015, cargo#5364, cargo#6195), it can also be applied to sub-crates.

--all, --workspace

Perform command for all packages in the workspace.

Unlike cargo, it does not compile all members at once.

For example, running cargo hack check --all in a workspace with members foo and bar behaves almost the same as the following script:

# If you use cargo-hack, you don't need to maintain this list manually.
members=("foo" "bar")

for member in "${members[@]}"; do
    cargo check --manifest-path "${member}/Cargo.toml"
done

Workspace members will be performed according to the order of the 'packages' fields of cargo metadata.

Installation

From source

cargo +stable install cargo-hack --locked

Compiler support: requires rustc 1.64+

cargo-hack is usually runnable with Cargo versions older than the Rust version required for installation (e.g., cargo +1.31 hack check). Currently, to run cargo-hack requires Cargo 1.26+.

From prebuilt binaries

You can download prebuilt binaries from the Release page. Prebuilt binaries are available for macOS, Linux (gnu and musl), Windows (static executable), and FreeBSD.

Example of script to download cargo-hack
# Get host target
host=$(rustc -Vv | grep host | sed 's/host: //')
# Download binary and install to $HOME/.cargo/bin
curl -LsSf https://github.com/taiki-e/cargo-hack/releases/latest/download/cargo-hack-$host.tar.gz | tar xzf - -C $HOME/.cargo/bin

On GitHub Actions

You can use taiki-e/install-action to install prebuilt binaries on Linux, macOS, and Windows. This makes the installation faster and may avoid the impact of problems caused by upstream changes.

- uses: taiki-e/install-action@cargo-hack

Via Homebrew

You can install cargo-hack using Homebrew tap on macOS and Linux:

brew install taiki-e/tap/cargo-hack

Via Scoop (Windows)

You can install cargo-hack using Scoop:

scoop bucket add taiki-e https://github.com/taiki-e/scoop-bucket
scoop install cargo-hack

Via cargo-binstall

You can install cargo-hack using cargo-binstall:

cargo binstall cargo-hack

Via AUR (Arch Linux)

You can install cargo-hack from AUR:

paru -S cargo-hack

Note: AUR package is maintained by community, not maintainer of cargo-hack.

Related Projects

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

More Repositories

1

cargo-llvm-cov

Cargo subcommand to easily use LLVM source-based code coverage (-C instrument-coverage).
Rust
741
star
2

pin-project

A crate for safe and ergonomic pin-projection.
Rust
447
star
3

auto_enums

A library for to allow multiple return types by automatically generated enum.
Rust
303
star
4

install-action

GitHub Action for installing development tools (mainly from GitHub Releases).
Shell
256
star
5

futures-async-stream

Async stream for Rust and the futures crate.
Rust
167
star
6

upload-rust-binary-action

GitHub Action for building and uploading Rust binary to GitHub Releases.
Shell
163
star
7

pin-project-lite

A lightweight version of pin-project written with declarative macros.
Rust
135
star
8

portable-atomic

Portable atomic types including support for 128-bit atomics, atomic float, etc.
Rust
96
star
9

create-gh-release-action

GitHub Action for creating GitHub Releases based on changelog.
Shell
60
star
10

parse-changelog

Simple changelog parser, written in Rust.
Rust
46
star
11

replace-await

Migration tool for replacing await! macro with await syntax.
Rust
41
star
12

cargo-minimal-versions

Cargo subcommand for proper use of -Z minimal-versions and -Z direct-minimal-versions.
Rust
40
star
13

easy-ext

A lightweight attribute macro for easily writing extension trait pattern.
Rust
36
star
14

derive_utils

A procedural macro helper for easily writing custom derives for enums.
Rust
25
star
15

const_fn

A lightweight attribute for easy generation of const functions with conditional compilations.
Rust
23
star
16

atomic-memcpy

Byte-wise atomic memcpy.
Rust
21
star
17

setup-cross-toolchain-action

GitHub Action for setup toolchains for cross compilation and cross testing for Rust.
Shell
21
star
18

syn-serde

Library to serialize and deserialize Syn syntax trees.
Rust
15
star
19

futures-enum

#[derive(Future, Stream, Sink, AsyncRead, AsyncWrite, AsyncSeek, AsyncBufRead)] for enums.
Rust
13
star
20

atomic-maybe-uninit

Atomic operations on potentially uninitialized integers.
Rust
13
star
21

easytime

Providing wrapper types for safely performing panic-free checked arithmetic on instants and durations.
Rust
13
star
22

rust-cross-toolchain

Toolchains for cross compilation and cross testing for Rust.
Shell
12
star
23

cargo-no-dev-deps

Cargo subcommand for running cargo without dev-dependencies.
Rust
11
star
24

cargo-config2

Load and resolve Cargo configuration.
Rust
10
star
25

iter-enum

#[derive(Iterator, DoubleEndedIterator, ExactSizeIterator, FusedIterator, Extend)] for enums.
Rust
9
star
26

negative-impl

Negative trait implementations on stable Rust.
Shell
9
star
27

coverage-helper

Helper for https://github.com/taiki-e/cargo-llvm-cov/issues/123.
Shell
6
star
28

find-crate

Find the crate name from the current Cargo.toml.
Rust
5
star
29

syn-mid

Providing the features between "full" and "derive" of syn.
Rust
5
star
30

assert-unmoved

A type that asserts that the underlying type is not moved after being pinned and mutably accessed.
Rust
4
star
31

cache-cargo-install-action

GitHub Action for `cargo install` with cache.
Shell
4
star
32

io-enum

#[derive(Read, Write, Seek, BufRead)] for enums.
Shell
4
star
33

semihosting

Semihosting for AArch64, ARM, RISC-V, MIPS, and MIPS64
Rust
3
star
34

target-spec-json

Structured access to rustc --print target-spec-json and --print all-target-specs-json.
Rust
2
star
35

build-context

Make build environment/target information available as constants in normal libraries and binaries.
Shell
2
star
36

github-actions

Shell
2
star
37

iced_style_config

Create Iced style sheets from configuration files.
Rust
2
star
38

dependabot-config

Structured access to the Dependabot configuration file.
Rust
2
star
39

taiki-e

1
star
40

workflows

Shell
1
star
41

checkout-action

GitHub Action for checking out a repository. (Simplified actions/checkout alternative without depending on Node.js.)
Shell
1
star
42

test

Shell
1
star
43

dockerfiles

Shell
1
star