命令行参数

以下是 rustc 的命令行参数列表及其作用。

-h/--help: 获取帮助

此标志将打印出 rustc 的帮助信息。

--cfg: 配置编译环境

此标志可以打开或关闭用于 条件编译 的各种 #[cfg] 设置。

该值可以是单个标识符，也可以是用 = 分隔的两个标识符。

例如，--cfg 'verbose' 或 --cfg 'feature="serde"'。它们分别对应于 #[cfg(verbose)] 和 #[cfg(feature = "serde")]。

--check-cfg: 启用检查条件配置

此标志将启用检查条件配置。有关更多详细信息和说明，请参阅本书的 检查条件配置 部分。

例如，--check-cfg 'cfg(verbose)' 或 --check-cfg 'cfg(feature, values("serde"))'。它们分别对应于 #[cfg(verbose)] 和 #[cfg(feature = "serde")]。

-L: 将目录添加到库搜索路径

-L 标志添加一个用于搜索外部 crate 和库的路径。

可以使用 -L KIND=PATH 的形式指定搜索路径的类型，其中 KIND 可以是以下之一

  • dependency — 仅在此目录中搜索传递依赖项。
  • crate — 仅在此目录中搜索此 crate 的直接依赖项。
  • native — 仅在此目录中搜索原生库。
  • framework — 仅在此目录中搜索 macOS 框架。
  • all — 在此目录中搜索所有类型的库。如果未指定 KIND，则默认为此选项。

-l: 将生成的 crate 链接到原生库

语法：-l [KIND[:MODIFIERS]=]NAME[:RENAME]。

此标志允许您在构建 crate 时指定链接到特定的原生库。

可以使用 -l KIND=lib 的形式指定库的类型，其中 KIND 可以是以下之一

  • dylib — 原生动态库。
  • static — 原生静态库（例如 .a 存档）。
  • framework — macOS 框架。

如果指定了类型，则可以将链接修饰符附加到该类型。修饰符指定为以逗号分隔的字符串，每个修饰符都以 + 或 - 为前缀，分别表示启用或禁用该修饰符。目前不支持在单个 link 属性中指定多个 modifiers 参数，也不支持在同一个 modifiers 参数中指定多个相同的修饰符。

示例：-l static:+whole-archive=mylib。

库的类型和修饰符也可以在 #[link] 属性 中指定。如果未在 link 属性或命令行中指定类型，则默认情况下将链接动态库，除非构建的是静态可执行文件。如果在命令行中指定了类型，则它将覆盖 link 属性中指定的类型。

可以使用 -l ATTR_NAME:LINK_NAME 的形式覆盖 link 属性中使用的名称，其中 ATTR_NAME 是 link 属性中的名称，LINK_NAME 是将要链接的实际库的名称。

链接修饰符：whole-archive

此修饰符仅与 static 链接类型兼容。使用任何其他类型将导致编译器错误。

+whole-archive 表示静态库作为整个存档链接，不会丢弃任何目标文件。

此修饰符对于类似 ld 的链接器转换为 --whole-archive，对于 link.exe 转换为 /WHOLEARCHIVE，对于 ld64 转换为 -force_load。对于不支持它的链接器，该修饰符不起作用。

此修饰符的默认值为 -whole-archive。

注意：为了向后兼容，在某些情况下默认值可能会有所不同，但这不能保证。如果您需要整个存档语义，请显式使用 +whole-archive。

链接修饰符：bundle

此修饰符仅与 static 链接类型兼容。使用任何其他类型将导致编译器错误。

在构建 rlib 或 staticlib 时，+bundle 表示原生静态库将被打包到 rlib 或 staticlib 存档中，然后在链接最终二进制文件时从中检索。

在构建 rlib 时，-bundle 表示原生静态库被注册为该 rlib 的“按名称”依赖项，并且只有在链接最终二进制文件时才会包含来自它的目标文件，在最终链接期间也会按该名称执行文件搜索。

在构建 staticlib 时，-bundle 表示原生静态库根本不包含在存档中，一些更高级别的构建系统需要在链接最终二进制文件时稍后添加它。

此修饰符在构建其他目标（如可执行文件或动态库）时无效。

此修饰符的默认值为 +bundle。

链接修饰符：verbatim

此修饰符与所有链接类型兼容。

+verbatim 表示 rustc 本身不会在库名称中添加任何特定于目标的库前缀或后缀（如 lib 或 .a），并且会尽力向链接器请求相同的内容。

