cargo-rustc(1)

定义

cargo-rustc - 编译当前包，并将额外参数传递给编译器

概要

cargo rustc [options] [-- args]

说明

当前包的指定目标(或由 -p 指定的已有的包)将与它的所有依赖一起被编译。 指定的 args 将全部传递给最终的编译器调用，而非依赖项的参数。 请注意，编译器仍然会无条件地接受参数，如 -L ， -extern ，和 -crat-type ， 而指定的的 args 将被添加到编译器的调用中。

有关 rustc 的标志位的文档请查看 https://doc.rust-lang.org/rustc/index.html

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

使用 RUSTFLAGS environment variable 或者 build.rustflags config value 来给 Cargo 创建的所有编译器进程传递标志位。

选项

选择包

当前工作目录下的包是默认选中的。可以使用 -p 选项来选择工作空间中不同的包。

-p spec

--package spec

要构建的包。请在 cargo-pkgid(1) 查看 SPEC 格式

选择构建目标

当没有提供构建目标选择的选项时， cargo rustc 会构建选中包的所有二进制程序和类库目标。

如果要构建集成测试或基准测试，二进制目标也会自动构建。 这允许集成测试执行二进制文件以测试其行为。 集成测试构建时会设置 CARGO_BIN_EXE_<name> [environment variable](.../reference/environment-variables.html#environment-variables-cargo-sets for-crates) ， 以便它可以使用 env macro 来定位可执行程序。

传递目标选中标志可以仅编译指定的目标。

注意 --bin 、 --example 、 --test 和 --bench 标志也 支持常见的 Unix glob pattern，比如 * , ? 和 [] 。 然而，为了避免你的 shell 在 Cargo 处理 glob pattern 之前意外地扩展它们， 你必须在每个 glob pattern 周围使用单引号或双引号。

--lib

构建包的类库

--bin 名称...

构建指定的二进制程序。这个标志位可以多次指定并且支持通用的 Unix glob pattern 格式。

--bins

构建所有二进制目标

--example 名称...

构建指定的例子。这个标志位可以多次指定并且支持通用的 Unix glob pattern 格式。

--examples

构建所有例子目标

--test 名称...

构建指定的集成测试。这个标志位可以多次指定并且支持通用的 Unix glob pattern 格式。

--tests

在清单文件中将 test = true 来在测试模式下构建所有目标。 默认情况下，这包括构建为 单元测试和集成测试的库和二进制文件。请注意，这也会构建任何 所需的依赖项，所以 lib 目标可能会被构建两次（一次是作为一个 单元测试，一次作为二进制文件、集成测试等的依赖项）。 可以在清单文件通过设置目标的 test 标志来启用或禁用此目标。

--bench 名称...

构建指定的基准测试。这个标志位可以多次指定并且支持通用的 Unix glob pattern 格式。

--benches

在清单文件中将 bench = true 来在测试模式下构建所有目标。 默认情况下，这包括构建为 基准测试的库和二进制文件。请注意，这也会构建任何 所需的依赖项，所以 lib 目标可能会被构建两次（一次是作为一个 基准测试，一次作为二进制文件、基准测试等的依赖项）。 可以在清单文件通过设置目标的 bench 标志来启用或禁用此目标。

--all-targets

构建所有目标。 相当于指定 --lib --bins --tests --benches --examples.

选择特性

feature 标志允许你有选择的启用特性。 当没有设置这个此标志时，将为所有已选的包启用 defualt 特性。

更多细节查看 the features documentation

-F 特性

--features 特性

要启用的特性列表，列表用空格或逗号分割。 工作空间中成员的特性可以通过 package-name/feature-name 语法启用。 此标志可以多次指定，会启用所有指定的特性。

--all-features

为全部选择的包启用所有可用的特性。

--no-default-features

不要为选择的包 默认 启用默认特性。

编译选项

--target triple

指定架构的构建。 默认为宿主机的架构。三元组的通用格式为 <arch><sub>-<vendor>-<sys>-<abi>。运行 rustc --print target-list 来获取支持的目标列表。 这个标志可以指定多次。

这也可以与 build.target config value 一起使用。

注意，指定这个标志会使 Cargo 在不同的模式下运行，目标 artifacts 被放在一个单独的目录中。 更多细节请参见 build cache 文档。

-r

--release

用 release 配置构建优化的 artifacts 。 请参阅 --profile 选项，通过名称选择一个特定的配置。

--profile name

用给定的配置进行测试。

rustc 子命令会对下列特殊名称的配置有特殊的行为:

• check — 与 cargo-check(1) 命令一样进行构建，使用 dev 配置。
• test — 与 cargo-test(1) 命令一样进行构建，在测试模式下构建，这会启用测试并启用 test cfg配置。 更多信息请查看 rustc tests
• bench — 与 cargo-bench(1) 命令一样进行构建，与 test 配置类似。

关于配置的更多细节，请参见 the reference

--ignore-rust-version

即使选择的 Rust 编译器比项目的 rust-version 字段中配置的所需的Rust版本要低，也要测试目标。

--timings=fmts

输出每次编译所需时间的信息，并跟踪一段时间的并发信息。 接受一个可选的逗号分隔的输出格式列表; 没有参数的 --timings 将默认为 --timings=html 。 指定一个输出格式(而不是默认的)是不稳定的，需要 -Zunstable-options 。 有效的输出格式:

• html (不稳定，需要 -Zunstable-options): 在 target/cargo-timings 目录下写一个方便阅读的文件 cargo-timing.html ，并附上编译报告 。 如果你想查看更早的运行情况，也可以在同一目录下写一份文件名中带有时间戳报告。 HTML输出只适合用户使用，并不提供机器可读的计时数据。
• json (不稳定，需要 -Zunstable-options): 发出机器可读的JSON格式的计时信息。

--crate-type crate-type

按给定的 crate 类型进行构建。 这个标志接收逗号分割的 crate 类型列表，允许的 crate 类型与清单中配置 Cargo target 的 crate-type 字段相同。 在 crate-type 字段查看可用的类型

如果清单中制定了列表, 并且提供了 --crate-type, 命令行参数会覆盖清单指定的列表。

此标志仅用于构建 lib 或 example 类库目标.

输出选项

--target-dir directory

所有生成的 artifacts 和中间文件的目录。 也可以与 CARGO_TARGET_DIR 环境变量或 build.target-dir 配置项 一起指定。 默认是工作空间中 target 的根目录。

显示选项

-v

--verbose

使用 verbose 级别输出详细信息。 指定两次此选项来输出 "十分详细" 的输出信息， 这会包含额外的输出信息，比如依赖警告和构建脚本输出。 也可以与 term.verbose config value 一起使用。

-q

--quiet

不要打印任何 cargo 日志信息。 也可以与 term.quiet config value 一起使用。

--color when

控制的日志的颜色。 有效的值如下:

• auto (默认): 自动检测终端颜色支持是否可用。
• always: 总是带颜色显示。
• never: 不带颜色显示.

也可以与 term.color config value 一起使用。

--message-format fmt

诊断信息的输出格式。可以多次指定，由逗号分隔的数值组成。有效值:

• human (默认): 以人类可读的文本格式显示。与 short 和 json冲突。
• short: 生成更短的、人类可读的文本信息。 与human 和 json 冲突。
• json: 生成 JSON 信息输出到 stdout. 更多细节请参见 the reference。 与 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-path path

Cargo.toml 文件的路径. 默认情况下，Cargo 会在当前目录或任何父目录下搜索 Cargo.toml 文件。

--frozen

--locked

这两个标志都要求 Cargo.lock 文件是最新的。 如果 .lock 文件缺失，或者需要更新，Cargo 将以错误退出。 --frozen 标志也可以防止 Cargo 访问网络以确定其是否过期。

这些可以用于需要判断 Cargo.lock 文件是否最新（比如CI构建）或者想避免网络访问的环境中。

--offline

禁止 Cargo 在任何情况下访问网络。 如果没有这个标志，当 Cargo 需要访问网络而网络不可用时，它会以错误的方式停止。 有了这个标志，Cargo会尝试在没有网络的情况下进行。

请注意，这可能会导致与在线模式不同的依赖方案。Cargo 会将自己限制在本地的 crate 仓库上， 即使在本地拷贝的索引中可能有更新的版本也是如此。 参见 cargo-fetch(1) 命令来在离线前下载依赖关系。

也可以用 net.offline config value 来指定。

通用选项

+toolchain

如果 Cargo 已经和 rustup 一起安装, 并且 cargo 的第一个参数以 + 开头, 它将被解释为一个rustup工具链的名字 (比如 +stable 或者 +nightly)。 更多关于工具链覆盖工作的信息，请参见 rustup documentation

--config KEY=VALUE or PATH

覆盖一个 Cargo 配置值。参数应该使用 TOML 的 KEY=VALUE 语法，或者提供一个额外配置文件的路径。 这个标志可以被多次指定。更多信息请参见 command-line overrides section。

-h

--help

打印帮助信息。

-Z flag

Cargo 的不稳定 (仅限 nightly 版本) 标志。 更多信息请运行 cargo -Z help。

其他选项

-j N

--jobs N

要运行的并行作业的数量。 也可以通过 build.jobs config value 配置值来指定。 默认为逻辑CPU的数量。如果是负数，它将最大的并行作业数量设置为逻辑CPU的数量加上所提供的值。不应该是0。

--keep-going

尽可能多地构建依赖关系图中的 crates, 而不是有一个 crate 构建失败则中止构建。 不稳定，需要 -Zunstable-options。

--future-incompat-report

展示一个未来兼容性报告(future-incompat report)，显示在执行此命令过程中产生的任何未来不兼容(future-incompatible)的警告

请参阅 cargo-report(1)

环境

更多关于 Cargo 读取的环境变量信息，请参见the reference。

退出状态

• 0: Cargo 成功退出.
• 101: Cargo 错误退出.

示例

1. 检查你的软件包(不包括依赖)是否使用了不安全代码:

   cargo rustc --lib -- -D unsafe-code
   

2. 在每日版编译器上尝试实验标志，比如这个标志打印了所有 type 的大小:

   cargo rustc --lib -- -Z print-type-sizes
   

3. 用命令行选项覆盖 Cargo.toml 中的 crate-type 字段:

   cargo rustc --lib --crate-type lib,cdylib
   

另请参见

cargo(1), cargo-build(1), rustc(1)