Crate wasm_opt

Expand description

Rust bindings to the wasm-opt WebAssembly optimizer.

wasm-opt is a component of the Binaryen toolkit that optimizes WebAssembly modules. It is written in C++.

This project provides a Rust crate that builds wasm-opt and:

makes its command-line interface installable via cargo install,
provides an API to access it programmatically.

Installing the binary

cargo install wasm-opt --locked

It should behave exactly the same as wasm-opt installed from other sources.

The crate provides an OptimizationOptions type that follows the builder pattern, with options that closely mirror the command line options of wasm-opt. Once built, call OptimizationOptions::run to load, optimize, and write the optimized module.

use wasm_opt::OptimizationOptions;

let infile = "hello_world.wasm";
let outfile = "hello_world_optimized.wasm";

OptimizationOptions::new_optimize_for_size()
    .run(infile, outfile)?;

There are constructors for all the typical optimization profiles:

OptimizationOptions::new_optimize_for_size · -Os or -O
OptimizationOptions::new_optimize_for_size_aggressively · -Oz
OptimizationOptions::new_opt_level_0 · -O0, or no -O* argument.
OptimizationOptions::new_opt_level_1 · -O1
OptimizationOptions::new_opt_level_2 · -O2
OptimizationOptions::new_opt_level_3 · -O3
OptimizationOptions::new_opt_level_4 · -O4

By default, the run method will read either binary wasm or text wat files, inspecting the first few bytes for the binary header and choosing as appropriate, and it will write a binary wasm file. This behavior can be changed with OptimizationOptions::reader_file_type and OptimizationOptions::writer_file_type.

Customizing passes

All Binaryen optimization passes are represented in the Pass enum, and can be added to OptimizationOptions via OptimizationOptions::add_pass. These are added after the default set of passes, which are enabled by most OptimizationOptions constructors. The default passes can be disabled either with the OptimizationOptions::new_opt_level_0 constructor, or by calling OptimizationOptions::add_default_passes with a false argument.

use wasm_opt::{OptimizationOptions, Pass};

let infile = "hello_world.wasm";
let outfile = "hello_world_optimized.wasm";

// Just run the inliner.
OptimizationOptions::new_opt_level_0()
    .add_pass(Pass::InliningOptimizing)
    .run(infile, outfile)?;

Note that while this crate exposes all Binaryen passes some may not make sense to actually use — Binaryen is a command-line oriented tool, and some passes are for debug purposes or print directly to the console.

Integrating with existing tooling

For ease of integration with tools that already use wasm-opt via CLI, this crate provides the integration module, which presents an API that is compatible with stds Command. This allows client code to use mostly the same code path for executing the wasm-opt CLI, and the crate-based API.