cargo xtask

cargo-xtask 是向 Rust 项目添加自由形式自动化的一种方法，类似于 make，npm run 或定制 bash 脚本。

xtask 的两个显著特点是

• 它不需要除了 cargo 和 rustc 以外的任何其他二进制文件，它完全从它们自举
• 与 bash 不同，它更容易跨平台，因为它不使用 shell。

它是如何工作的？

cargo-xtask 是 cargo workflows 功能的一个 polyfill。它是一种扩展标准、稳定的 cargo 的自定义命令（xtasks）的方法，这些命令是用 Rust 编写的。

这个 polyfill 不需要任何代码，只需要一个 cargo 项目的特定配置。这个仓库是这个配置的规范。

状态

cargo-xtask 不是一个官方推荐的流程，但它是在生态系统中的一个相对常见的模式。值得注意的是，Cargo 本身 使用了 xtasks。

它可能或可能不会适用于您的用例！

定义 xtasks

创建 xtask 的最佳方式是在 Cargo 工作区内部进行。如果您还没有工作区，您可以在您的包内部创建一个，将内容移动到一个新目录中。假设我们的包名为 "testing"。我们首先将所有内容移动到一个子目录中

$ mkdir testing

# then move all of the stuff except your .git directory into the new testing directory:
$ mv src testing
$ mv Cargo.toml testing
$ mv .gitignore testing
$ mv README.md testing

# Don't forget anything else your package may have.

然后，添加一个名为 xtask 的新包

$ cargo new --bin xtask

然后，我们需要为我们的工作区创建一个 Cargo.toml

[workspace]
members = [
    "testing",
    "xtask",
]

如果您之前有一个工作区，您将把 xtask 添加到您现有的工作区 Cargo.toml 中。

然后，别名。 这是魔法发生的地方。创建一个 .cargo

$ mkdir .cargo

并在其中创建一个名为 config.toml 的文件，内容如下

[alias]
xtask = "run --package xtask --"

示例目录结构

/testing
  .git
  .cargo/
    config.toml
  Cargo.toml
  testing/
    Cargo.toml
    .gitignore
    src/
      lib.rs
  xtask/
    Cargo.toml
    src/
      main.rs

xtask 目录和 .cargo/config 都应该提交到版本控制系统。

如果您不想使用工作区，可以使用以下别名：run --manifest-path ./xtask/Cargo.toml --，但这不建议使用。

xtask 二进制文件应至少期望一个位置参数，即要执行的任务名称。任务是用 Rust 实现的，可以使用来自 crates.io 的任意 crate。任务可以执行 cargo（建议使用 CARGO 环境变量以获取正确的 cargo）。

xtask crate 可能是主工作区的一部分，也可能不是。通常情况下，工作区设置更好。如果 xtask 是工作区的一部分，您可以在 xtask 和主 crate 之间共享依赖项，并且依赖项更新过程更简单。此外，您还可以使用 xtask = "run --package xtask --" 作为别名，它在 Cargo 的工作目录无关的情况下也能工作。如果 xtask 不是工作区的一部分，您可以为共享依赖项使用不同的功能集，并且您可以在 CI 上更容易地缓存 xtask/target。建议将 xtask 锁文件提交到存储库。

建议最小化 xtasks 的编译时间。

您可以在本存储库的 ./examples 目录中找到一些 xtasks 的示例。

当前建议是将各种任务定义为单个 xtask 二进制文件的子命令。另一种选择是为每个任务使用单独的二进制文件和 .cargo/config 中的单独条目。

外部示例

• rust-analyzer：发布、性能指标等。
• helix-editor/helix：验证嵌入式查询文件、生成文档。
• containers/bootc：生成 RPM，为 dbg! 创建自定义 lint。
• rust-lang/cargo：如今，甚至 Cargo 本身也使用这种模式！

更多示例可以通过例如 Github Code search 等方式找到。

限制

xtasks 不与 Cargo 生命周期集成。如果您需要在 cargo build 之后进行自定义后处理，则需要定义和调用 cargo xtask build 任务，该任务内部调用 cargo build。无法拦截标准的 cargo build 命令。

无法使用依赖项中的 xtasks，xtasks 是项目本地的。然而，可以将实现常见 xtasks 的逻辑作为 crates.io 软件包共享。

如果 xtask 不是工作空间成员，则 cargo xtask 仅从项目的根目录中工作。

使用 xtasks

使用 cargo xtask task-name 命令来运行任务。

示例

cargo xtask deploy

请注意，这不需要任何额外的设置，除了克隆存储库，它将在第一次运行时自动构建 xtask 二进制文件。

不使用 xtasks

xtasks 完全可选，您不必使用它们！特别是，如果 cargo build 和 cargo test 对您来说足够了，则无需使用 xtasks。如果您更喜欢编写短的 bash 脚本，并且不需要支持 Windows，那么也不需要使用 xtasks。

标准 xtasks

理论上，可能有益于为一些常见任务指定一种约定，以启用高级工具。例如，如果许多 CLI 应用程序可以提供 cargo xtask dist，它构建应用程序的分发版（编译后的二进制文件 + man 页面 + shell 完整性 + 其他任何辅助资源），那么这可以被下游 Linux 发行版以统一的方式重新用于打包 Rust 应用程序。