对于支持 GNU 扩展的类似 ld 的链接器，rustc 在传递库时将使用 -l:filename 语法（注意冒号），因此链接器不会向其添加任何前缀或后缀。有关更多详细信息，请参阅 ld 文档中的 -l namespec。

对于不支持任何逐字修饰符的链接器（例如 link.exe 或 ld64），库名称将按原样传递。因此，此选项最可靠的跨平台使用场景是不涉及链接器的情况，例如将原生库捆绑到 rlib 中。

-verbatim 表示 rustc 在将库名称传递给链接器之前，将在其前面添加特定于目标的前缀和后缀，或者不会阻止链接器隐式添加它。

特别是在 raw-dylib 类型的情况下，在 Windows 上会将 .dll 添加到库名称中。

此修饰符的默认值为 -verbatim。

注意：即使使用 +verbatim 和 -l:filename 语法，类似 ld 的链接器通常也不支持传递库的绝对路径。通常，此类路径需要作为输入文件传递，而无需使用任何类似 -l 的选项，例如 ld /my/absolute/path。

-Clink-arg=/my/absolute/path 可用于从稳定的 rustc 执行此操作。

--crate-type: 编译器要生成的 crate 类型列表

这指示 rustc 要构建哪种 crate 类型。此标志接受以逗号分隔的值列表，并且可以指定多次。有效的 crate 类型有

  • lib — 生成编译器首选的库类型，当前默认为 rlib。
  • rlib — Rust 静态库。
  • staticlib — 原生静态库。
  • dylib — Rust 动态库。
  • cdylib — 原生动态库。
  • bin — 可运行的可执行程序。
  • proc-macro — 生成适合于可由编译器加载的过程宏库的格式。

可以使用 crate_type 属性 指定 crate 类型。--crate-type 命令行值将覆盖 crate_type 属性。

更多详细信息可以在参考文档的 链接 章节中找到。

--crate-name: 指定正在构建的 crate 的名称

这会将您的 crate 的名称告知 rustc。

--edition：指定要使用的版本

此标志接受 2015、2018 或 2021 作为值。默认值为 2015。更多关于版本的信息可以在版本指南中找到。

--emit：指定要生成的输出文件类型

此标志控制编译器生成的输出文件类型。它接受以逗号分隔的值列表，并且可以指定多次。有效的输出类型有：

  • asm - 生成包含 crate 程序集代码的文件。默认输出文件名是 CRATE_NAME.s。
  • dep-info - 生成一个 Makefile 语法的文件，该文件指示加载以生成 crate 的所有源文件。默认输出文件名是 CRATE_NAME.d。
  • link - 生成由 --crate-type 指定的 crate。默认输出文件名取决于 crate 类型和平台。如果未指定 --emit，则这是默认值。
  • llvm-bc - 生成包含LLVM 位码的二进制文件。默认输出文件名是 CRATE_NAME.bc。
  • llvm-ir - 生成包含LLVM IR的文件。默认输出文件名是 CRATE_NAME.ll。
  • metadata - 生成包含 crate 元数据的文件。默认输出文件名是 libCRATE_NAME.rmeta。
  • mir - 生成包含 rustc 中间表示形式的文件。默认输出文件名是 CRATE_NAME.mir。
  • obj - 生成本机目标文件。默认输出文件名是 CRATE_NAME.o。

可以使用-o 标志设置输出文件名。可以使用-C extra-filename 标志在文件名中添加后缀。除非使用--out-dir 标志，否则文件将写入当前目录。每个输出类型也可以使用 KIND=PATH 的形式指定输出文件名，该形式优先于 -o 标志。指定 -o - 或 --emit KIND=- 会要求 rustc 输出到标准输出。文本输出类型（asm、dep-info、llvm-ir 和 mir）可以写入标准输出，无论它是否是 tty。如果任何二进制输出类型被写入到是 tty 的标准输出，这将导致错误。如果多个输出类型将被写入标准输出，这也将导致错误，因为它们将全部混合在一起。

--print：打印编译器信息

