11-cargo run
5 分钟阅读
译文 · 基于 The Cargo Book
cargo-run(1)
原文链接: https://doc.rust-lang.org/cargo/commands/cargo-run.html
名称
cargo-run — 运行当前包
大纲
cargo run [options] [-- args]
描述
运行本地包的二进制目标或示例。
两个短划线（--）之后的所有参数都会传给要运行的二进制程序。若同时向 Cargo 与二进制程序传参，则 -- 之后的参数传给二进制，之前的传给 Cargo。
与 cargo-test(1) 和 cargo-bench(1) 不同，cargo run 将所执行二进制的工作目录设为当前工作目录，就如同直接在 shell 中执行一样。
选项
包选择
默认选择当前工作目录中的包。可用 -p 标志选择工作空间中的其他包。
-pspec--packagespec要运行的包。 SPEC 格式见 cargo-pkgid(1)。
目标选择
若未给出目标选择选项，cargo run 将运行二进制目标。若有多个二进制目标，必须传入目标标志以选择其一。或者，可在 Cargo.toml 的 [package] 节中指定 default-run 字段，以选择默认运行的二进制名称。
--binname运行指定的二进制目标。
--examplename运行指定的示例。
特性选择
特性标志用于控制启用哪些特性（feature）。若未给出特性选项，则为每个所选包激活 default 特性。
参见特性文档 了解更多详情。
-Ffeatures--featuresfeatures要激活的特性列表，以空格或逗号分隔。工作空间成员的特性可用
package-name/feature-name语法启用。此标志可指定多次，将启用所有指定的特性。--all-features激活所有所选包的全部可用特性。
--no-default-features不激活所选包的
default特性。
编译选项
--targettripleRun for the specified target architecture. The default is the host architecture. triple 的一般格式为
<arch><sub>-<vendor>-<sys>-<abi>。可能的值：
rustc --print target-list中任何受支持的目标。"host-tuple"，内部会替换为主机目标。若你在交叉编译某些 crate，又不想把主机机器指定为目标（例如可能由多台主机协作的共享项目中的xtask），这会特别有用。- 自定义目标规范的路径。更多信息见 自定义目标查找路径。
也可通过
build.target配置值 指定。注意：指定此标志会使 Cargo 以不同模式运行，目标产物会放在单独目录中。详情见 构建缓存文档。
-r--release使用
release配置文件运行优化后的产物。 也可使用--profile选项按名称选择特定配置文件。--profilename使用给定的配置文件运行。 关于配置文件的更多详情见参考文档。
--timings输出每次编译耗时信息，并跟踪一段时间内的并发信息。
构建结束时会将
cargo-timing.html文件写入target/cargo-timings目录。还会写入一份文件名带时间戳的额外报告，便于查看先前运行。 这些报告仅供人阅读，不提供机器可读的耗时数据。
输出选项
--target-dirdirectory所有生成产物与中间文件的目录。也可通过
CARGO_TARGET_DIR环境变量或build.target-dir配置值 指定。 默认为工作空间根目录下的target。
显示选项
-v--verbose使用详细输出。可指定两次以获得「非常详细」的输出，其中包括依赖警告与构建脚本输出等额外信息。 也可通过
term.verbose配置值 指定。-q--quiet不打印 cargo 日志消息。 也可通过
term.quiet配置值 指定。--colorwhen控制何时使用彩色输出。有效值：
auto（默认）： 自动检测终端是否支持颜色。always: 始终显示颜色。never: 从不显示颜色。
也可通过
term.color配置值 指定。--message-formatfmt诊断消息的输出格式。可指定多次，由逗号分隔的值组成。有效值：
human（默认）： 以人类可读的文本格式显示。与short和json冲突。short: 发出更短的人类可读文本消息。与human和json冲突。json: 向 stdout 发出 JSON 消息。详情见 参考文档。 与human和short冲突。json-diagnostic-short: 确保 JSON 消息的rendered字段包含 rustc 的「short」渲染。不能与human或short一起使用。json-diagnostic-rendered-ansi: 确保 JSON 消息的rendered字段包含嵌入的 ANSI 颜色代码，以遵循 rustc 的默认配色方案。不能与human或short一起使用。json-render-diagnostics: 指示 Cargo 不要在打印的 JSON 消息中包含 rustc 诊断，而是由 Cargo 自身渲染来自 rustc 的 JSON 诊断。Cargo 自己的 JSON 诊断以及来自 rustc 的其他内容仍会发出。不能与human或short一起使用。
Manifest 选项
--manifest-pathpathCargo.toml文件的路径。默认情况下，Cargo 会在当前目录或其任意父目录中搜索Cargo.toml。--ignore-rust-version忽略包中的
rust-version规范。--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查看详情。
杂项选项
-jN--jobsN并行作业数。也可通过
build.jobs配置值 指定。默认为 逻辑 CPU 数量。若为负数，则将并行作业上限设为逻辑 CPU 数加上所给值。若 提供字符串default，则恢复为默认值。 不应为 0。--keep-going尽可能构建依赖图中的更多 crate，而不是在第一个构建失败时中止。
例如，若当前包依赖
fails与works， 其中之一构建失败，则cargo run -j1可能构建也可能不构建成功的那个 （取决于 Cargo 先运行哪一个），而cargo run -j1 --keep-going肯定会运行两者， 即便先运行的那个失败。
环境变量
参见参考文档 了解 Cargo 读取的环境变量详情。
退出状态
0: Cargo 成功完成。101: Cargo 未能完成。
示例
构建本地包并运行其主目标（假设只有一个二进制）：
cargo run运行带额外参数的示例：
cargo run --example exname -- --exoption exarg1 exarg2