最小化 Rust 二进制文件大小

本仓库演示了如何最小化 Rust 二进制文件的大小。

默认情况下，Rust 优化执行速度、编译速度和调试便利性，而不是二进制文件大小，因为这对绝大多数应用来说是理想的。但在开发者想要优化二进制文件大小的情况下，Rust 提供了实现这一目标的机制。

以发布模式构建

默认情况下，cargo build 以调试模式构建 Rust 二进制文件。调试模式禁用了许多优化，这有助于调试器（以及运行它们的 IDE）提供更好的调试体验。调试版二进制文件可能比发布版大 30% 或更多。

要最小化二进制文件大小，请以发布模式构建：

$ cargo build --release

从二进制文件中剥离符号

在 Linux 和 macOS 上，默认情况下符号信息会包含在编译后的 .elf 文件中。这些信息对于正确执行二进制文件并不需要。

可以配置 Cargo 来自动剥离二进制文件的符号。修改 Cargo.toml 如下：

[profile.release]
strip = true  # 自动剥离二进制文件中的符号。

在 Rust 1.59 之前，直接在 .elf 文件上运行 strip：

$ strip target/release/min-sized-rust

优化大小

Cargo 默认将发布构建的优化级别设置为 3，这会优化二进制文件的速度。要指示 Cargo 优化最小二进制文件大小，在 Cargo.toml 中使用 z 优化级别：

[profile.release]
opt-level = "z"  # 优化大小。

[!注意] 在某些情况下，"s" 级别可能会比 "z" 产生更小的二进制文件，正如 opt-level 文档中所解释的：

建议尝试不同的级别，为您的项目找到合适的平衡。可能会出现一些意外结果，例如... "s" 和 "z" 级别不一定更小。

启用链接时优化（LTO）

默认情况下，Cargo 指示编译单元独立编译和优化。LTO 指示链接器在链接阶段进行优化。这可以移除死代码，通常会减小二进制文件大小。

在 Cargo.toml 中启用 LTO：

[profile.release]
lto = true

移除 Jemalloc

[!重要] 从 Rust 1.32 开始，jemalloc 默认被移除。如果使用 Rust 1.32 或更新版本，无需采取任何行动来减小这个特性相关的二进制文件大小。

在 Rust 1.32 之前，为了提高某些平台的性能，Rust 捆绑了 jemalloc，这是一个通常优于默认系统分配器的分配器。然而，捆绑 jemalloc 会给最终的二进制文件增加约 200KB。

要在 Rust 1.28 - Rust 1.31 中移除 jemalloc，在 main.rs 顶部添加以下代码：

use std::alloc::System;

#[global_allocator]
static A: System = System;

减少并行代码生成单元以增加优化

默认情况下，Cargo 为发布构建指定 16 个并行代码生成单元。这改善了编译时间，但阻止了一些优化。

在 Cargo.toml 中将此设置为 1，以允许最大程度的大小减小优化：

[profile.release]
codegen-units = 1

恐慌时中止

[!重要] 到目前为止，讨论的减小二进制文件大小的特性并不会影响程序的行为（只影响其执行速度）。这个特性确实会影响行为。

默认情况下，当 Rust 代码遇到必须调用 panic!() 的情况时，它会展开栈并产生有用的回溯。然而，展开代码确实需要额外的二进制大小。可以指示 rustc 立即中止而不是展开，这样就不需要这些额外的展开代码。

在 Cargo.toml 中启用此功能：

[profile.release]
panic = "abort"

移除位置详情

默认情况下，Rust 包含 panic!() 和 [track_caller] 的文件、行和列信息，以提供更有用的回溯信息。这些信息在二进制文件中占用空间，从而增加了编译后二进制文件的大小。 要移除此文件、行和列信息，请使用不稳定的 rustc -Zlocation-detail 标志：

$ RUSTFLAGS="-Zlocation-detail=none" cargo +nightly build --release

使用 build-std 优化 libstd

