cargo-package(1)

名称

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

用法

cargo package [options]

描述

此命令会在当前目录创建一个可分发的，压缩过的.crate文件并附带其源代码。文件会存储于 target/package目录中。命令的执行可分为以下步骤：

  1. 加载当前的工作空间以进行基本的检查。
    • 如果不指定依赖的版本，就不能使用路径依赖。Cargo会在发布的包中忽略路径值。但 dev-dependencies 没有这一限制。
  2. 创建压缩的.crate文件
    • 原始的 Cargo.toml文件会被重写并规范化。
    • 清单中的 [patch]、[replace]、[workspace]段会被移除。
    • 如果包中有可执行的二进制或示例编译目标，则还会包含Cargo.lock文件。如果指定了 --locked标志参数，cargo-install(1)会使用锁文件。
    • 如果可用，会通过.cargo_vcs_info.json文件保存当前版本控制系统的签出哈希值(Checkout Hash)。 可通过--allow-dirty标志参数指定不生成该文件。
  3. 解压.crate文件并对其进行构建，以验证其确实可以成功构建。
    • 这一步会从头开始构建，以确保可以从原始状态构建。可通过指定--no-verify标志参数来跳过这一步。
  4. 检查构建脚本是否会修改源代码的文件。

包含文件的范围可通过清单中的include和exclude字段来控制。

更多关于打包和发布的细节可参见the reference

.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
允许打包 在版本控制系统中仍有未提交内容 的包。

选择包

默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过--manifest-path给出清单文件路径， 则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 单所定义的那个包。

工作区的默认成员可通过清单中workspace.default-members项来显式指定。如果未指定，则其虚拟 工作区会包含全体工作区成员(等同于传递--workspace标志参数时)，而非虚拟工作区则仅包含根部箱自身。

-p spec...
--package spec...
Package指定包. SPEC的格式参见 cargo-pkgid(1) 。 此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。
--workspace
Package 工作区中的全体成员.
--exclude SPEC...
排除指定包。必须与--workspace标志参数共同使用。 此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。

编译选项

--target triple
为指定架构执行 Package 。默认情况下为本机的架构。三元组的格式为 <arch><sub>-<vendor>-<sys>-<abi>。执行 rustc --print target-list 可得到支持的构建目标列表。

也可通过build.target指定(config value)。

注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 详情参见build cache

--target-dir directory
用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR 或 build.target-dir config value指定。

默认情况下为根工作区中的target目录。

特性选择

可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， 则每个已选择的包都会自动使用default特性。

详见the features documentation。

--features features
传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 此参数可多次给定，以分别启用给定的特性。
--all-features
为给定的包启用全部可用特性
--no-default-features
不启用给定包的default特性

清单选项

--manifest-path path
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
--frozen
--locked
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， 或用于避免联网。

--offline
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 所需依赖的方法，参见 cargo-fetch(1) 。

也可以通过 net.offline config value指定。

混杂选项

-j N
--jobs N
要并行运行的作业数量。也可通过build.jobs config value指定。 默认为CPU数量。

显示选项

-v
--verbose
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 也可通过term.verbose指定。 config value.
-q
--quiet
不输出Cargo的日志信息。也可通过term.quiet指定。 config value.
--color when
控制输出内容的颜色。有效取值如下：

  • auto (默认)：自动检测终端是否支持带颜色的输出。
  • always：总显示带颜色的输出。
  • never：从不显示带颜色的输出。

也可通过term.color指定。 config value.

Common Options

+toolchain
If Cargo has been installed with rustup, and the first argument to cargo begins with +, it will be interpreted as a rustup toolchain name (such as +stable or +nightly). See the rustup documentation for more information about how toolchain overrides work.
-h
--help
Prints help information.
-Z flag
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.

环境

关于Cargo所读取的环境变量，可参见the reference

退出状态

  • 0: Cargo命令执行成功
  • 101: Cargo命令未能完成.

示例

  1. 为当前包创建一个压缩好的.crate文件:

     cargo package

相关

cargo(1), cargo-publish(1)