cargo-hakari

cargo hakari 是一个命令行应用程序，用于管理 workspace-hack 包。通过它，您可以通过 15-95% 的速度提高本地的 cargo build 和 cargo check 命令，累积起来可以提升 20-25% 或更多。

有关 workspace-hack 包是什么以及它们如何使您的构建更快的说明，请参阅 about 模块。

示例

cargo-guppy 仓库使用由 cargo hakari 管理的 workspace-hack 包。 查看生成的 Cargo.toml。

平台支持

• Unix 平台：Hakari 可以正常工作并且受到支持。
• Windows：Hakari 可以正常工作并且以正斜杠为路径输出文件路径，以与 Unix 保持一致。不支持 workspace-hack 的 Cargo.toml 中的 CRLF 行结束符。在 Git 仓库中，cargo hakari init 会自动为您执行此操作。 这是手动执行此操作的方法。 (欢迎通过拉取请求改进此功能。)

安装

发布版本二进制文件

发布版本二进制文件可在 GitHub 发布 上找到，通过 cargo binstall 使用。

cargo binstall cargo-hakari

在 GitHub Actions CI 中，使用 taiki-e/install-action，它底层使用 cargo binstall

- name: Install cargo-hakari
  uses: taiki-e/install-action@v2
   with:
     tool: cargo-hakari

从源安装

要安装或更新 cargo-hakari，运行

cargo install cargo-hakari --locked

如果 $HOME/.cargo/bin 在您的 PATH 中，则 cargo hakari 命令将可用。

用法

入门

为了使 cargo hakari 正确工作，您必须采取以下四个步骤。

1. 检查您的 Cargo.lock

为了使 hakari 正确工作，您必须将您的 Cargo.lock 添加到版本控制中，即使您没有任何二进制crate也是如此。这是因为依赖项的补丁版本提升可能会添加或删除功能，甚至整个传递依赖项。

2. 初始化工作区-hack

在工作区路径 my-workspace-hack 处初始化工作区-hack crate

cargo hakari init my-workspace-hack

3. 生成 Cargo.toml

生成或更新工作区-hack crate 的内容

cargo hakari generate

4. 将依赖项添加到工作区-hack

将工作区-hack crate 作为依赖项添加到所有其他工作区 crate 中

cargo hakari manage-deps

使 hakari 工作良好

以下是一些并非绝对必要做的事情，但会使 cargo hakari 工作得更好。

1. 更新 hakari 配置

打开 .config/hakari.toml，然后

• 取消注释或添加常用的开发者平台
• 阅读关于解析器的说明，并强烈考虑在您的 Cargo.toml 中设置 resolver = "2"。

记住在更改配置后运行 cargo hakari generate。

2. 在 CI 中保持工作区-hack 的最新状态

在 CI 中运行以下命令

cargo hakari generate --diff  # workspace-hack Cargo.toml is up-to-date
cargo hakari manage-deps --dry-run  # all workspace crates depend on workspace-hack

如果这些命令中的任何一个以非零状态退出，您可以选择使 CI 失败或生成警告消息。

有关示例，请参阅 此 GitHub action，用于 cargo-guppy。

所有 cargo hakari 命令都接受一个 --quiet 选项来抑制输出，尽管在 CI 中显示 diff 输出通常很有用。

3. 考虑一个 patch 指令

如果您的 workspace 作为 Git 或路径依赖项被依赖，强烈建议您遵循 patch 指令部分 中的说明。

关于工作区-hack 的信息

本节中的命令提供了关于工作区-hack 组件的信息。

为什么工作区中有一个依赖项？

打印出关于为什么在工作区中存在依赖的信息

cargo hakari explain <dependency-name>

工作区-hack 是否确保每个依赖项仅使用一个功能集进行构建？

cargo hakari verify

如果某些依赖项使用多个功能集进行构建，此命令将打印有关它们的详细信息。这始终是一个错误——如果您遇到这种情况，请提交包含更多信息的错误报告将非常感谢！

发布 crate

如果您向 crates.io 或其他注册表发布 crate，请参阅 publishing 模块。

禁用和卸载

通过从 Cargo.toml 中删除生成的行来暂时禁用 workspace-hack crate。（通过运行 cargo hakari generate 来重新启用。）

cargo hakari disable

从所有其他工作区 crate 中删除 workspace-hack crate 作为依赖项

cargo hakari remove-deps

配置

cargo hakari 通过工作区根目录下的 .config/hakari.toml 进行配置。运行 cargo hakari init 将在此位置创建一个新文件。

示例配置

# The name of the package used for workspace-hack unification.
hakari-package = "workspace-hack"
# Cargo resolver version in use -- version 2 is highly recommended.
resolver = "2"

# Format for `workspace-hack = ...` lines in other Cargo.tomls. Version 2 requires cargo-hakari
# 0.9.8 or above.
dep-format-version = "2"

# Add triples corresponding to platforms commonly used by developers here.
# https://doc.rust-lang.net.cn/rustc/platform-support.html
platforms = [
    # "x86_64-unknown-linux-gnu",
    # "x86_64-apple-darwin",
    # "x86_64-pc-windows-msvc",
]

# Write out exact versions rather than specifications. Set this to true if version numbers in
# `Cargo.toml` and `Cargo.lock` files are kept in sync, e.g. in some configurations of
# https://dependabot.com/.
# exact-versions = false

有关更多选项，包括如何排除输出中的 crate，请参阅 config 模块。

稳定性保证

cargo-hakari 遵循语义版本控制，其中公共 API 是命令行界面。

在给定系列中，命令行界面将被视为可追加的。

除非添加了新的配置选项，否则生成的 Cargo.toml 将保持不变，或者

• 涉及错误修复。
• 涉及错误修复。

贡献

有关如何帮助的详细信息，请参阅 CONTRIBUTING 文件。

许可

本项目可在 Apache 2.0 许可证 或 MIT 许可证 的条款下使用。