[!注意] 另请参阅 Xargo，它是 build-std 的前身。 Xargo 目前处于维护状态。

[!注意] 示例项目位于 build_std 文件夹中。

Rust 在其工具链中附带了预构建的标准库（libstd）副本。这意味着开发者无需在每次构建应用程序时都重新构建 libstd。libstd 会被静态链接到二进制文件中。

虽然这非常方便，但对于试图积极优化大小的开发者来说，存在几个缺点。

1. 预构建的 libstd 是为速度而非大小进行优化的。

2. 无法移除特定应用程序中未使用的 libstd 部分（例如 LTO 和 panic 行为）。

这就是 build-std 的用武之地。build-std 功能能够从源代码编译 libstd，与您的应用程序一起构建。它通过 rustup 方便提供的 rust-src 组件来实现这一点。

安装适当的工具链和 rust-src 组件：

$ rustup toolchain install nightly
$ rustup component add rust-src --toolchain nightly

使用 build-std 构建：

# 找到您主机的目标三元组
$ rustc -vV
...
host: x86_64-apple-darwin

# 使用该目标三元组进行 build-std 构建
# 在选项中添加 =std,panic_abort 以使 Cargo.toml 中的 panic = "abort" 选项生效
# 参见：https://github.com/rust-lang/wg-cargo-std-aware/issues/56
$ RUSTFLAGS="-Zlocation-detail=none" cargo +nightly build -Z build-std=std,panic_abort \
  -Z build-std-features="optimize_for_size" \
  --target x86_64-apple-darwin --release

optimize_for_size 标志向 libstd 提供了一个提示，表明它应该尝试使用针对二进制大小优化的算法。有关它的更多信息可以在跟踪问题中找到。

在 macOS 上，最终剥离后的二进制文件大小减少到 51KB。

使用 panic_immediate_abort 移除 panic 字符串格式化

即使在 Cargo.toml 中指定了 panic = "abort"，默认情况下 rustc 仍会在最终二进制文件中包含 panic 字符串和格式化代码。 一个不稳定的 panic_immediate_abort 功能已合并到 nightly rustc 编译器中以解决这个问题。

要使用此功能，重复上述使用 build-std 的说明，但还要传递以下 -Z build-std-features=panic_immediate_abort 选项。

$ cargo +nightly build -Z build-std=std,panic_abort -Z build-std-features=panic_immediate_abort \
    --target x86_64-apple-darwin --release

在 macOS 上，最终剥离后的二进制文件大小减少到 30KB。

通过 #![no_main] 和谨慎使用 libstd 移除 core::fmt

[!注意] 示例项目位于 no_main 文件夹中。

到目前为止，我们没有限制从 libstd 使用的工具。在本节中，我们将限制 libstd 的使用，以进一步减小二进制文件大小。

如果您想要一个小于 20 千字节的可执行文件，必须移除 Rust 的字符串格式化代码 core::fmt。panic_immediate_abort 只移除了这些代码的一些用法。还有许多其他代码在某些情况下使用格式化。这包括 libstd 中的 Rust "预主函数" 代码。

通过使用 C 入口点（添加 #![no_main] 属性）、手动管理标准输入输出，并仔细分析您或您的依赖项包含的代码块，有时可以使用 libstd 同时避免臃肿的 core::fmt。

预期代码会变得不稳定和不可移植，会比平常使用更多的 unsafe{}。感觉像是 no_std，但带有 libstd。

从一个空的可执行文件开始，确保 xargo bloat --release --target=... 不包含 core::fmt 或有关填充的内容。添加（取消注释）一小部分。看看 xargo bloat 现在报告的内容是否大幅增加。检查您刚刚添加的源代码。可能使用了某个外部 crate 或新的 libstd 函数。递归地进行审查过程（需要使用 [replace] Cargo 依赖项，可能需要深入 libstd），找出为什么它比应有的重量更大。选择替代方法或修补依赖项以避免不必要的功能。取消注释更多代码，使用 xargo bloat 调试膨胀的大小，依此类推。

