Shrinking .wasm Code Size

This section will teach you how to optimize your .wasm build for a small codesize footprint, and how to identify opportunities to change your Rust sourcesuch that less .wasm code is emitted.

Why Care About Code Size?

When serving a .wasm file over the network, the smaller it is, the faster theclient can download it. Faster .wasm downloads lead to faster page load times,and that leads to happier users.

However, it's important to remember though that code size likely isn't theend-all-be-all metric you're interested in, but rather something much more vagueand hard to measure like "time to first interaction". While code size plays alarge factor in this measurement (can't do anything if you don't even have allthe code yet!) it's not the only factor.

WebAssembly is typically served to users gzip'd so you'll want to be sure tocompare differences in gzip'd size for transfer times over the wire. Also keepin mind that the WebAssembly binary format is quite amenable to gzipcompression, often getting over 50% reductions in size.

Furthermore, WebAssembly's binary format is optimized for very fast parsing andprocessing. Browsers nowadays have "baseline compilers" which parses WebAssemblyand emits compiled code as fast as wasm can come in over the network. This meansthat if you're using instantiateStreaming the second the Web requestis done the WebAssembly module is probably ready to go. JavaScript, on the otherhand, can often take longer to not only parse but also get up to speed with JITcompilation and such.

And finally, remember that WebAssembly is also far more optimized thanJavaScript for execution speed. You'll want to be sure to measure for runtimecomparisons between JavaScript and WebAssembly to factor that in to howimportant code size is.

All this to say basically don't dismay immediately if your .wasm file islarger than expected! Code size may end up only being one of many factors in theend-to-end story. Comparisons between JavaScript and WebAssembly that only lookat code size are missing the forest for the trees.

Optimizing Builds for Code Size

There are a bunch of configuration options we can use to get rustc to makesmaller .wasm binaries. In some cases, we are trading longer compile times forsmaller .wasm sizes. In other cases, we are trading runtime speed of theWebAssembly for smaller code size. We should be cognizant of the trade offs ofeach option, and in the cases where we trade runtime speed for code size,profile and measure to make an informed decision about whether the trade isworth it.

Compiling with Link Time Optimizations (LTO)

In Cargo.toml, add lto = true in the [profile.release] section:

  1. [profile.release]
  2. lto = true

This gives LLVM many more opportunities to inline and prune functions. Not onlywill it make the .wasm smaller, but it will also make it faster at runtime!The downside is that compilation will take longer.

Tell LLVM to Optimize for Size Instead of Speed

LLVM's optimization passes are tuned to improve speed, not size, by default. Wecan change the goal to code size by modifying the [profile.release] section inCargo.toml to this:

  1. [profile.release]
  2. opt-level = 's'

Or, to even more aggressively optimize for size, at further potential speedcosts:

  1. [profile.release]
  2. opt-level = 'z'

Note that, surprisingly enough, opt-level = "s" can sometimes result insmaller binaries than opt-level = "z". Always measure!

Use the wasm-opt Tool

The Binaryen toolkit is a collection of WebAssembly-specific compilertools. It goes much further than LLVM's WebAssembly backend does, and using itswasm-opt tool to post-process a .wasm binary generated by LLVM can often getanother 15-20% savings on code size. It will often produce runtime speed ups atthe same time!

  1. # Optimize for size.
  2. wasm-opt -Os -o output.wasm input.wasm
  4. # Optimize aggressively for size.
  5. wasm-opt -Oz -o output.wasm input.wasm
  7. # Optimize for speed.
  8. wasm-opt -O -o output.wasm input.wasm
  10. # Optimize aggressively for speed.
  11. wasm-opt -O3 -o output.wasm input.wasm

Notes about Debug Information

One of the biggest contributors to wasm binary size can be debug information andthe names section of the wasm binary. The wasm-pack tool, however, removesdebuginfo by default. Additionally wasm-opt removes the names section bydefault unless -g is also specified.

This means that if you follow the above steps you should by default not haveeither debuginfo or the names section in the wasm binary. If, however, you aremanually otherwise preserving this debug information in the wasm binary be sureto be mindful of this!

