第44章 cargo run 命令详解
名称
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-
运行指定的示例。
特性选择
特性标志用于控制启用哪些特性。未指定任何特性选项时，所有选定包都会激活 default 特性。
详见特性文档。
-Ffeatures--featuresfeatures-
需启用的特性列表，以空格或逗号分隔。可使用
包名/特性名语法启用工作区成员的特性。此标志可多次指定，从而启用所有指定的特性。 --all-features-
激活所有选定包的全部可用特性。
--no-default-features-
不激活选定包的
default特性。
编译选项
--targettriple-
为指定的目标架构运行。默认为宿主架构。三元组的一般格式为
<arch><sub>-<vendor>-<sys>-<abi>。可能的取值：
rustc --print target-list中列出的任何受支持目标。"host-tuple"，内部会被替换为宿主目标。在交叉编译部分 crate 且不想明确指定宿主机器为目标时特别有用（例如，在一个由多主机共同开发共享项目中的xtask场景）。- 自定义 target 规范文件的路径。详见 Custom Target Lookup Path。
也可以通过
build.target-dir之外的build.target配置项 来指定。注意：指定此选项后，Cargo 会以另一种模式运行，target 产物会放在单独的目录中。详见 build cache 文档。
-r--release-
使用
releaseprofile 运行优化后的产物。 也可以用--profile选项按名称选择特定的 profile。 --profilename-
使用指定的 profile 运行。 关于 profile 的更多细节见 参考文档。
--timings-
输出每次编译的耗时信息，并跟踪并发情况随时间的变化。
构建结束后会在
target/cargo-timings目录下生成一个cargo-timing.html文件。另外还会生成一份文件名带时间戳的报告，方便查看之前某次运行的结果。这些报告仅供人工查看，不提供机器可读的计时数据。
输出选项
--target-dirdirectory-
存放所有生成的产物和中间文件的目录。也可以通过
CARGO_TARGET_DIR环境变量或build.target-dir配置项 指定。默认为 workspace 根目录下的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：将 JSON 消息输出到标准输出。请参阅 参考文档 获取更多详情。与human和short冲突。json-diagnostic-short：确保 JSON 消息中rendered字段包含 rustc 生成的“简短”渲染结果。不能与human或short选项同时使用。json-diagnostic-rendered-ansi：确保 JSON 消息中rendered字段包含嵌入的 ANSI 颜色代码，以遵循 rustc 的默认配色方案。不能与human或short选项同时使用。json-render-diagnostics：指示 Cargo 不要直接输出 rustc 诊断信息，而是由 Cargo 自行渲染来自 rustc 的 JSON 诊断结果。Cargo 自身的 JSON 诊断及其他来源的 JSON 诊断仍会正常输出。不能与human或short选项同时使用。
Manifest Options
--manifest-pathpath-
Cargo.toml文件的路径。默认情况下，Cargo 会在当前目录或其任意父目录中查找该文件。 --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 或 PATH-
覆盖 Cargo 的配置项。参数需采用
KEY=VALUE的 TOML 语法，或者提供一个额外配置文件的路径。此标志可以多次指定。更多信息请参阅命令行覆盖章节。 -CPATH-
在执行指定操作前更改当前工作目录。这会影响 Cargo 默认查找项目清单文件（
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查看详细信息。
杂项选项
-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
