cargo-package(1)

描述

此命令将创建一个可分发的、压缩的 .crate 文件，其中包含当前目录中包的源代码。生成的文件将存储在 target/package 目录中。此命令执行以下步骤：

加载并检查当前工作区，执行一些基本检查。
- 路径依赖项不允许使用，除非它们包含版本键。Cargo 将忽略已发布包中依赖项的路径键。dev-dependencies 没有此限制。
创建压缩的 .crate 文件。
- 原始的 Cargo.toml 文件被重写并规范化。
- [patch]、[replace] 和 [workspace] 部分将从清单中移除。
- Cargo.lock 文件总是会被包含。如果丢失，除非使用了 --exclude-lockfile 标志，否则将生成一个新的 lock 文件。cargo-install(1) 如果使用了 --locked 标志，将使用打包的 lock 文件。
- 包含一个 .cargo_vcs_info.json 文件，其中包含当前 VCS 检出哈希（如果可用）的信息，以及一个指示工作区是否不干净的标志。
- 符号链接被展平为其目标文件。
- 文件和目录的包含或排除基于 [include] 和 [exclude] 字段中提到的规则。
解压 .crate 文件并构建它，以验证它可以构建。
- 这将从头开始重新构建您的包，以确保它可以从干净的状态构建。可以使用 --no-verify 标志跳过此步骤。
检查构建脚本是否修改了任何源文件。

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

有关打包和发布的更多详细信息，请参阅参考资料。

.cargo_vcs_info.json 格式

将生成一个以下格式的 .cargo_vcs_info.json 文件：

{
 "git": {
   "sha1": "aac20b6e7e543e6dd4118b246c77225e3a3a1302",
   "dirty": true
 },
 "path_in_vcs": ""
}

dirty 指示在构建包时 Git 工作区是否不干净。

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

此文件的兼容性遵循与 cargo-metadata(1) 的 JSON 输出相同的策略进行维护。

请注意，此文件提供了 VCS 信息的尽力快照。但是，包的来源未经验证。无法保证 tar 包中的源代码与 VCS 信息匹配。

选项

打包选项

-l

--list

打印包中包含的文件列表，但不创建包。

--no-verify

不通过构建来验证内容。

--no-metadata

忽略缺少人工可读元数据（如描述或许可证）的警告。

--allow-dirty

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

--exclude-lockfile

打包时不包含 lock 文件。

此标志不适用于一般用途。某些工具可能期望 lock 文件存在（例如 cargo install --locked）。在使用此标志之前，请考虑其他选项。

--index 索引

要使用的注册表索引 URL。

--registry 注册表

要打包到的注册表名称；有关注册表名称配置的更多详细信息，请参阅 cargo publish --help。包不会发布到此注册表，但如果我们要打包多个相互依赖的 crate，则在假设依赖项将发布到此注册表的前提下生成 lock 文件。

--message-format 格式

指定输出消息格式。目前，它仅适用于 --list 并影响文件列表格式。这是不稳定的，需要 -Zunstable-options。有效的输出格式：

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

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

