cargo-parcel

注意：该项目处于早期阶段。虽然所有记录的功能都已实际实现，但功能集仍然相当有限。它可能仍然足够作为 MVP。

虽然 cargo install 是将 crate 提供的二进制文件安装到系统中的便捷方式，但如果这些 crate 需要安装附加资源，如手册页、图标、声音文件等，则它就不够用了。此外，在 Rust 生态系统似乎没有建立一种约定，允许访问与应用程序一起安装的资源，无论它们安装在哪里。

cargo-parcel 实际上是 xtask 模式 的应用，当我偶然发现它时，产生了 cargo-parcel 的想法。虽然 cargo-xtask 是“向 Rust 项目添加自由形式自动化的一种方式，...”，但 cargo-parcel 是该想法的具体实现，移除了“自由形式”部分，而是专注于应用程序安装和分发，以及定义描述这些的声明性方式。

卖点

• 将附加资源与您的二进制文件一起安装。
• 在安装之前，从 markdown 源渲染 Unix 手册页。
• 允许将安装位置编译到您的二进制文件中，以便它们可以找到与自身一起安装的资源。

一个示例用例

作为一个激励的示例，假设你正在开发一个提供 frobnitz 二进制文件的 crate，该二进制文件播放声音样本，并且你想要将一些声音样本包含在你的程序中。此外，你希望成为 *nix 生态系统的良好公民，并提供详细描述 frobnitz 的手册页。此外，你希望使 Linux 发行版和其他类似努力能够轻松地为它们的各自包系统打包 frobnitz。这意味着在实践中，你希望能够满足以下要求

• 在用户提供的任意位置安装 frobnitz，以及以下文档和其他资源。在 Unix 系统上，默认位置通常是系统范围的 /usr/local，而针对用户的安装通常是 ~/.local。~/.local 目录是 XDG 基础目录规范 中描述的约定。安装目标根目录通常被称为 安装前缀。
• 如果需要，可以将安装前缀编译到 frobnitz 中，这样它就可以在用户未指定其位置的情况下定位已安装的资源，无论选择的安装前缀是什么。
• 应该可以通过指定一个附加路径并将其附加到选择的安装前缀来重新定位安装。此路径仅在安装时相关，必须 不得 编译到或以其他方式引用安装的可执行文件或资源。此路径在 autotools 世界中被称为 DESTDIR。对于需要在不具有 root 权限的情况下运行，并且不能写入最终将安装构建包的位置的发行版打包工具，它特别有用。

它能为您做什么

cargo-parcel 是一个尝试，让二进制crate作者轻松满足上述要求。它还允许将常见的任务（如构建手册页面）集成到安装过程中。此外，它提供了一种创建简单的二进制发行版存档的方法，这对于您想要为用户提供与发行版无关的二进制软件包，或者从源代码部署到不同的系统时非常有用。

您可以通过在 Cargo.toml 文件中添加一些元数据来在自己的 crate 中使用 cargo-parcel，具体是添加 package.metadata.parcel 表，如下所述。由于元数据格式预计会演变，目前没有 cargo-parcel cargo 插件，您必须添加一些额外的样板代码来将您的代码绑定到 cargo-parcel 的特定版本，从而在您的 crate 中定义 cargo parcel 命令。

用法

使用 cargo-parcel 有两个方面；应用程序 crate 作者会想看看如何将其 集成 到他们的 crate 中，而使用 cargo-parcel 的 crate 的用户可能会对 CLI 指南 更感兴趣。cargo-parcel 的行为由 Cargo.toml 中的 package.metadata.parcel 表配置。可用设置在 元数据参考 中描述。

以下提供了一些可用命令及其最重要的选项的简要概述。有关详细信息，请参阅 CLI 指南或内置的命令行界面帮助。

• cargoparcel install[--prefix DIR] [--dest-dir DIR]

  将存档内容安装到指定的 --prefix 目录（默认为 ~/.local），可选地重新定位安装到指定的 --dest-dir 目录。

• cargoparcel uninstall[--prefix DIR] [--dest-dir DIR]

  抵消等效的 install 命令的操作；即卸载包内容。

• cargoparcel bundle[-o FILE] [--prefix DIR] [--root DIR]

  生成发行版 "bundle"；目前通过调用 GNU tar 支持支持 TAR 存档。

相关软件

要了解 cargo-parcel 的目标，将其与通用任务运行器如 cargo-make 进行对比是有帮助的。

• 使用 cargo-make，您可以定义任意任务，而 cargo-parcel 则定义了一些专注于应用程序安装和分发的固定命令。
• cargo-parcel 力求声明性，描述“是什么”，而不是“如何做”。其他工具应能利用 parcel 元数据，而无需运行 cargo-parcel 或部分重新实现它。

有一些 crate 提供与 cargo-parcel 相重叠的功能；经过随意搜索，我找到了以下这些。如果您知道其他类似的，请提交问题，我将它们添加到列表中。

• cargo 扩展 cargo-deb 基于配置的 Cargo.toml 创建二进制 Debian 软件包，并且可以通过 deb 元数据部分进行配置。
• cargo-rpm 与 cargo-deb 不同（当然，除了生成 .rpm 而不是 .deb 软件包外），它不使用 Cargo.toml 作为其元数据。
• debcargo 通过从“原始”crate 源生成 Debian 源软件包，清楚地分离了打包者和上游者的角色。

那么 cargo-parcel 与这些工具有什么关系呢？创建实际的分发软件包超出了 cargo-parcel 的范围，而是它旨在让您描述应用程序 crate 的内容，这样就可以轻松地从源安装，并为分发构建一个简单、与分发无关的二进制软件包。

未来方向

除了有望减少打包“Rust 应用程序”的开销外，cargo-parcel 元数据的可用性也将允许构建其他可能很酷的东西。一个想法是创建一个关注 Rust 应用程序（CLI 和 GUI 都有）的网站，它可以

• 提供手册页内容和其他文档，类似于 docs.rs，但针对最终用户文档，而不是 API 文档。
• 显示由该 crate 安装的文件列表。

思考这一点也引发了我对“cargo 和 crates.io 的范围”的问题。我认为处理平台特有的问题，如手册页的存在，超出了 cargo 的范围。所以如果我们接受 cargo 不会处理这些事情，如渲染和安装手册页，那么是否留下了工具的空缺？cargo-parcel 是填补这一空缺的实验，目前针对其作者的 CLI crate 的需求定制，但也旨在对他人也有用。

如果类似 cargo-parcel 的工具，一个针对 Rust 编写的应用程序的 cargo install 工具受到欢迎，这意味着二进制 crate 将变得（更）普遍，在运行 cargo install 后将不足以（完全）安装它们。在那个假设的未来，甚至可能需要考虑通过不同于 crates.io 的通道提供这样的 crate。

许可证

本crate中的代码和文档是自由软件，根据您的选择，可以双许可协议下使用MIT或Apache-2.0许可证。

templates和examples目录的内容旨在免费复制和修改，用于任何用途，没有任何义务。作者认为这些内容过于简单，不应受版权保护。