Rust bindings for Binaryen's wasm-opt

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

lib.rs:

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:

1. makes its command-line interface installable via cargo install,
2. 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.

Using the library

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.

Enabling and disabling WASM features

The WebAssembly specification has optional features, represeted by the Feature enum. The Feature variants link to the relevant specifications of each feature when known. wasm-opt can be configured with support for them individually using the OptimizationOptions::enable_feature and OptimizationOptions::disable_feature methods.

By default Binaryen (and this crate) enables these common features by default:

• Feature::SignExt
• Feature::MutableGlobals.

The original WebAssembly specification with no additional features is known as the MVP specification. To enable only the MVP features call OptimizationOptions::mvp_features_only.

After resetting to MVP features, additional calls to enable_feature will add features to the MVP feature set.

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.

Cargo features

Enabled by default, the dwarf feature enables passes related to DWARF debug info. When enabled, this crate includes C++ code from the LLVM project. This can cause duplicate symbol linkage errors when also linking to LLVM. When disabled, this code is not built, so can link successfully to LLVM, but the Binaryen DWARF passes will do nothing.