rust-course/contents/cargo/reference/profiles.md

发布配置Profile

细心的同学可能发现了迄今为止我们已经为 Cargo 引入了不少新的名词，而且这些名词有一个共同的特点，不容易或不适合翻译成中文，因为难以表达的很准确，例如 Cargo Target, Feature 等，这不现在又多了一个 Profile。

默认的 profile

Profile 其实是一种发布配置，例如它默认包含四种: dev、 release、 test 和 bench，正常情况下，我们无需去指定，Cargo 会根据我们使用的命令来自动进行选择

• 例如 cargo build 自动选择 dev profile，而 cargo test 则是 test profile, 出于历史原因，这两个 profile 输出的结果都存放在项目根目录下的 target/debug 目录中，结果往往用于开发/测试环境
• 而 cargo build --release 自动选择 release profile，并将输出结果存放在 target/release 目录中，结果往往用于生产环境

可以看出 Profile 跟 Nodejs 的 dev 和 prod 很像，都是通过不同的配置来为目标环境构建最终编译后的结果: dev 编译输出的结果用于开发环境，prod 则用于生产环境。

针对不同的 profile，编译器还会提供不同的优化级别，例如 dev 用于开发环境，因此构建速度是最重要的：此时，我们可以牺牲运行性能来换取编译性能，那么优化级别就会使用最低的。而 release 则相反，优化级别会使用最高，导致的结果就是运行得非常快，但是编译速度大幅降低。

初学者一个常见的错误，就是使用非 release profile 去测试性能，例如 cargo run，这种方式显然无法得到正确的结果，我们应该使用 cargo run --release 的方式测试性能

profile 可以通过 Cargo.toml 中的 [profile] 部分进行设置和改变:

[profile.dev]
opt-level = 1               # 使用稍高一些的优化级别，最低是0，最高是3
overflow-checks = false     # 关闭整数溢出检查

需要注意的是，每一种 profile 都可以单独的进行设置，例如上面的 [profile.dev]。

如果是工作空间的话，只有根 package 的 Cargo.toml 中的 [profile 设置才会被使用，其它成员或依赖包中的设置会被自动忽略。

另外，profile 还能在 Cargo 自身的配置文件中进行覆盖，总之，通过 .cargo/config.toml 或环境变量的方式所指定的 profile 配置会覆盖项目的 Cargo.toml 中相应的配置。

自定义profile

除了默认的四种 profile，我们还可以定义自己的。对于大公司来说，这个可能会非常有用，自定义的 profile 可以帮助我们建立更灵活的工作发布流和构建模型。

当定义 profile 时，你必须指定 inherits 用于说明当配置缺失时，该 profile 要从哪个 profile 那里继承配置。

例如，我们想在 release profile 的基础上增加 LTO 优化，那么可以在 Cargo.toml 中添加如下内容：

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

然后在构建时使用 --profile 来指定想要选择的自定义 profile ：

cargo build --profile release-lto

与默认的 profile 相同，自定义 profile 的编译结果也存放在 target/ 下的同名目录中，例如 --profile release-lto 的输出结果存储在 target/release-lto 中。

选择 profile

• 默认使用 dev : cargo build, cargo rustc, cargo check, 和 cargo run
• 默认使用 test: cargo test
• 默认使用 bench: cargo bench
• 默认使用 release： cargo install, cargo build --release, cargo run --release
• 使用自定义 profile: cargo build --profile release-lto

profile设置

下面我们来看看 profile 中可以进行哪些优化设置。

opt-level

该字段用于控制 -C opt-level 标志的优化级别。更高的优化级别往往意味着运行更快的代码，但是也意味着更慢的编译速度。

同时，更高的编译级别甚至会造成编译代码的改变和再排列，这会为 debug 带来更高的复杂度。

opt-level 支持的选项包括:

• 0: 无优化
• 1: 基本优化
• 2: 一些优化
• 3: 全部优化
• "s": 优化输出的二进制文件的大小
• "z": 优化二进制文件大小，但也会关闭循环向量化

我们非常推荐你根据自己的需求来找到最适合的优化级别(例如，平衡运行和编译速度)。而且有一点值得注意，有的时候优化级别和性能的关系可能会出乎你的意料之外，例如 3 比 2 更慢，再比如 "s" 并没有让你的二进制文件变得更小。

而且随着 rustc 版本的更新，你之前的配置也可能要随之变化，总之，为项目的热点路径做好基准性能测试是不错的选择，不然总不能每次都手动重写代码来测试吧 :)

如果想要了解更多，可以参考 rustc 文档，这里有更高级的优化技巧。

debug

debug 控制 -C debuginfo 标志，而后者用于控制最终二进制文件输出的 debug 信息量。

支持的选项包括:

• 0 或 false：不输出任何 debug 信息
• 1: 行信息
• 2: 完整的 debug 信息

split-debuginfo

split-debuginfo 控制 -C split-debuginfo 标志，用于决定输出的 debug 信息是存放在二进制可执行文件里还是邻近的文件中。

debug-assertions

该字段控制 -C debug-assertions 标志，可以开启或关闭其中一个条件编译选项： cfg(debug_assertions)。

