#continuous-integration #cargo-subcommand #cargo #cargo-build #cargo-toml

app cargo-hack

Cargo 子命令,提供各种用于测试和持续集成的有用选项

90 个版本

0.6.31 2024年8月8日
0.6.30 2024年7月15日
0.6.28 2024年4月17日
0.6.23 2024年3月27日
0.3.1 2019年11月20日

Cargo 插件 中排名第 8

Download history 3141/week @ 2024-05-04 3557/week @ 2024-05-11 3087/week @ 2024-05-18 2336/week @ 2024-05-25 2263/week @ 2024-06-01 3036/week @ 2024-06-08 4032/week @ 2024-06-15 2667/week @ 2024-06-22 2474/week @ 2024-06-29 2099/week @ 2024-07-06 3793/week @ 2024-07-13 3227/week @ 2024-07-20 3027/week @ 2024-07-27 3760/week @ 2024-08-03 3366/week @ 2024-08-10 2973/week @ 2024-08-17

每月下载量 13,794

Apache-2.0 OR MIT

175KB
3.5K SLoC

cargo-hack

crates.io license github actions

Cargo 子命令,提供各种用于测试和持续集成的有用选项。

用法

点击以显示完整选项列表
$ 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.

        --locked
            Require Cargo.lock is up to date.

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

            This treats the specified features as if it were a single feature.

            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.

        --mutually-exclusive-features <FEATURES>...
            Space or comma separated list of features to not use together.

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

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

        --at-least-one-of <FEATURES>...
            Space or comma separated list of features. Skips sets of features that don't enable any
            of the features listed.

            To specify multiple groups, use this option multiple times: `--at-least-one-of a,b
            --at-least-one-of 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.

        --no-private
            Perform without `publish = false` crates.

        --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 be used with --features, --include-features, or --group-features.

        --rust-version
            Perform commands on `package.rust-version`.

            This cannot be used with --version-range.

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

            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.

            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.

        --partition <M/N>
            Partition runs and execute only its subset according to M/N.

        --log-group <KIND>
            Log grouping: none, github-actions.

            If this option is not used, the environment will be automatically detected.

        --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 实际上是 cargo 的包装器,将子命令和大多数传递的标志传播到 cargo,但提供额外的标志并更改一些现有标志的行为。

--each-feature

为每个功能执行,包括默认功能和包的 --no-default-features

这有助于检查每个功能是否正常工作。(当用于此目的时,建议与 --no-dev-deps 一起使用,以避免 cargo#4866。)

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

另请参阅调整 --each-feature 和 --feature-powerset 行为的选项部分。

--feature-powerset

为功能幂集执行,包括 --no-default-features 和包的默认功能。

这有助于检查每个功能组合是否正常工作。(当用于此目的时,建议与 --no-dev-deps 一起使用,以避免 cargo#4866。)

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

cargo-hack 根据 cargo 功能的工作方式消除任何完全等效的功能组合。因此,它可能比其他方式检查所有功能组合更有效。

当使用此标志导致特征组合数量非常大时,请考虑使用 --depth 选项。

另请参阅调整 --each-feature 和 --feature-powerset 行为的选项部分。

调整 --each-feature 和 --feature-powerset 行为的选项

以下标志可以与 --each-feature--feature-powerset 一起使用。

--optional-deps

将可选依赖项用作特征。

默认情况下,此标志将所有选项依赖项视为特征。要仅将特定依赖项视为特征,请传递空格或逗号分隔的列表。

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

--exclude-features, --skip

要排除的特征的空格或逗号分隔列表。

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

--depth

指定 --feature-powerset 的最大同时特征标志数。

如果数字设置为 1,则 --feature-powerset 等同于 --each-feature

--group-features

要分组的特征的空格或逗号分隔列表。

这会将指定的特征视为单个特征。

要指定多个组,多次使用此选项:--group-features a,b --group-features c,d

--rust-version

Cargo.toml 中的 package.rust-version 字段上执行命令

--version-range

在指定的(包含)Rust版本范围内执行命令。

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

(我们使用 rustup run <toolchain> cargo 而不是 cargo +<toolchain> 来解决 rustup bug。)

这可能有助于捕获类似 termcolor#35regex#685rust-clippy#6324 的问题。

如果省略范围的上限,则使用最新稳定编译器作为上限。

如果省略范围的下限,则使用 Cargo.tomlrust-version 字段的值作为下限。

您可以通过使用 --version-step 来指定版本间隔。

--no-dev-deps

不包含开发依赖项执行。

这是解决开发依赖项泄漏到正常构建(cargo#4866)的问题的解决方案。

此外,这也可以用作解决 cargo 不允许发布具有循环开发依赖项的包的问题的解决方案。(cargo#4242

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

注意:当前,使用 --no-dev-deps 标志在 cargo-hack 运行时从实际清单中删除开发依赖项,并在完成后恢复。有关为什么这是必要的,请参阅 cargo#4242。此外,此行为可能在某些子命令中在未来发生变化。请参阅 #15

--remove-dev-deps

等同于 --no-dev-deps,但执行后不会恢复原始 Cargo.toml

这有助于了解 cargo-hack 实际上与 --no-dev-deps 一起使用哪个 Cargo.toml

此标志也可以在没有子命令的情况下工作。

--ignore-private

跳过在 publish = false 包上执行。

--no-private

不包含 publish = false 包执行。这与 --ignore-private 类似,但更强大,因为它还防止私有包影响锁文件和元数据。

注意:当 cargo-hack 运行时,--no-private 标志会修改 Cargo.toml,并在完成后恢复。

--ignore-unknown-features

如果该功能不存在,则跳过将 --features 传递给 cargo

--clean-per-run

在运行命令之前删除该包的构建产物。

这也可作为rust-clippy#4612的解决方案。

改进现有 cargo 标志的行为

cargo-hack 改变了以下现有标志的行为。

--features, --no-default-features

cargo 不同(cargo#3620cargo#4106cargo#4463cargo#4753cargo#5015cargo#5364cargo#6195),它也可以应用于子仓库名。

--all, --workspace

对工作空间中的所有包执行命令。

与 cargo 不同,它不会一次性编译所有成员。

例如,在一个包含成员 foobar 的工作空间中运行 cargo hack check --all 的行为几乎与以下脚本相同

# 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

工作空间成员将按照cargo metadata中'packages'字段的顺序执行。

安装

从源代码

cargo +stable install cargo-hack --locked

目前,安装 cargo-hack 需要 rustc 1.70+。

cargo-hack 通常可以使用比安装所需的 Rust 版本更旧的 Cargo 版本运行(例如,cargo +1.31 hack check)。目前,要运行 cargo-hack 需要 Cargo 1.26+。

从预构建的二进制文件

您可以从发布页面下载预构建的二进制文件。预构建的二进制文件适用于 macOS、Linux(gnu 和 musl)、Windows(静态可执行文件)、FreeBSD 和 illumos。

cargo-hack 下载脚本的示例
# Get host target
host=$(rustc -vV | grep '^host:' | cut -d' ' -f2)
# Download binary and install to $HOME/.cargo/bin
curl --proto '=https' --tlsv1.2 -fsSL https://github.com/taiki-e/cargo-hack/releases/latest/download/cargo-hack-$host.tar.gz | tar xzf - -C "$HOME/.cargo/bin"

在 GitHub Actions 中

您可以使用 taiki-e/install-action 在 Linux、macOS 和 Windows 上安装预构建的二进制文件。这可以使安装更快,并可能避免上游更改引起的问题

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

通过 Homebrew

您可以从我们维护的Homebrew tap 安装 cargo-hack(x86_64/aarch64 macOS,x86_64/aarch64 Linux)。

brew install taiki-e/tap/cargo-hack

通过 Scoop(Windows)

您可以从我们维护的Scoop bucket 安装 cargo-hack。

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

通过 cargo-binstall

您可以使用 cargo-binstall 安装 cargo-hack。

cargo binstall cargo-hack

通过 pacman(Arch Linux)

您可以从extra 仓库安装 cargo-hack。

pacman -S cargo-hack

许可证

许可协议为Apache License,版本2.0MIT许可证,任选其一。

除非您明确说明,否则您提交的任何有意包含在作品中的贡献(根据Apache-2.0许可证的定义),均应双重许可如上,不附加任何额外条款或条件。

依赖项

~5–13MB
~156K SLoC