第31章 Cargo（Rust包管理器）
名称
cargo — Rust 的包管理器
概要
cargo [选项] 命令 [参数]cargo [选项] --versioncargo [选项] --listcargo [选项] --helpcargo [选项] --explain 代码
描述
这个程序是 Rust 语言的包管理和构建工具，Rust 可在 https://rust-lang.org 获取。
命令可以是以下几种：
命令
构建命令
cargo-bench(1)
执行包的基准测试。
cargo-build(1)
编译包。
cargo-check(1)
检查本地包及其所有依赖是否有错误。
cargo-clean(1)
删除 Cargo 之前生成的构建产物。
cargo-doc(1)
构建包的文档。
cargo-fetch(1)
从网络获取包的依赖。
cargo-fix(1)
自动修复 rustc 报告的 lint 警告。
cargo-run(1)
运行本地包的二进制文件或示例。
cargo-rustc(1)
编译包，并向编译器传递额外选项。
cargo-rustdoc(1)
使用指定的自定义参数构建包的文档。
cargo-test(1)
执行包的单元测试和集成测试。
清单命令
cargo-add(1)
向 Cargo.toml 清单文件添加依赖。
cargo-generate-lockfile(1)
为项目生成 Cargo.lock。
cargo-info(1)
显示注册表中某个包的信息。默认注册表是 crates.io。
cargo-locate-project(1)
以 JSON 格式输出 Cargo.toml 文件所在位置。
cargo-metadata(1)
以机器可读的格式输出软件包解析后的依赖项。
cargo-pkgid(1)
打印完整的软件包规范信息。
cargo-remove(1)
从 Cargo.toml 清单文件中移除依赖项。
cargo-tree(1)
以树状图形式展示依赖关系。
cargo-update(1)
更新本地 lock 文件中记录的依赖项。
cargo-vendor(1)
将所有依赖项下载到本地。
软件包命令
cargo-init(1)
在现有目录中创建一个新的 Cargo 软件包。
cargo-install(1)
编译并安装 Rust 二进制文件。
cargo-new(1)
创建一个新的 Cargo 软件包。
cargo-search(1)
在 crates.io 中搜索软件包。
cargo-uninstall(1)
卸载 Rust 二进制文件。
发布命令
cargo-login(1)
在本地保存 registry 的 API 令牌。
cargo-logout(1)
从本地移除 registry 的 API 令牌。
cargo-owner(1)
管理 registry 上某个 crate 的所有者。
cargo-package(1)
将本地软件包打包成可分发的 tarball。
cargo-publish(1)
将软件包上传至 registry。
cargo-yank(1)
将已上传的 crate 从索引中移除。
报告命令
cargo-report(1)
生成并显示各类报告。
cargo-report-future-incompatibilities(1)
报告将来无法再编译的 crate。
通用命令
cargo-help(1)
显示有关 Cargo 的帮助信息。
cargo-version(1)
显示版本信息。
选项
特殊选项
-V--version-
打印版本信息后退出。配合
--verbose使用时会输出更多信息。 --list-
列出所有已安装的 Cargo 子命令。配合
--verbose使用时会输出更多信息。 --explaincode-
运行
rustc --explain CODE，打印某个错误代码的详细说明（例如E0004）。
显示选项
-v--verbose-
使用详细输出。指定两次可获得“超详细”输出，其中包含依赖警告和构建脚本输出等额外信息。也可以通过
term.verbose配置项 设置。 -q--quiet-
不打印 cargo 的日志信息。也可以通过
term.quiet配置项 设置。 --colorwhen-
控制何时使用彩色输出。有效取值：
auto（默认）：自动检测终端是否支持彩色输出。always：总是显示颜色。never：从不显示颜色。
也可以通过
term.color配置项 指定。
清单选项
--locked-
断言所用的依赖及其版本与生成现有
Cargo.lock文件时完全一致。出现以下任一情况时，Cargo 将报错退出：- lock 文件缺失。
- 由于依赖解析结果不同，Cargo 试图修改 lock 文件。
该选项适用于需要确定性构建的环境，例如 CI 流水线。
--offline-
禁止 Cargo 以任何理由访问网络。不加此标志时，如果 Cargo 需要访问网络而网络不可用，会直接报错退出；加上此标志后，Cargo 会尽可能在无网络的情况下继续执行。
注意，这可能导致与在线模式不同的依赖解析结果。Cargo 只会使用本地已下载的 crate，即使本地索引副本显示可能有更新的版本。如果想在离线前预先下载依赖，请参见 cargo-fetch(1) 命令。
也可以通过
net.offline配置项 指定。 --frozen-
等价于同时指定
--locked和--offline。
通用选项
+toolchain-
如果 Cargo 是通过 rustup 安装的，且传给
cargo的第一个参数以+开头，该参数会被解析为 rustup 工具链名称（例如+stable或+nightly）。 关于工具链覆盖的工作原理，请参阅 rustup 文档。 --configKEY=VALUE 或 PATH-
覆盖 Cargo 配置项。参数格式应为 TOML 语法的
KEY=VALUE，或提供指向额外配置文件的文件路径。此选项可以指定多次。 详情请参阅命令行覆盖部分。 -CPATH-
在执行指定操作前切换当前工作目录。这将影响项目清单（
Cargo.toml）的默认查找位置，以及.cargo/config.toml等文件的搜索路径。此选项必须位于命令名之前，例如cargo -C path/to/my-project build。此选项仅在nightly 渠道可用， 并需要启用
-Z unstable-options标志（参见 #10098）。 -h--help-
打印帮助信息。
-Zflag-
Cargo 的不稳定（仅限 nightly）标志。运行
cargo -Z help查看详细信息。
环境变量
Cargo 读取的环境变量详见参考文档。
退出状态
0：Cargo 执行成功。101：Cargo 执行失败。
文件
~/.cargo/
Cargo “home” 目录的默认位置，用于存放各类文件。可通过 CARGO_HOME 环境变量修改该位置。
$CARGO_HOME/bin/
cargo-install(1) 安装的二进制文件存放在这里。如果使用
rustup，随 Rust 分发的可执行文件也位于此目录。
$CARGO_HOME/config.toml
全局配置文件。配置文件的更多信息请见参考文档。
.cargo/config.toml
Cargo 会自动在当前目录及所有上级目录中查找名为 .cargo/config.toml 的文件。这些配置文件会与全局配置文件合并。
$CARGO_HOME/credentials.toml
登录 registry 所需的私有认证信息。
$CARGO_HOME/registry/
该目录缓存了 registry 索引及已下载的依赖。
$CARGO_HOME/git/
该目录缓存了 git 依赖的下载内容。
请注意，$CARGO_HOME 目录的内部结构尚不稳定，未来可能会发生变化。
示例
-
构建本地包及其所有依赖：
cargo build -
以优化模式构建包：
cargo build --release -
为交叉编译目标运行测试：
cargo test --target i686-unknown-linux-gnu -
创建一个新的可执行包：
cargo new foobar -
在当前目录创建包：
mkdir foo && cd foo cargo init . -
查看某个命令的选项和用法：
cargo help clean
已知问题
问题反馈请参见 https://github.com/rust-lang/cargo/issues。