此标志打印有关编译器的各种信息。此标志可以指定多次，并且信息按照标志指定的顺序打印。指定 --print 标志通常会禁用--emit步骤，并且只会打印请求的信息。有效的打印值类型有：

  • crate-name - crate 的名称。
  • file-names - link 输出类型创建的文件的名称。
  • sysroot - sysroot 的路径。
  • target-libdir - 目标 libdir 的路径。
  • cfg - cfg 值列表。有关 cfg 值的更多信息，请参见条件编译。
  • target-list - 已知目标列表。可以使用 --target 标志选择目标。
  • target-cpus - 当前目标可用的 CPU 值列表。可以使用-C target-cpu=val 标志选择目标 CPU。
  • target-features - 当前目标可用的目标功能列表。可以使用-C target-feature=val 标志启用目标功能。此标志不安全。有关更多详细信息，请参见已知问题。
  • relocation-models - 重定位模型列表。可以使用-C relocation-model=val 标志选择重定位模型。
  • code-models - 代码模型列表。可以使用-C code-model=val 标志选择代码模型。
  • tls-models - 支持的线程本地存储模型列表。可以使用 -Z tls-model=val 标志选择模型。
  • native-static-libs - 这可以在创建 staticlib crate 类型时使用。如果这是唯一的标志，它将执行完整的编译，并包含一个诊断说明，指示链接生成的静态库时要使用的链接器标志。该说明以文本 native-static-libs: 开头，以便于获取输出。
  • link-args - 此标志不会禁用 --emit 步骤。链接时，此标志会导致 rustc 以人类可读的形式打印完整的链接器调用。这在调试链接器选项时很有用。此调试输出的确切格式不是稳定的保证，但它将包含链接器可执行文件和传递给链接器的每个命令行参数的文本。
  • deployment-target - 为选定的 Apple 平台目标当前选择的部署目标（或最低操作系统版本）。此值可以与 Rust 构建一起使用或传递给需要此信息的其它组件，例如 C 编译器。如果环境中不存在 *_DEPLOYMENT_TARGET 变量，则返回 rustc 支持的最低部署目标，否则返回变量的解析值。

可以选择为每个请求的信息类型指定文件路径，格式为 --print KIND=PATH，就像 --emit 一样。指定路径时，信息将写入该路径而不是标准输出。

-g：包含调试信息

-C debuginfo=2的同义词。

-O：优化代码

-C opt-level=2的同义词。

-o：输出文件名

此标志控制输出文件名。

--out-dir：写入输出的目录

输出的 crate 将写入此目录。如果使用-o 标志，则忽略此标志。

--explain：提供错误消息的详细说明

rustc 的每个错误都有一个错误代码；这将打印出对给定错误的更长说明。

--test：构建测试工具

编译此 crate 时，rustc 将忽略您的 main 函数，而是生成一个测试工具。有关测试的更多信息，请参见测试章节。

--target：选择要构建的目标三元组

这控制要生成哪个目标。

-W：设置 lint 警告

此标志将设置哪些 lint 应设置为警告级别。

注意：这些 lint 级别参数的顺序会被考虑在内，有关更多信息，请参见通过编译器标志设置 lint 级别。

--force-warn：强制 lint 发出警告

此标志将给定的 lint 设置为强制警告级别，并且该级别不能被覆盖，甚至忽略lint 上限。

-A：设置 lint 允许

此标志将设置哪些 lint 应设置为允许级别。

注意：这些 lint 级别参数的顺序会被考虑在内，有关更多信息，请参见通过编译器标志设置 lint 级别。

-D：设置 lint 拒绝

此标志将设置哪些 lint 应设置为拒绝级别。

注意：这些 lint 级别参数的顺序会被考虑在内，有关更多信息，请参见通过编译器标志设置 lint 级别。

-F：设置 lint 禁止

此标志将设置哪些 lint 应设置为禁止级别。

注意：这些 lint 级别参数的顺序会被考虑在内，有关更多信息，请参见通过编译器标志设置 lint 级别。

-Z：设置不稳定选项

此标志将允许您设置 rustc 的不稳定选项。为了设置多个选项，可以使用多次 -Z 标志。例如：rustc -Z verbose-internals -Z time-passes。使用 -Z 指定选项仅在 nightly 版本上可用。要查看所有可用选项，请运行：rustc -Z help，或参见不稳定功能手册。

--cap-lints：设置最严格的 lint 级别

此标志允许您“限制”lint，有关更多信息，请参见此处。

-C/--codegen：代码生成选项

此标志将允许您设置代码生成选项。

-V/--version：打印版本

此标志将打印出 rustc 的版本。

-v/--verbose：使用详细输出

此标志与其它标志结合使用时，会使它们产生额外的输出。

--extern：指定外部库的位置

此标志允许您传递直接依赖项的外部 crate 的名称和位置。间接依赖项（依赖项的依赖项）使用 -L 标志 定位。给定的 crate 名称将添加到 外部前奏 中，类似于在根模块中指定 extern crate。给定的 crate 名称不需要与构建库时使用的名称匹配。

