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。任务可以执行《xtask》二进制文件（建议使用《CARGO》环境变量以获取正确的《cargo》命令）。

《xtask》crate可能是也可能是主工作空间的一部分。通常情况下，但并非总是如此，工作空间的设置更好。如果《xtask》是工作空间的一部分，你可以在《xtask》和主crate之间共享依赖项，并且依赖项更新过程更简单。此外，你还可以使用《xtask = "run --package xtask --"》作为别名，这不受Cargo工作目录的限制。如果《xtask》不是工作空间的一部分，你可以为共享依赖项使用不同的功能集，并且你可以在CI上更容易地缓存《xtask/target》。建议将《xtask》lockfile提交到仓库。

建议尽量减少xtasks的编译时间。

你可以在本仓库的《a href="https://github.com/matklad/cargo-xtask/blob/master/examples" rel="ugc noopener">./examples

目前的建议是将各种任务定义为单个《xtask》二进制文件的子命令。另一种方法是使用单独的二进制文件和单独的《.cargo/config.toml》条目。

外部示例

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

还有更多示例可以通过例如Github代码搜索找到。

局限性

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，这将构建一个应用程序的发行版（编译的二进制文件 + 手册页 + shell补全 + 其他辅助资源），那么下游的Linux发行版可以使用统一的方式打包Rust应用程序。

据我所知，到目前为止还没有出现这样的常规xtasks。如果您认为将一些重复的模式编码化是一个好主意，请考虑发布您自己的规范（例如，创建 cargo-xtask-dist 仓库）。如果它得到了认可（至少由三位不同作者的不同项目使用），请向本文档发送一个包含规范链接的PR。

有关讨论，请参阅 #1。

工具

库

• devx：一组有用的实用工具（启动进程、git预提交钩子等）
• xshell：在Rust中进行人体工程学的“bash”脚本编写
• duct：一个用于运行子进程的库，支持管道和IO重定向

如果您为xtasks编写工具或库，请向本文档发送PR。一些可能的想法

• 生成 xtask 模板的cargo子命令
• 作为库实现常见xtasks，如“检查代码是否使用rustfmt格式化”或“为clap应用程序构建补全”

背景

据我所知，xtasks的想法最初是在 这篇文章 中提出的。在某种程度上，本文档只是对原始想法的一些规范。

选择 xtask 这个名字是为了不与潜在的未来内置cargo功能冲突。