Size Profiling

If tweaking build configurations to optimize for code size isn't resulting in asmall enough .wasm binary, it is time to do some profiling to see where theremaining code size is coming from.

⚡ Just like how we let time profiling guide our speed up efforts, we want to let size profiling guide our code size shrinking efforts. Fail to do this and you risk wasting your own time!

The twiggy Code Size Profiler

twiggy is a code size profiler that supports WebAssembly asinput. It analyzes a binary's call graph to answer questions like:

  • Why was this function included in the binary in the first place?

  • What is the retained size of this function? I.e. how much space would besaved if I removed it and all the functions that become dead code after itsremoval?

  1. $ twiggy top -n 20 pkg/wasm_game_of_life_bg.wasm
  2.  Shallow Bytes │ Shallow % │ Item
  3. ───────────────┼───────────┼────────────────────────────────────────────────────────────────────────────────────────
  4.           9158 ┊    19.65% ┊ "function names" subsection
  5.           3251 ┊     6.98% ┊ dlmalloc::dlmalloc::Dlmalloc::malloc::h632d10c184fef6e8
  6.           2510 ┊     5.39% ┊ <str as core::fmt::Debug>::fmt::he0d87479d1c208ea
  7.           1737 ┊     3.73% ┊ data[0]
  8.           1574 ┊     3.38% ┊ data[3]
  9.           1524 ┊     3.27% ┊ core::fmt::Formatter::pad::h6825605b326ea2c5
  10.           1413 ┊     3.03% ┊ std::panicking::rust_panic_with_hook::h1d3660f2e339513d
  11.           1200 ┊     2.57% ┊ core::fmt::Formatter::pad_integral::h06996c5859a57ced
  12.           1131 ┊     2.43% ┊ core::str::slice_error_fail::h6da90c14857ae01b
  13.           1051 ┊     2.26% ┊ core::fmt::write::h03ff8c7a2f3a9605
  14.            931 ┊     2.00% ┊ data[4]
  15.            864 ┊     1.85% ┊ dlmalloc::dlmalloc::Dlmalloc::free::h27b781e3b06bdb05
  16.            841 ┊     1.80% ┊ <char as core::fmt::Debug>::fmt::h07742d9f4a8c56f2
  17.            813 ┊     1.74% ┊ __rust_realloc
  18.            708 ┊     1.52% ┊ core::slice::memchr::memchr::h6243a1b2885fdb85
  19.            678 ┊     1.45% ┊ <core::fmt::builders::PadAdapter<'a> as core::fmt::Write>::write_str::h96b72fb7457d3062
  20.            631 ┊     1.35% ┊ universe_tick
  21.            631 ┊     1.35% ┊ dlmalloc::dlmalloc::Dlmalloc::dispose_chunk::hae6c5c8634e575b8
  22.            514 ┊     1.10% ┊ std::panicking::default_hook::{{closure}}::hfae0c204085471d5
  23.            503 ┊     1.08% ┊ <&'a T as core::fmt::Debug>::fmt::hba207e4f7abaece6

Manually Inspecting LLVM-IR

