入门 The Cargo Team 2026-09-13 15:48:22 · 0 阅读

第45章 cargo rustc 命令详解

名称

cargo rustc — 编译当前包，并向编译器传递额外选项

概要

cargo rustc [选项] [-- 参数]

描述

当前包（或通过 -p 指定的包）指定的目标及其所有依赖项将被编译。指定的参数将全部传递给最终的编译器调用，而不会传递给任何依赖项。请注意，编译器仍会无条件接收诸如 -L、--extern 和 --crate-type 等参数，指定的参数只是简单添加到编译器调用中。

有关 rustc 标志的文档，请参见 https://doc.rust-lang.org/rustc/index.html。

当提供额外参数时，此命令要求仅编译一个目标。如果当前包有多个可用目标，则必须使用 --lib、--bin 等过滤器来选择要编译的目标。

若要向 Cargo 生成的所有编译器进程传递标志，请使用 RUSTFLAGS 环境变量或 build.rustflags 配置项。

选项

包选择

默认情况下，选择当前工作目录中的包。-p 标志可用于选择工作区中的其他包。

-p spec
--package spec: 要构建的包。有关 SPEC 格式，请参见 cargo-pkgid(1)。

目标选择

当未给出目标选择选项时，cargo rustc 将构建所选包的所有二进制和目标库目标。

如果选中了集成测试或基准测试进行构建，那么对应的二进制目标会被自动构建。这使得集成测试能够执行该二进制文件，从而验证和测试其功能。在集成测试的构建和运行过程中，会设置 CARGO_BIN_EXE_<name> 环境变量，以便测试代码通过 env 宏或 var 函数定位可执行文件。

传入目标选择标志时，只会构建指定的目标。

注意，--bin、--example、--test 和 --bench 标志也支持常见的 Unix glob 模式（如 *、? 和 []）。不过，为了防止 Shell 在 Cargo 处理之前意外展开 glob 模式，必须用单引号或双引号包裹每个 glob 模式。

--lib: 构建包的库目标。
--bin name…: 构建指定的二进制目标。该标志可多次指定，并支持常见的 Unix glob 模式。
--bins: 构建所有二进制目标。
--example name…: 构建指定的示例目标。该标志可多次指定，并支持常见的 Unix glob 模式。
--examples: 构建所有示例目标。
--test name…: 构建指定的集成测试。此参数可以指定多次，并支持常见的 Unix glob 模式。
--tests: 构建所有设置了 test = true manifest 标志的 target。默认包括作为 unittest 构建的库和二进制文件，以及集成测试。注意这也会构建所需的依赖，因此 lib target 可能会被构建两次（一次作为 unittest，一次作为二进制文件、集成测试等的依赖）。可以通过在 manifest 中设置 target 的 test 标志来启用或禁用相应 target。
--bench name…: 构建指定的基准测试。此参数可以指定多次，并支持常见的 Unix glob 模式。
--benches: 构建所有设置了 bench = true manifest 标志的 target。默认包括作为基准测试构建的库和二进制文件，以及 bench target。注意这也会构建所需的依赖，因此 lib target 可能会被构建两次（一次作为基准测试，一次作为二进制文件、基准测试等的依赖）。可以通过在 manifest 中设置 target 的 bench 标志来启用或禁用相应 target。
--all-targets: 构建所有 target，等价于指定 --lib --bins --tests --benches --examples。

Feature 选择

特性标志允许你控制启用哪些特性。在未指定任何特性选项时，会为每个选定的包激活 default 特性。

更多详情见特性文档。

-F features
--features features: 需激活的特性列表，以空格或逗号分隔。工作区成员的特性可通过 package-name/feature-name 语法启用。该标志可多次指定，以启用所有指定的特性。
--all-features: 激活所有选定包的全部可用特性。
--no-default-features: 不激活选定包的 default 特性。

编译选项

--target triple

为指定的目标架构构建。该标志可多次指定。默认值为主机架构。三元组的一般格式为 <arch><sub>-<vendor>-<sys>-<abi>。

可能的取值包括：

rustc --print target-list 中列出的任意受支持目标。
"host-tuple"，其内部会被替换为主机的目标架构。在交叉编译某些 crate 且不希望将本机指定为目标时（例如，在一个可能被多种主机共同使用的共享项目中的 xtask），此选项特别有用。
自定义目标规范的路径。请参阅自定义目标查找路径获取更多信息。

也可以通过 build.target 的配置值来指定。

指定此标志会使 Cargo 进入不同的运行模式，目标产物会被放置在独立的目录中。详情请参阅构建缓存文档。

-r

--release

使用 release 配置文件构建优化后的产物。有关通过名称选择特定配置文件的选项，请参见 --profile 参数。

--profile 名称

使用给定的配置文件进行构建。