{
  /* The Package ID Spec of the package. */
  "id": "path+file:///home/foo#0.0.0",
  /* Files of this package */
  "files" {
    /* Relative path in the archive file. */
    "Cargo.toml.orig": {
      /* Where the file is from.
         - "generate" for file being generated during packaging
         - "copy" for file being copied from another location.
      */
      "kind": "copy",
      /* For the "copy" kind,
         it is an absolute path to the actual file content.
         For the "generate" kind,
         it is the original file the generated one is based on.
      */
      "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 规格…
--package 规格…: 仅打包指定的包。有关 SPEC 格式，请参阅 cargo-pkgid(1)。此标志可以多次指定，并且支持常见的 Unix glob 模式，例如 *、? 和 []。但是，为了避免您的 shell 在 Cargo 处理之前意外扩展 glob 模式，您必须在每个模式周围使用单引号或双引号。
--workspace: 打包工作区中的所有成员。
--exclude 规格…: 排除指定的包。必须与 --workspace 标志一起使用。此标志可以多次指定，并且支持常见的 Unix glob 模式，例如 *、? 和 []。但是，为了避免您的 shell 在 Cargo 处理之前意外扩展 glob 模式，您必须在每个模式周围使用单引号或双引号。

编译选项

--target 三元组

为给定的架构打包。默认是主机架构。三元组的通用格式是 <arch><sub>-<vendor>-<sys>-<abi>。运行 rustc --print target-list 可查看支持的目标列表。此标志可以多次指定。

此选项也可以通过 build.target 配置值指定。

请注意，指定此标志会使 Cargo 在一种不同模式下运行，目标工件会放在单独的目录中。有关更多详细信息，请参阅构建缓存文档。

--target-dir 目录

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

特性选择

特性标志允许您控制哪些特性被启用。当未指定特性选项时，每个选定的包都会激活 default 特性。

有关更多详细信息，请参阅特性文档。

-F 特性
--features 特性: 空格或逗号分隔的要激活的特性列表。工作区成员的特性可以使用 包名称/特性名称 语法启用。此标志可以多次指定，这将启用所有指定的特性。
--all-features: 激活所有选定包的所有可用特性。
--no-default-features: 不激活所选包的 default 特性。

清单选项

--manifest-path 路径

Cargo.toml 文件的路径。默认情况下，Cargo 在当前目录或任何父目录中搜索 Cargo.toml 文件。

--locked

断言使用的依赖项和版本与生成现有 Cargo.lock 文件时使用的完全相同。在以下任何一种情况发生时，Cargo 将退出并报错：

lock 文件丢失。
由于依赖项解析不同，Cargo 尝试更改 lock 文件。

它可用于需要确定性构建的环境中，例如 CI 流水线。

--offline

阻止 Cargo 以任何理由访问网络。如果缺少此标志，当需要访问网络但网络不可用时，Cargo 将停止并报错。使用此标志时，Cargo 将尝试在可能的情况下不使用网络进行操作。

请注意，这可能导致与在线模式不同的依赖项解析。Cargo 会将自己限制在本地下载的 crate 中，即使本地索引副本中可能指示有更新的版本。有关在离线前下载依赖项的信息，请参阅 cargo-fetch(1) 命令。

此选项也可以通过 net.offline 配置值指定。

--frozen

相当于同时指定 --locked 和 --offline。

--lockfile-path 路径

将 lock 文件路径从默认路径 (<workspace_root>/Cargo.lock) 更改为路径。路径必须以 Cargo.lock 结尾（例如 --lockfile-path /tmp/temporary-lockfile/Cargo.lock）。请注意，提供 --lockfile-path 将忽略默认路径下的现有 lock 文件，而是使用来自路径的 lock 文件，或者如果该路径不存在 lock 文件，则将新的 lock 文件写入提供的路径。此标志可用于在只读目录中运行大多数命令，将 lock 文件写入提供的路径。

此选项仅在 nightly channel 上可用，并需要 -Z unstable-options 标志才能启用（参见 #14421）。

杂项选项

-j N

--jobs N

并行运行的作业数。也可以通过 build.jobs 配置值指定。默认为逻辑 CPU 的数量。如果为负数，则将最大并行作业数设置为逻辑 CPU 数量加上提供的值。如果提供字符串 default，则将值重置为默认值。不应为 0。

--keep-going

尽可能多地构建依赖图中的 crate，而不是在第一个构建失败时中止构建。

例如，如果当前包依赖于依赖项 fails 和 works，其中一个构建失败，则 cargo package -j1 可能会或可能不会构建成功的那个（取决于 Cargo 首先选择运行的两个构建中的哪一个），而 cargo package -j1 --keep-going 则一定会运行这两个构建，即使先运行的那个失败了。

显示选项

-v

--verbose

使用详细输出。可以指定两次以获得“非常详细”的输出，其中包含依赖项警告和构建脚本输出等额外信息。也可以通过 term.verbose 配置值指定。

-q

--quiet

不打印 Cargo 日志消息。也可以通过 term.quiet 配置值指定。

--color 何时

控制何时使用彩色输出。有效值：

auto（默认）：自动检测终端是否支持颜色。
always：总是显示颜色。
never：从不显示颜色。

也可以通过 term.color 配置值指定。

通用选项

+工具链

如果 Cargo 是通过 rustup 安装的，并且 cargo 的第一个参数以 + 开头，它将被解释为 rustup 工具链名称（例如 +stable 或 +nightly）。有关工具链覆盖如何工作的更多信息，请参阅 rustup 文档。

--config 键=值 或路径

覆盖 Cargo 配置值。参数应为 TOML 语法 键=值，或提供额外配置文件的路径。此标志可以多次指定。有关更多信息，请参阅命令行覆盖部分。

-C 路径

在执行任何指定操作之前更改当前工作目录。这会影响 Cargo 默认查找项目清单文件 (Cargo.toml) 的位置，以及搜索发现 .cargo/config.toml 的目录等。此选项必须出现在命令名称之前，例如 cargo -C path/to/my-project build。

此选项仅在 nightly channel 上可用，并需要 -Z unstable-options 标志才能启用（参见 #10098）。

-h

--help

打印帮助信息。

-Z 标志

Cargo 的不稳定（仅限 nightly）标志。运行 cargo -Z help 获取详细信息。

环境变量

有关 Cargo 读取的环境变量的详细信息，请参阅参考资料。

退出状态码

0: Cargo 成功。
101: Cargo 未能完成。

示例

创建当前包的压缩 .crate 文件
```
cargo package
```

参见

cargo(1), cargo-publish(1)

Cargo 手册