在 macOS 上，最终剥离后的二进制文件减小到 8KB。

通过 #![no_std] 移除 libstd

[!注意] 示例项目位于 no_std 文件夹中。

到目前为止，我们的应用程序一直在使用 Rust 标准库 libstd。libstd 提供了许多方便、经过良好测试的跨平台 API 和数据类型。但如果用户想要将二进制文件大小减小到等同于 C 程序的大小，可以选择只依赖 libc。

重要的是要理解这种方法有许多缺点。首先，您可能需要编写大量 unsafe 代码，并失去对大多数依赖 libstd 的 Rust crate 的访问权限。尽管如此，这仍是减小二进制文件大小的一个（尽管是极端的）选择。 以这种方式构建的经过 strip 处理的二进制文件大约为 8KB。

#![no_std]
#![no_main]

extern crate libc;

#[no_mangle]
pub extern "C" fn main(_argc: isize, _argv: *const *const u8) -> isize {
    // 由于我们传递的是 C 字符串，最后的空字符是必需的。
    const HELLO: &'static str = "Hello, world!\n\0";
    unsafe {
        libc::printf(HELLO.as_ptr() as *const _);
    }
    0
}

#[panic_handler]
fn my_panic(_info: &core::panic::PanicInfo) -> ! {
    loop {}
}

压缩二进制文件

[!注意] 到目前为止，所有减小大小的技术都是 Rust 特有的。本节描述了一种与语言无关的二进制打包工具，它是进一步减小二进制大小的一个选择。

UPX 是一个强大的工具，用于创建自包含的、压缩的二进制文件，无需额外的运行时要求。它声称通常可以将二进制大小减少 50-70%，但实际结果取决于你的可执行文件。

$ upx --best --lzma target/release/min-sized-rust

[!警告] 有时 UPX 打包的二进制文件会触发基于启发式的杀毒软件，因为恶意软件经常使用 UPX。

工具

• cargo-bloat - 查找可执行文件中占用最多空间的内容。
• cargo-unused-features - 查找并删除项目中已启用但可能未使用的特性标志。
• momo - proc_macro crate，帮助控制泛型方法的代码占用。
• Twiggy - Wasm 的代码大小分析器。

容器

有时将 Rust 部署到容器（例如 Docker）中是有优势的。有几个很好的现有资源可以帮助创建运行 Rust 二进制文件的最小尺寸容器镜像。

• 官方 rust:alpine 镜像
• mini-docker-rust
• muslrust
• docker-slim - 缩小 Docker 镜像
• dive - 一个用于探索容器镜像并发现缩小镜像大小方法的工具。

参考文献

• 151 字节静态 Linux 二进制文件 Rust 实现 - 2015
• 为什么 Rust 可执行文件很大？ - 2016
• Tiny Rocket - 2018
• 格式化对嵌入式 Rust 来说代价过高 - 2019
• Rust 中的微小 Windows 可执行文件 - 2019
• 制作非常小的 WebAssembly 图形演示 - 2019
• 减小 Rust GStreamer 插件的大小 - 2020
• 优化 Rust 二进制大小 - 2020
• 最小化 Mender-Rust - 2020
• 使用 cargo 和 Semver 优化 Rust 二进制大小 - 2021
• 收紧 Rust 的腰带：缩小嵌入式 Rust 二进制文件 - 2022
• 在 Rust 中避免分配以缩小 Wasm 模块 - 2022
• 一个非常小的 Rust 二进制文件 - 2022
• 内联和单态化的阴暗面 - 2023
• 默认情况下使 Rust 二进制文件更小 - 2024
• Tock 二进制大小 - 2024
• min-sized-rust-windows - Windows 特定的减小二进制大小的技巧
• 缩小 .wasm 代码大小

组织

• wg-binary-size: 致力于改进 Rust 程序和库大小的工作组。