Optimizing Wasm Binary Size

In this lesson, you will learn how to aggressively strip your Wasm binaries by controlling link-time code generation and manual dead-code elimination.

When targeting specialized Wasm runtimes, the default Rust compilation settings often include debug symbols, panic formatting strings, and unused standard library features that bloat the .wasm file. To achieve a minimal binary, we must move beyond standard optimization flags like -C opt-level=z and manipulate the linker's behavior.

Link-Time Code Generation

The linker performs a critical role in "dead-code elimination" (DCE). If you have a massive library linked into your project but only call a single function, the linker typically removes everything else. However, Rust’s std library can sometimes pull in complex dependencies that are difficult for the linker to prune.

By using #[panic_handler] to define a custom, minimal panic routine, we can avoid linking in the heavy core::fmt infrastructure. When a panic occurs, we simply trap the execution:

#[panic_handler]
fn panic(_info: &core::panic::PanicInfo) -> ! {
    core::arch::wasm32::unreachable()
}

Manual Dead-Code Elimination

Even with lto = true enabled in your Cargo.toml, some items remain in the binary because the compiler perceives them as "reachable" via export tables. If you are targeting a runtime that only expects a specific set of functions, you can explicitly hide everything else using the cdylib crate type and managing your symbols:

1. lto = "fat": Ensures the linker sees the entire program as one unit, maximizing the effectiveness of dead-code removal across crate boundaries.
2. panic = "abort": Removes the landing pad code required for stack unwinding, which significantly reduces binary size in Wasm, as exceptions aren't natively supported in the same way as native hardware.
3. codegen-units = 1: While slower to compile, this allows the compiler to perform global optimizations that aren't possible when code is partitioned.

By stripping symbols and disabling unwinding, you force the linker to treat your binary as a closed, minimal system where every byte must justify its existence.

Key Takeaway: Shrink your Wasm footprint by disabling unwinding, implementing a minimal panic handler, and enabling "fat" Link-Time Optimization to ensure the linker can effectively prune unreachable code paths.