Rust构建系统优化工具cargo-hakari的使用，管理复杂工作区依赖和提升Cargo构建效率

Rust构建系统优化工具cargo-hakari的使用，管理复杂工作区依赖和提升Cargo构建效率

cargo hakari 是一个命令行应用程序，用于管理工作区hack crate。使用它可以将本地 cargo build 和 cargo check 命令的速度提高高达 100倍，累积提高高达 1.7倍 或更多。

安装

发布二进制文件

可以通过 cargo binstall 安装：

cargo binstall cargo-hakari

在 GitHub Actions CI 中，使用 taiki-e/install-action：

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

从源码安装

安装或更新 cargo-hakari：

cargo install cargo-hakari --locked

使用

开始使用

有四个步骤是必须执行的，以便 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"

2. 在 CI 中保持工作区hack更新

在 CI 中运行以下命令：

cargo hakari generate --diff  # 检查workspace-hack Cargo.toml是否最新
cargo hakari manage-deps --dry-run  # 检查所有工作区crate是否都依赖于workspace-hack

3. 考虑 patch 指令

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

关于工作区hack的信息

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

为什么依赖项在工作区hack中？

打印有关为什么依赖项存在于工作区hack中的信息：

cargo hakari explain <dependency-name>

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

cargo hakari verify

发布 crate

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

禁用和卸载

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

cargo hakari disable

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

cargo hakari remove-deps

配置

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

示例配置：

# 用于工作区hack统一的包的名称
hakari-package = "workspace-hack"
# 使用的 Cargo 解析器版本 -- 强烈推荐版本 2
resolver = "2"

# 其他 Cargo.toml 中 `workspace-hack = ...` 行的格式
dep-format-version = "4"

# 开发人员常用平台的三元组
platforms = [
    # "x86_64-unknown-linux-gnu",
    # "x86_64-apple-darwin",
    # "x86_64-pc-windows-msvc",
]

# 写出确切的版本而不是规范
# exact-versions = false

稳定性保证

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

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

生成的 Cargo.toml 也将保持不变，除非：

  • 添加了新的配置选项
  • 涉及错误修复

贡献

请参阅 CONTRIBUTING 文件以了解如何提供帮助。

许可证

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

完整示例

以下是一个完整的使用示例，展示如何在工作区中设置和使用 cargo-hakari：

  1. 首先，确保你的 Cargo.lock 文件已提交到版本控制中。

  2. 初始化工作区hack crate：

cargo hakari init workspace-hack
  1. 生成 Cargo.toml 文件：
cargo hakari generate
  1. 将工作区hack crate添加到所有其他工作区crate的依赖中：
cargo hakari manage-deps
  1. 更新 .config/hakari.toml 配置文件：
hakari-package = "workspace-hack"
resolver = "2"
dep-format-version = "4"

platforms = [
    "x86_64-unknown-linux-gnu",
    "x86_64-apple-darwin",
    "x86_64-pc-windows-msvc",
]
  1. 在 CI 中添加检查以确保工作区hack保持最新：
cargo hakari generate --diff
cargo hakari manage-deps --dry-run
  1. 如果需要，可以查看为什么特定依赖项被包含在工作区hack中：
cargo hakari explain serde
  1. 验证工作区hack是否确保每个依赖项仅构建一个功能集：
cargo hakari verify

  1. 如果要发布 crate，请确保遵循 publishing 模块中的指南。

  2. 如果需要临时禁用工作区hack：

cargo hakari disable
  1. 如果要完全移除工作区hack：
cargo hakari remove-deps

1 回复

Rust构建系统优化工具cargo-hakari的使用指南

什么是cargo-hakari

cargo-hakari是一个用于管理复杂Rust工作区依赖关系的工具，它通过优化Cargo构建系统来显著提升大型项目的构建效率。该工具特别适合包含多个crate的工作区(workspace)项目，能够解决依赖版本冲突和重复构建的问题。

主要功能

  1. 自动管理工作区中所有crate的依赖版本
  2. 减少重复构建相同依赖的情况
  3. 解决工作区中不同crate依赖版本冲突问题
  4. 生成优化的Cargo.lock文件

安装方法

cargo install cargo-hakari

基本使用方法

初始化hakari配置

在项目根目录下运行：

cargo hakari init

这将在项目根目录下生成一个hakari.toml配置文件。

生成优化的依赖管理

cargo hakari generate

此命令会分析工作区中的所有依赖关系，并生成优化的解决方案。

应用优化

cargo hakari manage-deps

此命令会实际修改各个crate的Cargo.toml文件，应用hakari的优化方案。

实际示例

假设我们有一个包含多个crate的工作区项目：

my_project/
├── Cargo.toml
├── crate_a/
│   └── Cargo.toml
├── crate_b/
│   └── Cargo.toml
└── crate_c/
    └── Cargo.toml
  1. 首先初始化hakari：
cd my_project
cargo hakari init
  1. 然后生成依赖优化方案：
cargo hakari generate
  1. 应用优化：
cargo hakari manage-deps
  1. 之后可以像往常一样使用cargo构建项目，但会体验到更快的构建速度：
cargo build

高级用法

排除特定crate

在hakari.toml中可以配置排除某些crate不参与优化：

excluded_crates = [
    "some_special_crate",
]

自定义依赖统一策略

[dependencies]
# 强制所有crate使用相同版本的serde
serde = "1.0"

与CI系统集成

可以在CI脚本中添加hakari步骤：

cargo hakari generate
cargo hakari verify  # 验证依赖是否一致
cargo build

完整示例demo

下面是一个完整的使用cargo-hakari的工作区项目示例：

  1. 首先创建工作区结构：
mkdir my_project && cd my_project
cargo new crate_a --lib
cargo new crate_b --lib
cargo new crate_c --lib
  1. 创建工作区根Cargo.toml：
[workspace]
members = [
    "crate_a",
    "crate_b",
    "crate_c"
]
resolver = "2"  # 使用新的特性解析器
  1. 为各个crate添加一些依赖（示例）：
# crate_a/Cargo.toml
[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.0", features = ["full"] }

# crate_b/Cargo.toml
[dependencies]
serde = "1.0"
reqwest = "0.11"

# crate_c/Cargo.toml
[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.0", features = ["rt-multi-thread"] }
  1. 初始化并应用cargo-hakari：
# 安装cargo-hakari
cargo install cargo-hakari

# 初始化配置
cargo hakari init

# 生成优化方案
cargo hakari generate

# 应用优化
cargo hakari manage-deps

# 构建项目
cargo build
  1. 检查hakari.toml配置示例：
# hakari.toml示例配置
[hakari]
# 排除特定crate
excluded_crates = [
    "special_crate"
]

# 自定义依赖版本
[dependencies]
serde = "1.0"
tokio = "1.0"

注意事项

  1. 使用hakari前建议先提交当前代码，因为它会修改Cargo.toml文件
  2. 首次使用可能需要一些时间来分析大型工作区
  3. 某些特殊情况下可能需要手动调整hakari.toml配置

cargo-hakari特别适合大型Rust项目，能够显著减少构建时间并简化依赖管理。对于小型项目，可能带来的收益不如大型项目明显。

回到顶部