LLVM-IR is the final intermediate representation in the compiler toolchainbefore LLVM generates WebAssembly. Therefore, it is very similar to theWebAssembly that is ultimately emitted. More LLVM-IR generally means more.wasm size, and if a function takes up 25% of the LLVM-IR, then it generallywill take up 25% of the .wasm. While these numbers only hold in general, theLLVM-IR has crucial information that is not present in the .wasm (because ofWebAssembly's lack of a debugging format like DWARF): which subroutines wereinlined into a given function.

You can generate LLVM-IR with this cargo command:

  1. cargo rustc --release -- --emit llvm-ir

Then, you can use find to locate the .ll file containing the LLVM-IR incargo's target directory:

  1. find target/release -type f -name '*.ll'

References

More Invasive Tools and Techniques

Tweaking build configurations to get smaller .wasm binaries is pretty handsoff. When you need to go the extra mile, however, you are prepared to use moreinvasive techniques, like rewriting source code to avoid bloat. What follows isa collection of get-your-hands-dirty techniques you can apply to get smallercode sizes.

Avoid String Formatting

format!, to_string, etc… can bring in a lot of code bloat. If possible,only do string formatting in debug mode, and in release mode use static strings.

Avoid Panicking

This is definitely easier said than done, but tools like twiggy and manuallyinspecting LLVM-IR can help you figure out which functions are panicking.

Panics do not always appear as a panic!() macro invocation. They ariseimplicitly from many constructs, such as:

  • Indexing a slice panics on out of bounds indices: my_slice[i]

  • Division will panic if the divisor is zero: dividend / divisor

  • Unwrapping an Option or Result: opt.unwrap() or res.unwrap()

The first two can be translated into the third. Indexing can be replaced withfallible my_slice.get(i) operations. Division can be replaced withchecked_div calls. Now we only have a single case to contend with.

Unwrapping an Option or Result without panicking comes in two flavors: safeand unsafe.

The safe approach is to abort instead of panicking when encountering a Noneor an Error:

  2. # #![allow(unused_variables)]
  3. #fn main() {
  4. #[inline]
  5. pub fn unwrap_abort<T>(o: Option<T>) -> T {
  6.     use std::process;
  7.     match o {
  8.         Some(t) => t,
  9.         None => process::abort(),
  10.     }
  11. }
  12. #}

Ultimately, panics translate into aborts in wasm32-unknown-unknown anyways, sothis gives you the same behavior but without the code bloat.

Alternatively, the unreachable crate provides an unsafeunchecked_unwrap extension method for Option andResult which tells the Rust compiler to assume that the Option is Someor the Result is Ok. It is undefined behavior what happens if thatassumption does not hold. You really only want to use this unsafe approach whenyou 110% know that the assumption holds, and the compiler just isn't smartenough to see it. Even if you go down this route, you should have a debug buildconfiguration that still does the checking, and only use unchecked operations inrelease builds.

Avoid Allocation or Switch to wee_alloc

Rust's default allocator for WebAssembly is a port of dlmalloc to Rust. Itweighs in somewhere around ten kilobytes. If you can completely avoid dynamicallocation, then you should be able to shed those ten kilobytes.

Completely avoiding dynamic allocation can be very difficult. But removingallocation from hot code paths is usually much easier (and usually helps makethose hot code paths faster, as well). In these cases, replacing the defaultglobal allocator with wee_alloc should save you most (but notquite all) of those ten kilobytes. weealloc is an allocator designed forsituations where you need _some kind of allocator, but do not need aparticularly fast allocator, and will happily trade allocation speed for smallercode size.

Use Trait Objects Instead of Generic Type Parameters

When you create generic functions that use type parameters, like this:

  2. # #![allow(unused_variables)]
  3. #fn main() {
  4. fn whatever<T: MyTrait>(t: T) { ... }
  5. #}

Then rustc and LLVM will create a new copy of the function for each T typethat the function is used with. This presents many opportunities for compileroptimizations based on which particular T each copy is working with, but thesecopies add up quickly in terms of code size.

If you use trait objects instead of type parameters, like this:

  2. # #![allow(unused_variables)]
  3. #fn main() {
  4. fn whatever(t: Box<MyTrait>) { ... }
  5. // or
  6. fn whatever(t: &MyTrait) { ... }
  7. // etc...
  8. #}

Then dynamic dispatch via virtual calls is used, and only a single version ofthe function is emitted in the .wasm. The downside is the loss of the compileroptimization opportunities and the added cost of indirect, dynamicallydispatched function calls.

Use the wasm-snip Tool

wasm-snip replaces a WebAssembly function's body with an unreachableinstruction. This is a rather heavy, blunt hammer for functions that kindof look like nails if you squint hard enough.

Maybe you know that some function will never be called at runtime, but thecompiler can't prove that at compile time? Snip it! Afterwards, run wasm-optagain with the —dce flag, and all the functions that the snipped functiontransitively called (which could also never be called at runtime) will getremoved too.

This tool is particularly useful for removing the panicking infrastructure,since panics ultimately translate into traps anyways.