配置文件

配置文件提供了一种更改编译器设置的方法，可以影响优化和调试符号等内容。

Cargo 有 4 个内置配置文件：dev、release、test 和 bench。如果在命令行上未指定配置文件，则会根据正在运行的命令自动选择配置文件。除了内置配置文件外，还可以指定自定义用户定义的配置文件。

可以使用 [profile] 表在 Cargo.toml 中更改配置文件设置。在每个命名的配置文件中，可以使用如下所示的键/值对更改各个设置

[profile.dev]
opt-level = 1               # Use slightly better optimizations.
overflow-checks = false     # Disable integer overflow checks.

Cargo 只查看工作空间根目录下 Cargo.toml 清单中的配置文件设置。依赖项中定义的配置文件设置将被忽略。

此外，还可以从 配置 定义中覆盖配置文件。在配置文件或环境变量中指定配置文件将覆盖 Cargo.toml 中的设置。

配置文件设置

以下是可以在配置文件中控制的设置列表。

opt-level

opt-level 设置控制 -C opt-level 标志，该标志控制优化级别。较高的优化级别可能会生成更快的运行时代码，但代价是编译时间更长。较高的级别也可能会更改和重新排列编译后的代码，这可能会使其更难与调试器一起使用。

有效选项为

  • 0：无优化
  • 1：基本优化
  • 2：一些优化
  • 3：所有优化
  • "s"：优化二进制文件大小
  • "z"：优化二进制文件大小，但也关闭循环向量化。

建议尝试不同的级别，为您的项目找到合适的平衡点。可能会出现令人惊讶的结果，例如级别 3 比 2 慢，或者 "s" 和 "z" 级别不一定会更小。随着新版本 rustc 更改优化行为，您可能还需要随着时间的推移重新评估您的设置。

另请参阅 配置文件引导优化，了解更高级的优化技术。

debug

debug 设置控制 -C debuginfo 标志，该标志控制编译后的二进制文件中包含的调试信息量。

有效选项为

  • 0、false 或 "none"：根本没有调试信息，release 的默认值
  • "line-directives-only"：仅限行信息指令。对于 nvptx* 目标，这将启用 分析。对于其他用例，line-tables-only 是更好、更兼容的选择。
  • "line-tables-only"：仅限行表。生成最少量的调试信息，用于包含文件名/行号信息的回溯，但不包含任何其他信息，即没有变量或函数参数信息。
  • 1 或 "limited"：没有类型或变量级信息的调试信息。生成比 line-tables-only 更详细的模块级信息。
  • 2、true 或 "full"：完整的调试信息，dev 的默认值

有关每个选项作用的更多信息，请参阅 rustc 关于 debuginfo 的文档。

您可能还希望根据需要配置 split-debuginfo 选项。

split-debuginfo

split-debuginfo 设置控制 -C split-debuginfo 标志，该标志控制生成的调试信息是放在可执行文件本身中还是放在可执行文件旁边。

此选项是一个字符串，可接受的值与 编译器接受 的值相同。对于启用了调试信息的配置文件，此选项在 macOS 上的默认值为 unpacked。否则，此选项的默认值在 rustc 文档 中有说明，并且特定于平台。某些选项仅在 夜间频道 上可用。在执行更多测试并稳定了对 DWARF 的支持后，Cargo 默认值将来可能会更改。

请注意，Cargo 和 rustc 对此选项有不同的默认值。此选项允许 Cargo 尝试不同的标志组合，从而提供更好的调试和开发体验。

strip

strip 选项控制 -C strip 标志，该标志指示 rustc 从二进制文件中剥离符号或调试信息。可以通过以下方式启用它

[package]
# ...

[profile.release]
strip = "debuginfo"

strip 的可能字符串值为 "none"、"debuginfo" 和 "symbols"。默认值为 "none"。

您还可以使用布尔值 true 或 false 配置此选项。strip = true 等效于 strip = "symbols"。strip = false 等效于 strip = "none" 并完全禁用 strip。

debug-assertions

debug-assertions 设置控制 -C debug-assertions 标志，该标志打开或关闭 cfg(debug_assertions) 条件编译。调试断言旨在包含仅在调试/开发构建中可用的运行时验证。这些在发布版本中可能过于昂贵或不受欢迎。调试断言启用了标准库中的 debug_assert! 宏。

有效选项为

  • true：启用
  • false：禁用

overflow-checks

