04-cargo package

cargo-package(1) 打包分发包

7 分钟阅读

译文 · 基于 The Cargo Book

cargo-package(1)

原文链接: https://doc.rust-lang.org/cargo/commands/cargo-package.html

名称

cargo-package — 将本地包组装为可分发压缩包

大纲

cargo package [options]

描述

此命令会为当前目录中的包创建可分发、压缩的 .crate 文件（含源代码）。生成的文件保存在 target/package 目录中。执行步骤如下：

加载并检查当前工作空间，执行一些基本检查。
- 除非路径依赖带有 version 键，否则不允许使用路径依赖。Cargo 在已发布包中会忽略依赖的 path 键。dev-dependencies 不受此限制。
创建压缩的 .crate 文件。
- 原始 Cargo.toml 文件会被重写并规范化。
- 清单中的 [patch]、[replace] 与 [workspace] 节会被移除。
- 始终包含 Cargo.lock。若缺失，将生成新的锁文件，除非使用了 --exclude-lockfile 标志。若使用 --locked 标志，cargo-install(1) 会使用打包的锁文件。
- 包含 .cargo_vcs_info.json 文件，其中记录当前 VCS 检出哈希（若可用），以及工作树是否 dirty 的标志。
- 符号链接会被展平为其目标文件。
- 根据 [include] 与 [exclude] 字段中的规则包含或排除文件与目录。
解压 .crate 文件并构建，以验证其可以构建。
- 这会从头重新构建你的包，确保可以从干净状态构建。可用 --no-verify 标志跳过此步骤。
检查构建脚本是否修改了任何源文件。

包含的文件列表可通过清单中的 include 与 exclude 字段控制。

关于打包与发布的更多细节，见参考文档。

.cargo_vcs_info.json 格式

将生成如下格式的 .cargo_vcs_info.json：

1
2
3
4
5
6
7
{
 "git": {
   "sha1": "aac20b6e7e543e6dd4118b246c77225e3a3a1302",
   "dirty": true
 },
 "path_in_vcs": ""
}

dirty 表示打包时 Git 工作树处于 dirty 状态。

path_in_vcs 对于版本控制仓库子目录中的包，会设置为相对于仓库的路径。

此文件的兼容性策略与 cargo-metadata(1) 的 JSON 输出相同。

请注意，此文件提供的是 VCS 信息的最佳努力快照。然而，包的来源并未被验证。无法保证压缩包中的源代码与 VCS 信息一致。

选项

打包选项

列出包中将包含的文件，但不实际创建包。

不通过构建来验证内容。

忽略缺少人类可读元数据（如 description 或 license）的警告。

--allow-dirty

允许打包含有未提交 VCS 变更的工作目录。

--exclude-lockfile

打包时不包含锁文件。

此标志并非供一般使用。某些工具可能期望存在锁文件（例如 cargo install --locked）。使用前请考虑其他选项。

--index index

要使用的注册表索引 URL。

--registry registry

要为其打包的注册表名称；注册表名称的配置详见 cargo publish --help。包不会发布到该注册表，但若我们在打包多个相互依赖的 crate，锁文件将在假设依赖将发布到该注册表的前提下生成。

--message-format fmt

指定输出消息格式。目前仅与 --list 配合使用，并影响文件列表格式。此功能不稳定，需要 -Zunstable-options。有效输出格式：

human（默认）：每行一个文件的格式显示。

json：输出关于每个包的机器可读 JSON 信息。每个包一行 JSON（换行分隔的 JSON）。

{
  /* 包的 Package ID Spec。 */
  "id": "path+file:///home/foo#0.0.0",
  /* 此包的文件 */
  "files" {
    /* 归档文件中的相对路径。 */
    "Cargo.toml.orig": {
      /* 文件来源。
         - "generate" 表示打包过程中生成的文件
         - "copy" 表示从其他位置复制的文件
      */
      "kind": "copy",
      /* 对于 "copy" 类型，
         为实际文件内容的绝对路径。
         对于 "generate" 类型，
         为生成文件所基于的原始文件。
      */
      "path": "/home/foo/Cargo.toml"
    },
    "Cargo.toml": {
      "kind": "generate",
      "path": "/home/foo/Cargo.toml"
    },
    "src/main.rs": {
      "kind": "copy",
      "path": "/home/foo/src/main.rs"
    }
  }
}

包选择

默认情况下，若未指定包选择选项，所选包取决于所选清单文件（若未指定 --manifest-path，则基于当前工作目录）。若清单是工作空间的根，则选择工作空间的默认成员；否则仅选择清单定义的包。

工作空间的默认成员可在根清单中通过 workspace.default-members 键显式设置。若未设置，虚拟工作空间将包含所有工作空间成员（等价于传入 --workspace），非虚拟工作空间则仅包含根 crate 本身。

-p spec…
--package spec…: 仅打包指定的包。SPEC 格式见 cargo-pkgid(1)。此标志可指定多次，并支持常见的 Unix glob 模式，如 *、? 和 []。不过，为避免 shell 在 Cargo 处理之前意外展开 glob 模式，必须用单引号或双引号括住每个模式。
--workspace: 打包工作空间中的所有成员。
--exclude SPEC…: 排除指定的包。必须与 --workspace 标志一起使用。此标志可指定多次，并支持常见的 Unix glob 模式，如 *、? 和 []。不过，为避免 shell 在 Cargo 处理之前意外展开 glob 模式，必须用单引号或双引号括住每个模式。

编译选项

--target triple

为指定目标架构打包。此标志可指定多次。默认为宿主架构。三元组的一般格式为 <arch><sub>-<vendor>-<sys>-<abi>。

可能的值：

rustc --print target-list 中支持的任意目标。
"host-tuple"，内部将替换为宿主目标。若你在交叉编译某些 crate，且不想将宿主机器指定为目标（例如多人协作的共享项目中的 xtask），这会特别有用。
自定义目标规范的路径。更多信息见 Custom Target Lookup Path。

也可通过 build.target 配置值指定。

请注意，指定此标志会使 Cargo 以不同模式运行，目标产物将放在单独的目录中。更多细节见构建缓存文档。

--target-dir directory

所有生成产物与中间文件的目录。也可通过 CARGO_TARGET_DIR 环境变量或 build.target-dir 配置值指定。默认为工作空间根目录下的 target。

特性选择

特性标志用于控制启用哪些特性。若未指定特性选项，每个所选包都会激活 default 特性。

参见特性文档了解更多详情。

-F features
--features features: 空格或逗号分隔的要激活的特性列表。工作空间成员的特性可用 package-name/feature-name 语法启用。此标志可指定多次，以启用所有指定的特性。
--all-features: 激活所有所选包的全部可用特性。
--no-default-features: 不激活所选包的 default 特性。