01-cargo
4 分钟阅读
译文 · 基于 The Cargo Book
cargo(1)
名称
cargo — Rust 包管理器
大纲
cargo [options] command [args]cargo [options] --versioncargo [options] --listcargo [options] --helpcargo [options] --explain code
描述
本程序是 Rust 语言的包管理器与构建工具，可在 https://rust-lang.org 获取。
command 可以是以下之一：
- 内置命令，见下文
- 别名（aliases）
- 外部工具
命令
构建命令
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)
执行包的单元测试与集成测试。
Manifest 命令
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)
按本地锁文件记录更新依赖。
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)
将注册表的 API token 保存到本地。
cargo-logout(1)
从本地移除注册表的 API token。
cargo-owner(1)
管理注册表上 crate 的所有者。
cargo-package(1)
将本地包组装为可分发的 tarball。
cargo-publish(1)
将包上传到注册表。
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配置值 指定。
Manifest 选项
--locked断言使用与生成现有
Cargo.lock文件时完全相同的依赖与版本。出现以下任一情况时，Cargo 将以错误退出：- 缺少锁文件。
- 由于依赖解析不同，Cargo 试图更改锁文件。
可用于需要确定性构建的环境，例如 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 or PATH覆盖 Cargo 配置值。参数应为 TOML 语法的
KEY=VALUE，或指向额外配置文件的路径。此标志可指定多次。 更多信息见 命令行覆盖一节。-CPATH在执行任何指定操作之前更改当前工作目录。这会影响诸如 Cargo 默认查找项目清单（
Cargo.toml）的位置，以及用于发现.cargo/config.toml的目录搜索等。此选项必须出现在命令名之前，例如cargo -C path/to/my-project build。此选项仅在 nightly 通道 可用， 并需要
-Z unstable-options标志才能启用（见 #10098）。-h--help打印帮助信息。
-ZflagCargo 的不稳定（仅 nightly）标志。运行
cargo -Z help查看详情。
环境变量
参见参考文档了解 Cargo 读取的环境变量详情。
退出状态
0：Cargo 成功完成。101：Cargo 未能完成。
文件
~/.cargo/
Cargo「主目录」的默认位置，用于存储各类文件。可通过 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
用于登录注册表的私有认证信息。
$CARGO_HOME/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。