overflow-checks 设置控制 -C overflow-checks 标志，该标志控制 运行时整数溢出 的行为。启用溢出检查后，溢出时会出现 panic。

有效选项为

  • true：启用
  • false：禁用

lto

lto 设置控制 rustc 的 -C lto、-C linker-plugin-lto 和 -C embed-bitcode 选项，这些选项控制 LLVM 的 链接时优化。LTO 可以生成优化程度更高的代码，使用全程序分析，但代价是链接时间更长。

有效选项为

  • false：执行“精简本地 LTO”，仅在其 代码生成单元 中对本地 crate 执行“精简”LTO。如果代码生成单元为 1 或 opt-level 为 0，则不执行 LTO。
  • true 或 "fat"：执行“胖”LTO，尝试对依赖图中的所有 crate 执行优化。
  • "thin"：执行 “精简”LTO。这与“胖”类似，但运行时间要短得多，同时仍然可以实现与“胖”类似的性能提升。
  • "off"：禁用 LTO。

如果您对跨语言 LTO 感兴趣，请参阅 linker-plugin-lto 章节。Cargo 本身尚不支持此功能，但可以通过 RUSTFLAGS 执行。

panic

panic 设置控制 -C panic 标志，该标志控制使用哪种 panic 策略。

有效选项为

  • "unwind"：在 panic 时展开堆栈。
  • "abort"：在 panic 时终止进程。

设置为 "unwind" 时，实际值取决于目标平台的默认值。例如，NVPTX 平台不支持展开，因此它始终使用 "abort"。

测试、基准测试、构建脚本和 proc 宏会忽略 panic 设置。rustc 测试工具目前需要 unwind 行为。请参阅启用 abort 行为的 panic-abort-tests 不稳定标志。

此外，当使用 abort 策略并构建测试时，所有依赖项也将被迫使用 unwind 策略构建。

incremental

incremental 设置控制 -C incremental 标志，该标志控制是否启用增量编译。增量编译会导致 rustc 将附加信息保存到磁盘，这些信息将在重新编译 crate 时重复使用，从而缩短重新编译时间。附加信息存储在 target 目录中。

有效选项为

  • true：启用
  • false：禁用

增量编译仅用于工作区成员和“路径”依赖项。

可以使用 CARGO_INCREMENTAL 环境变量 或 build.incremental 配置变量全局覆盖增量值。

codegen-units

codegen-units 设置控制 -C codegen-units 标志，该标志控制将 crate 拆分为多少个“代码生成单元”。更多的代码生成单元允许并行处理更多 crate，可能会减少编译时间，但可能会生成速度较慢的代码。

此选项采用大于 0 的整数。

增量 构建的默认值为 256，非增量构建的默认值为 16。

rpath

rpath 设置控制 -C rpath 标志，该标志控制是否启用 rpath。

默认配置文件

dev

dev 配置文件用于正常的开发和调试。它是 cargo build 等构建命令的默认配置文件，并用于 cargo install --debug。

dev 配置文件的默认设置为

[profile.dev]
opt-level = 0
debug = true
split-debuginfo = '...'  # Platform-specific.
strip = "none"
debug-assertions = true
overflow-checks = true
lto = false
panic = 'unwind'
incremental = true
codegen-units = 256
rpath = false

release

release 配置文件适用于用于发布和生产的优化工件。当使用 --release 标志时，将使用此配置文件，并且它是 cargo install 的默认配置文件。

release 配置文件的默认设置为

[profile.release]
opt-level = 3
debug = false
split-debuginfo = '...'  # Platform-specific.
strip = "none"
debug-assertions = false
overflow-checks = false
lto = false
panic = 'unwind'
incremental = false
codegen-units = 16
rpath = false

test

test 配置文件是 cargo test 使用的默认配置文件。test 配置文件继承 dev 配置文件的设置。

bench

bench 配置文件是 cargo bench 使用的默认配置文件。bench 配置文件继承 release 配置文件的设置。

构建依赖项

为了快速编译，默认情况下，所有配置文件都不会优化构建依赖项（构建脚本、proc 宏及其依赖项），并且在不将构建依赖项用作运行时依赖项时避免计算调试信息。构建覆盖的默认设置为

[profile.dev.build-override]
opt-level = 0
codegen-units = 256
debug = false # when possible

[profile.release.build-override]
opt-level = 0
codegen-units = 256

