cargo-package(1)

名称

cargo-package — 将本地包组装成可分发的 tar 包

概要

cargo package [选项]

描述

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

加载并检查当前工作空间，执行一些基本检查。
- 除非路径依赖项具有版本键，否则不允许使用它们。Cargo 将忽略已发布包中依赖项的路径键。dev-dependencies 没有此限制。
创建压缩的 .crate 文件。
- 原始 Cargo.toml 文件将被重写和规范化。
- 清单文件中将删除 [patch]、[replace] 和 [workspace] 部分。
- 如果包包含可执行二进制文件或示例目标，则会自动包含 Cargo.lock。如果使用了 --locked 标志，则 cargo-install(1) 将使用打包的锁文件。
- 包含一个 .cargo_vcs_info.json 文件，其中包含有关当前 VCS 签出哈希的信息（如果可用）（不包含在 --allow-dirty 中）。
解压缩 .crate 文件并构建它以验证它是否可以构建。
- 这将从头开始重建您的包，以确保它可以从原始状态构建。可以使用 --no-verify 标志跳过此步骤。
检查构建脚本是否未修改任何源文件。

可以使用清单文件中的 include 和 exclude 字段控制包含的文件列表。

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

.cargo_vcs_info.json 格式

将生成以下格式的 .cargo_vcs_info.json

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

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

选项

打包选项

-l
--list: 打印包中包含的文件，而不创建包。
--no-verify: 不通过构建内容来验证内容。
--no-metadata: 忽略有关缺少人类可读元数据（例如描述或许可证）的警告。
--allow-dirty: 允许打包具有未提交 VCS 更改的工作目录。

包选择

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

可以使用根清单文件中的 workspace.default-members 键显式设置工作空间的默认成员。如果未设置，则虚拟工作空间将包含所有工作空间成员（相当于传递 --workspace），而非虚拟工作空间将仅包含根 crate 本身。

-p 规范…
--package 规范…: 仅打包指定的包。有关规范格式，请参阅 cargo-pkgid(1)。此标志可以指定多次，并支持常见的 Unix 通配符模式，例如 *、? 和 []。但是，为了避免您的 shell 在 Cargo 处理之前意外扩展通配符模式，您必须在每个模式周围使用单引号或双引号。
--workspace: 打包工作空间中的所有成员。
--exclude 规范…: 排除指定的包。必须与 --workspace 标志一起使用。此标志可以指定多次，并支持常见的 Unix 通配符模式，例如 *、? 和 []。但是，为了避免您的 shell 在 Cargo 处理之前意外扩展通配符模式，您必须在每个模式周围使用单引号或双引号。

编译选项

--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 功能: 要激活的功能的空格或逗号分隔列表。可以使用 package-name/feature-name 语法启用工作空间成员的功能。此标志可以指定多次，这将启用所有指定的功能。
--all-features: 激活所有选定包的所有可用功能。
--no-default-features: 不要激活所选包的 default 功能。

清单选项

--manifest-path 路径

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

--locked

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

缺少锁定文件。
由于不同的依赖项解析，Cargo 尝试更改锁定文件。

它可以用于需要确定性构建的环境中，例如在 CI 管道中。

--offline

阻止 Cargo 出于任何原因访问网络。如果没有此标志，Cargo 在需要访问网络而网络不可用时将停止并报错。使用此标志，Cargo 将尝试在可能的情况下在没有网络的情况下继续进行。

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

也可以使用 net.offline 配置值指定。

--frozen

等效于同时指定 --locked 和 --offline。

其他选项

-j N

--jobs N

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

--keep-going

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

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