cargo-package(1)

名称

cargo-package - 将本地的 package 打包为可分发的 tarball (tar 打包的压缩文件)

概要

cargo package [options]

描述

这个命令会创建一个可分发的，以 .crate 为后缀的压缩文件，其中包含当前目录下的 package 的源代码。该压缩文件会保存在 target/package 文件夹中。该命令具体会执行以下几步:

加载并检查当前的工作空间，执行一些基础的检查。
- 不允许 Path dependencies，除非其设置了 version 字段。Cargo 会忽略那些已发布的包的依赖的 path 字段。dev-dependencies e没有此限制。
创建一个 .crate 压缩文件。
- 原有的 Cargo.toml 被重写并格式化。
- [patch], [replace], 和 [workspace] 部分会从清单文件中移除
- 如果包中包含二进制或 example target，Cargo.lock 会被打包进文件。在指定 --locked 的情况下，cargo-install(1) 会使用该 lockfile。
- 一个 .cargo_vcs_info.json 文件会被打包进去，其中包含了当前 VCS (Version Control System，如 git) 的checkout hash ( 没有使用 --allow-dirty 的情况下)。
解压该 .crate 文件并构建，以确认其可以正常构建。
- 这会从头重新构建你的包来保证其能从原始状态成功构建。 --no-verify 标志可以跳过这个步骤。
检查确认构建脚本没有修改任何源文件。

可以在清单文件的 include 和 exclude 字段中控制压缩包要包含的文件。

从 the reference 获取更多关于打包和发布的知识。

.cargo_vcs_info.json 的格式

.cargo_vcs_info.json 的格式为:

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

对于在版本控制仓库的子文件夹下的包，path_in_vcs 会被设置为以仓库为根的相对路径。

选项

Package 选项

-l
--list: 打印包中的所有文件，不创建任何新文件。
--no-verify: 不通过构建来检验压缩包中的内容
--no-metadata: 忽略因缺少人类可读的元数据(如 description 或 license)而产生的警告信息。
--allow-dirty: 允许工作目录中有未提交的 VCS 修改。

包的选择

默认情况下，如果没有提供选择包的选项，那么会按照选择的配置清单文件来选择包(当没有指定 --manifest-path 时，按照当前工目录来查找配置清单文件)。如果工作空间根目录的配置清单文件，则会选择该工作空间的默认成员，否则仅选取配置清单文件所在的那个包。

可以通过 workspace.default-members 来显式设置一个工作空间的默认成员。如果没有设置，在虚拟工作空间下会选择所有的成员，在非虚拟工作空间下仅会选择根 package 。

-p spec...
--package spec...: 仅打包指定的 package。见 cargo-pkgid(1) 中关于 SPEC 格式的描述。此标志可以指定多次，而且支持 common Unix glob patterns ，如 *， ? 和 []。但是，为避免你的 shell 误在 Cargo 之前扩展这些 glob pattern，必须用单引号或双引号将每个 pattern 括起来。
--workspace: 打包工作空间中的所有成员。
--exclude SPEC...: 排除指定的包。必须与 --workspace 标志一起使用。此标志可以指定多次，而且支持 common Unix glob patterns ，如 *， ? 和 []。但是，为避免你的 shell 误在 Cargo 之前扩展这些 glob pattern，必须用单引号或双引号将每个 pattern 括起来。

编译选项

--target triple

为指定的架构而打包，默认为宿主架构。triple 的格式为 <arch><sub>-<vendor>-<sys>-<abi>。执行 rustc --print target-list 可以展示支持的 target 的列表。该标志可以指定多次。

也可以通过 build.target 配置。

注意，指定这个标志会使Cargo在不同的模式下运行，目标制品放在单独目录。参见构建缓存文档了解详情。

--target-dir directory

存放构建产物和中间文件的文件夹。也可以用 CARGO_TARGET_DIR 环境变量来设置，或者 build.target-dir 设置选项。默认会放在工作空间的 target 下。

选择 feature

特性标志允许你控制开启哪些特性。当没有提供特性选项时，会为每个选择的包启用 default 特性。

查看 the features documentation 获取更多信息。

-F features
--features features: 用空格或逗号来分隔多个启用的 feature。工作空间成员的 feature 可以通过 package-name/feature-name 语法来启用。该标志可以设置多次，最终将启用指定的所有 feature 。
--all-features: 启用指定包的所有可用 feature。
--no-default-features: 不使用指定包的 default feature 。

清单选项

--manifest-path path

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

--frozen

--locked

这两个 flag 都需要 Cargo.lock 文件处于无需更新的状态。如果 lock 文件缺失，或者需要被更新，Cargo 会报错退出。 --frozen flag 还会阻止 Cargo 访问网络来判断 Cargo.lock 是否过期。

这些 flag 可以用于某些场景下你想断言 Cargo.lock 无需更新 (比如在CI中构建) 或者避免网络访问。

--offline

阻止 Cargo 访问网络。如果没有这个 flag，当 Cargo 需要访问网络但是没有网络时，就会报错退出。加上这个 flag，Cargo 会尝试在不联网的情况下继续执行 (如果可以的话) 。

要小心这会导致与在线模式不同的解析结果。Cargo 会限制自己在本地已下载的 crate 中查找版本，即使在本地的 index 拷贝中表明还有更新的版本。 cargo-fetch(1) 命令可以在进入离线模式前下载依赖。

同样的功能也可以通过设置 net.offline 配置选项来实现。

杂项

-j N
--jobs N: 并行执行的任务数。可以通过 build.jobs 配置选项来指定。默认值为逻辑CPU数。如果设置为负值，则最大的并行任务数为*逻辑CPU数*加*这个负数*。该值不能为0。
--keep-going: 依赖图中的 crate 能构建多少就构建多少，而不是一个失败就停止。功能还不稳定，需要 -Zunstable-options。

显示选项

-v

--verbose

进行 verbose 输出。可以指定两遍来开启 "very verbose" 模式，输出更多的额外信息，像是依赖项的警告和构建脚本的输出信息。也可以通过 term.verbose 配置选项来指定。

-q

--quiet

不打印 cargo log 信息。也可以通过 term.quiet 配置选项来指定。

--color when

控制*何时*使用彩色输出。可选值有:

auto (默认值): 自动检测终端是否支持彩色输出。
always: 总是显示彩色。
never: 从不显示彩色。

也可以在 term.color 配置选项中设置。

通用选项

+toolchain: 如果 Cargo 由 rustup 安装，那么 cargo 后第一个以 + 开头的参数会被认为是 rustup toolchain 名字(例如 +stable 或 +nightly)。查看 rustup documentation 了解 toolchain overrides 如何工作。
--config KEY=VALUE or PATH: 覆盖一个 Cargo 配置的值。参数应该是一个 TOML 语法的 KEY=VALUE，或者提供一个路径来指向一个额外的配置文件 (configuration file)。这个标记可以指定多次。参考 command-line overrides 一节获取更多信息。
-h
--help: 打印帮助信息。
-Z flag: 不稳定 (nightly-only) 的标志。执行 cargo -Z help 获取详细信息。

环境

查看 the reference 获取 Cargo 读取的环境变量的更多信息。

退出状态

0: Cargo 执行成功。
101: Cargo 没有执行完成。

使用案例

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

其他参考

cargo(1), cargo-publish(1)

The Cargo Book