但是，如果在运行构建依赖项时发生错误，则打开完整调试信息将在需要时改进回溯和可调试性

debug = true

构建依赖项否则会继承正在使用的活动配置文件中的设置，如 配置文件选择 中所述。

自定义配置文件

除了内置配置文件之外，还可以定义其他自定义配置文件。这些对于设置多个工作流和构建模式很有用。定义自定义配置文件时，必须指定 inherits 键以指定未指定设置时自定义配置文件继承哪个配置文件的设置。

例如，假设您要将正常的发布版本与使用 LTO 优化的发布版本进行比较，则可以在 Cargo.toml 中指定如下内容

[profile.release-lto]
inherits = "release"
lto = true

然后可以使用 --profile 标志选择此自定义配置文件

cargo build --profile release-lto

每个配置文件的输出将放置在 target 目录 中与配置文件同名的目录中。如上例所示，输出将进入 target/release-lto 目录。

配置文件选择

使用的配置文件取决于命令、--release 或 --profile 等命令行标志以及包（在 覆盖 的情况下）。如果未指定配置文件，则默认配置文件为

命令默认配置文件
cargo run、cargo build、

cargo check、cargo rustc		dev 配置文件
cargo testtest 配置文件
cargo benchbench 配置文件
cargo installrelease 配置文件

您可以使用 --profile=NAME 选项切换到不同的配置文件，该选项将使用给定的配置文件。--release 标志等效于 --profile=release。

所选配置文件适用于所有 Cargo 目标，包括 库、二进制文件、示例、测试 和 基准测试。

可以使用下面描述的 覆盖 指定特定包的配置文件。

覆盖

可以为特定包和构建时 crate 覆盖配置文件设置。要覆盖特定包的设置，请使用 package 表更改命名包的设置

# The `foo` package will use the -Copt-level=3 flag.
[profile.dev.package.foo]
opt-level = 3

包名称实际上是一个 包 ID 规范，因此您可以使用 [profile.dev.package."foo:2.1.0"] 等语法定位包的各个版本。

要覆盖所有依赖项（但不是任何工作区成员）的设置，请使用 "*" 包名称

# Set the default for dependencies.
[profile.dev.package."*"]
opt-level = 2

要覆盖构建脚本、proc 宏及其依赖项的设置，请使用 build-override 表

# Set the settings for build scripts and proc-macros.
[profile.dev.build-override]
opt-level = 3

注意：当依赖项既是普通依赖项又是构建依赖项时，Cargo 会尝试在未指定 --target 时仅构建一次。使用 build-override 时，依赖项可能需要构建两次，一次作为普通依赖项，一次使用覆盖的构建设置。这可能会增加初始构建时间。

使用哪个值的优先级按以下顺序进行（第一个匹配项获胜）

  1. [profile.dev.package.name] — 命名的包。
  2. [profile.dev.package."*"] — 对于任何非工作区成员。
  3. [profile.dev.build-override] — 仅适用于构建脚本、proc 宏及其依赖项。
  4. [profile.dev] — Cargo.toml 中的设置。
  5. Cargo 中内置的默认值。

覆盖不能指定 panic、lto 或 rpath 设置。

覆盖和泛型

泛型代码实例化的位置将影响用于该泛型代码的优化设置。当使用配置文件覆盖更改特定 crate 的优化级别时，这可能会导致微妙的交互。如果您尝试提高定义泛型函数的依赖项的优化级别，则这些泛型函数在您的本地 crate 中使用时可能不会被优化。这是因为代码可能是在实例化它的 crate 中生成的，因此可能会使用该 crate 的优化设置。

例如，nalgebra 是一个定义向量和矩阵的库，大量使用泛型参数。如果您的本地代码定义了具体的 nalgebra 类型，如 Vector4<f64> 并使用了它们的方法，则相应的 nalgebra 代码将在您的 crate 中实例化和构建。因此，如果您尝试使用配置文件覆盖来提高 nalgebra 的优化级别，则可能不会提高性能。

使问题进一步复杂化的是，rustc 有一些优化，它会尝试在 crate 之间共享单态化的泛型。如果 opt-level 为 2 或 3，则 crate 不会使用来自其他 crate 的单态化泛型，也不会导出本地定义的单态化项以与其他 crate 共享。在尝试优化依赖项以进行开发时，请考虑尝试 opt-level 1，它将应用一些优化，同时仍然允许共享单态化项。