rustc 子命令会对以下命名配置文件应用特殊行为：

check — 使用 dev 配置文件，以与 cargo-check(1) 命令相同的方式进行构建。
test — 以与 cargo-test(1) 命令相同的方式构建，启用测试模式，从而激活测试并启用 test 配置选项。更多详情参见 rustc 测试。
bench — 以与 cargo-bench(1) 命令相同的方式构建，类似于 test 配置文件。

有关配置文件的更多详情，请参见参考文档。

--timings

输出每次编译的耗时信息，并跟踪随时间变化的并发信息。

构建结束后会在 target/cargo-timings 目录下生成一个 cargo-timing.html 文件。如果你还想查看之前某次构建的情况，目录中还会额外保存一份文件名带时间戳的报告。这些报告仅供人阅读，不提供机器可读的计时数据。

--crate-type crate-type

按指定的 crate 类型构建。该参数接受一个或多个以逗号分隔的 crate 类型，可选值与 manifest 中配置 Cargo target 的 crate-type 字段相同。可选值参见 crate-type 字段。

如果 manifest 中已定义了列表，同时又提供了 --crate-type，则命令行参数会覆盖 manifest 中的设置。

该参数仅在构建 lib 或 example 库 target 时有效。

输出选项

--target-dir directory: 存放所有生成产物和中间文件的目录。也可以通过 CARGO_TARGET_DIR 环境变量或 build.target-dir 配置项来指定。默认为 workspace 根目录下的 target。

显示选项

-v

--verbose

输出详细信息。指定两次可获得“非常详细”的输出，包括依赖警告和构建脚本输出等额外内容。也可以通过 term.verbose 配置项设置。

-q

--quiet

不输出 cargo 日志。也可通过 term.quiet 配置项指定。

--color when

控制何时使用彩色输出。有效值：

auto（默认）：自动检测终端是否支持颜色。
always：始终显示彩色。
never：从不显示彩色。

也可通过 term.color 配置项指定。

--message-format fmt

诊断消息的输出格式。可指定多次，值以逗号分隔。有效值：

human（默认）：以人类可读的文本格式显示。与 short 和 json 冲突。
short：输出更简短的人类可读文本消息。与 human 和 json 冲突。
json：将 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 不要将 rustc 诊断信息包含在打印的 JSON 消息中，而是由 Cargo 本身渲染来自 rustc 的 JSON 诊断。Cargo 自身的 JSON 诊断和来自 rustc 的其他诊断仍会输出。不能与 human 或 short 一起使用。

Manifest Options

--manifest-path path

Cargo.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 文档。

--config KEY=VALUE 或 PATH

覆盖 Cargo 的配置值。参数需为 KEY=VALUE 形式的 TOML 语法，或提供一个额外配置文件的路径。此标志可多次指定。详见命令行覆盖一节。

-C PATH

在执行任何操作之前先切换当前工作目录。这会影响 cargo 默认查找项目清单（Cargo.toml）的位置，以及搜索 .cargo/config.toml 的目录等。该选项必须放在命令名之前，例如 cargo -C path/to/my-project build。

此选项仅在 nightly 渠道上可用，且需要启用 -Z unstable-options 标志（参见 #10098）。

-h

--help

显示帮助信息。

-Z flag

Cargo 的不稳定（仅限 nightly）标志。运行 cargo -Z help 查看详细信息。

其他选项

-j N

--jobs N

并行作业的数量。也可通过 build.jobs 配置项指定。默认值为逻辑 CPU 数量。如果为负数，则将最大并行作业数设为逻辑 CPU 数量加上该数值。如果提供字符串 default，则恢复默认值。不应为 0。

--keep-going

尽可能构建依赖图中的多个 crate，而不是在第一个构建失败时中止构建。

例如，如果当前包依赖于 fails 和 works 两个依赖项，其中一个构建失败，cargo rustc -j1 可能无法构建成功的那个（取决于 Cargo 先选择运行这两个中的哪一个），而 cargo rustc -j1 --keep-going 肯定会运行这两个构建，即使先执行的那个失败了。

--future-incompat-report

显示在执行此命令期间产生的任何未来不兼容警告的兼容性报告。

参见 cargo-report(1)

环境变量

关于 Cargo 读取的环境变量详情，请参见参考文档。

退出状态

0：Cargo 执行成功。
101：Cargo 执行失败。

示例

检查当前包（不包含依赖项）是否使用了 unsafe 代码：
```
cargo rustc --lib -- -D unsafe-code
```
在 nightly 编译器上尝试实验性标志，例如以下命令会打印每种类型的大小：
```
cargo rustc --lib -- -Z print-type-sizes
```
通过命令行选项覆盖 Cargo.toml 中的 crate-type 字段：
```
cargo rustc --lib --crate-type lib,cdylib
```