debug-assertion 会提供运行时的检查，该检查只能用于 debug 模式，原因是对于 release 来说，这种检查的成本较为高昂。

大家熟悉的 debug_assert! 宏也是通过该标志开启的。

支持的选项包括 :

• true: 开启
• false: 关闭

overflow-checks

用于控制 -C overflow-checks 标志，该标志可以控制运行时的整数溢出行为。当开启后，整数溢出会导致 panic。

支持的选项包括 :

• true: 开启
• false: 关闭

lto

lto 用于控制 -C lto 标志，而后者可以控制 LLVM 的链接时优化( link time optimizations )。通过对整个程序进行分析，并以增加链接时间为代价，LTO 可以生成更加优化的代码。

支持的选项包括：

• false: 只会对代码生成单元中的本地包进行 thin LTO 优化，若代码生成单元数为 1 或者 opt-level 为 0，则不会进行任何 LTO 优化
• true 或 fat：对依赖图中的所有包进行 fat LTO 优化
• thin：对依赖图的所有包进行 thin LTO，相比 fat 来说，它仅牺牲了一点性能，但是换来了链接时间的可观减少
• off： 禁用 LTO

如果大家想了解跨语言 LTO，可以看下 -C linker-plugin-lto 标志。

panic

panic 控制 -C panic 标志，它可以控制 panic 策略的选择。

支持的选项包括:

• "unwind": 遇到 panic 后对栈进行展开( unwind )
• "abort": 遇到 panic 后直接停止程序

当设置为 "unwind" 时，具体的栈展开信息取决于特定的平台，例如 NVPTX 不支持 unwind，因此程序只能 "abort"。

测试、基准性能测试、构建脚本和过程宏会忽略 panic 设置，目前来说它们要求是 "unwind"，如果大家希望修改成 "abort"，可以看看 panic-abort-tests 。

另外，当你使用 "abort" 策略且在执行测试时，由于上述的要求，除了测试代码外，所有的依赖库也会忽略该 "abort" 设置而使用 "unwind" 策略。

incremental

incremental 控制 -C incremental 标志，用于开启或关闭增量编译。开启增量编译时，rustc 会将必要的信息存放到硬盘中( target 目录中 )，当下次编译时，这些信息可以被复用以改善编译时间。

支持的选项包括:

• true： 启用
• false: 关闭

增量编译只能用于工作空间的成员和通过 path 引入的本地依赖。

大家还可以通过环境变量 CARGO_INCREMENTAL 或 Cargo 配置 build.incremental 在全局对 incremental 进行覆盖。

codegen-units

codegen-units 控制 -C codegen-units 标志，可以指定一个包会被分隔为多少个代码生成单元。更多的代码生成单元会提升代码的并行编译速度，但是可能会降低运行速度。

对于增量编译，默认值是 256，非增量编译是 16。

r-path

用于控制 -C rpath标志，可以控制 rpath 的启用与关闭。

rpath 代表硬编码到二进制可执行文件或库文件中的运行时代码搜索(runtime search path)，动态链接库的加载器就通过它来搜索所需的库。

默认profile

dev

dev profile 往往用于开发和 debug，cargo build 或 cargo run 默认使用的就是 dev profile，cargo build --debug 也是。

注意：dev profile 的结果并没有输出到 target/dev 同名目录下，而是 target/debug ，这是历史遗留问题

默认的 dev profile 设置如下：

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

release

release 往往用于预发/生产环境或性能测试，以下命令使用的就是 release profile:

• cargo build --release
• cargo run --release
• cargo install

默认的 release profile 设置如下：

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

test

该 profile 用于构建测试，它的设置是继承自 dev

bench

bench profile 用于构建基准测试 benchmark，它的设计默认继承自 release

构建本身依赖

默认情况下，所有的 profile 都不会对构建过程本身所需的依赖进行优化，构建过程本身包括构建脚本、过程宏。

默认的设置是：

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

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

如果是自定义 profile，那它会自动从当前正在使用的 profile 继承相应的设置，但不会修改。

重写profile

我们还可以对特定的包使用的 profile 进行重写(override):

# `foo` package 将使用 -Copt-level=3 标志.
[profile.dev.package.foo]
opt-level = 3

这里的 package 名称实际上是一个 Package ID，因此我们还可以通过版本号来选择: [profile.dev.package."foo:2.1.0"]。

如果要为所有依赖包重写(不包括工作空间的成员):

[profile.dev.package."*"]
opt-level = 2

为构建脚本、过程宏和它们的依赖重写：

[profile.dev.build-override]
opt-level = 3

注意：如果一个依赖同时被正常代码和构建脚本所使用，当 --target 没有指定时，Cargo 只会构建该依赖一次。

但是当使用了 build-override 后，该依赖会被构建两次，一次为正常代码，一次为构建脚本，因此会增加一些编译时间

重写的优先级按以下顺序执行(第一个匹配获胜):

• [profile.dev.package.name]，指定名称进行重写
• [profile.dev.package."*"]，对所有非工作空间成员的 package 进行重写
• [profile.dev.build-override]，对构建脚本、过程宏及它们的依赖进行重写
• [profile.dev]
• Cargo 内置的默认值

重写无法使用 panic、lto 或 rpath 设置。