指定 --extern 与 extern crate 的行为有一个区别：--extern 只是使 crate 成为链接的*候选者*；除非它被积极使用，否则它实际上不会链接它。在极少数情况下，您可能希望确保即使您没有在代码中积极使用 crate 也能链接它：例如，如果它更改了全局分配器，或者它包含供其他编程语言使用的 #[no_mangle] 符号。在这种情况下，您需要使用 extern crate。

此标志可以指定多次。此标志采用以下任一格式的参数

  • CRATENAME=PATH — 指示在给定路径中找到给定的 crate。
  • CRATENAME — 指示可以在搜索路径中找到给定的 crate，例如在 sysroot 中或通过 -L 标志。

可以为不同的 crate 类型多次指定相同的 crate 名称。如果同时找到 rlib 和 dylib，则使用内部算法来决定使用哪个进行链接。-C prefer-dynamic 标志 可用于影响使用哪个。

如果使用和不使用路径指定相同的 crate 名称，则使用带有路径的名称，并且无路径标志无效。

--sysroot：覆盖系统根目录

“sysroot”是 rustc 查找 Rust 发行版附带的 crate 的位置；此标志允许覆盖该位置。

--error-format：控制如何生成错误

此标志允许您控制消息的格式。消息将打印到 stderr。有效选项为

  • human — 人类可读的输出。这是默认设置。
  • json — 结构化 JSON 输出。有关更多详细信息，请参阅JSON 章节。
  • short — 简短的单行消息。

--color：配置输出的颜色

此标志允许您控制输出的颜色设置。有效选项为

  • auto — 如果输出到 tty，则使用颜色。这是默认设置。
  • always — 始终使用颜色。
  • never — 从不为输出着色。

--diagnostic-width：指定诊断信息的终端宽度

此标志采用一个数字，该数字指定终端的宽度（以字符为单位）。诊断信息的格式将考虑宽度，使其更好地适合屏幕。

--remap-path-prefix：重新映射输出中的源名称

重新映射所有输出中的源路径前缀，包括编译器诊断信息、调试信息、宏扩展等。它采用 FROM=TO 形式的值，其中等于 FROM 的路径前缀将被重写为值 TO。FROM 本身可能包含 = 符号，但 TO 值可能不包含。此标志可以指定多次。

这对于规范化构建产品很有用，例如通过从对象文件中删除当前目录。替换是纯文本的，不考虑当前系统的路径名语法。例如，--remap-path-prefix foo=bar 将匹配 foo/lib.rs，但不匹配 ./foo/lib.rs。

当给出多个重新映射并且其中几个匹配时，将应用*最后一个*匹配的重新映射。

--json：配置编译器打印的 json 消息

当将 --error-format=json 选项 传递给 rustc 时，所有编译器的诊断输出都将以 JSON blob 的形式发出。--json 参数可以与 --error-format=json 结合使用，以配置 JSON blob 包含的内容以及发出哪些 blob。

使用 --error-format=json，编译器将始终以 JSON blob 的形式发出任何编译器错误，但 --json 标志还可以使用以下选项来自定义输出

  • diagnostic-short - 诊断消息的 json blob 应使用“short”呈现而不是正常的“human”默认呈现。这意味着 --error-format=short 的输出将嵌入到 JSON 诊断信息中，而不是默认的 --error-format=human。

  • diagnostic-rendered-ansi - 默认情况下，rendered 字段中的 JSON blob 将包含诊断信息的纯文本呈现。此选项改为指示诊断信息应包含嵌入式 ANSI 颜色代码，这些代码旨在用于以 rustc 通常已经为终端输出执行的方式为消息着色。请注意，这可以与 fwdansi 等 crate 结合使用，以将 Windows 上的这些 ANSI 代码转换为控制台命令，或者与 strip-ansi-escapes 结合使用（如果您希望稍后选择性地删除 ansi 颜色）。

  • artifacts - 这指示 rustc 为发出的每个工件发出一个 JSON blob。工件对应于 --emit CLI 参数 的请求，并且一旦工件在文件系统上可用，就会发出通知。

  • future-incompat - 包含一个 JSON 消息，该消息包含一份报告，说明 crate 是否包含任何将来可能无法编译的代码。

请注意，将 --json 参数与 --color 参数组合使用是无效的，并且需要将 --json 与 --error-format=json 组合使用。

有关更多详细信息，请参阅JSON 章节。

@path：从路径加载命令行标志

如果在命令行上指定 @path，它将打开 path 并从中读取命令行选项。这些选项每行一个；空行表示空选项。该文件可以使用 Unix 或 Windows 样式的行尾，并且必须编码为 UTF-8。