wasm-tools

A Bytecode Alliance project

CLI and Rust libraries for low-level manipulation of WebAssembly modules

Installation

Precompiled artifacts built on CI are available for download for each release.

If you'd prefer to build from source then first install Rust for your platform and then use the included Cargo package manager to install:

$ cargo install wasm-tools

Installation can be confirmed with:

$ wasm-tools --version

Subcommands can be explored with:

$ wasm-tools help

Examples

Basic validation/printing:

# Validate a WebAssembly file
$ wasm-tools validate foo.wasm

# Validate a WebAssembly module in the text format, automatically converting to
# binary.
$ wasm-tools validate foo.wat

# Validate a WebAssembly file enabling an off-by-default feature
$ wasm-tools validate foo.wasm --features=exception-handling

# Validate a WebAssembly file with a default-enabled feature disabled
$ wasm-tools validate foo.wasm --features=-simd

# Print the text format of a module to stdout
$ wasm-tools print foo.wasm

# Convert a binary module to text
$ wasm-tools print foo.wasm -o foo.wat

Simple mutation as well as piping commands together:

# Mutate a WebAssembly module and print its text representation to stdout
$ wasm-tools mutate foo.wasm -t

# Mutate a WebAssembly module with a non-default seed and validate that the
# output is a valid module.
$ wasm-tools mutate foo.wasm --seed 192 | wasm-tools validate

# Demangle Rust/C++ symbol names in the `name` section, strip all other custom
# sections, and then print out what binary sections remain.
$ wasm-tools demangle foo.wasm | wasm-tools strip | wasm-tools objdump

Working with components:

# Print the WIT interface of a component
$ wasm-tools component wit component.wasm

# Convert WIT text files to a binary-encoded WIT package, printing the result to
# stdout
$ wasm-tools component wit ./wit -t

# Convert a WIT document to JSON
$ wasm-tools component wit ./wit --json

# Round trip WIT through the binary-encoded format to stdout.
$ wasm-tools component wit ./wit --wasm | wasm-tools component wit

# Convert a core WebAssembly binary into a component. Note that this requires
# WIT metadata having previously been embedded in the core wasm module.
$ wasm-tools component new my-core.wasm -o my-component.wasm

# Convert a core WebAssembly binary which uses WASI to a component.
$ wasm-tools component new my-core.wasm -o my-component.wasm --adapt wasi_snapshot_preview1.reactor.wasm

CLI Conventions

There are a few conventions that all CLI commands adhere to:

• All subcommands print "short help" with -h and "long help" with --help.
• Input is by default read from stdin if no file input is specified (when applicable).
• Output is by default sent to stdout if a -o or --output flag is not provided. Binary WebAssembly is not printed to a tty by default, however.
• Commands which output WebAssembly binaries all support a -t or --wat flag to generate the WebAssembly text format instead.
• A -v or --verbose flag can be passed to enable log messages throughout the tooling. Verbosity can be turned up by passing the flag multiple times such as -vvv.
• Color in error messages and console output is enabled by default for TTY based outputs and can be configured with a --color argument.

Tools included

The wasm-tools binary internally contains a number of subcommands for working with wasm modules and component. Many subcommands also come with Rust crates that can be use programmatically as well:

CLI	Rust Crate	Description
wasm-tools validate	wasmparser	Validate a WebAssembly file
wasm-tools parse	wat and wast	Translate the WebAssembly text format to binary
wasm-tools print	wasmprinter	Translate the WebAssembly binary format to text
wasm-tools smith	wasm-smith	Generate a valid WebAssembly module from an input seed
wasm-tools mutate	wasm-mutate	Mutate an input wasm file into a new valid wasm file
wasm-tools shrink	wasm-shrink	Shrink a wasm file while preserving a predicate
wasm-tools dump		Print debugging information about the binary format
wasm-tools objdump		Print debugging information about section headers
wasm-tools strip		Remove custom sections from a WebAssembly file
wasm-tools demangle		Demangle Rust and C++ symbol names in the name section
wasm-tools compose	wasm-compose	Compose wasm components together
wasm-tools component new	wit-component	Create a component from a core wasm binary
wasm-tools component wit		Extract a *.wit interface from a component
wasm-tools component embed		Embed a component-type custom section in a core wasm binary
wasm-tools metadata show	wasm-metadata	Show name and producer metadata in a component or module
wasm-tools metadata add		Add name or producer metadata to a component or module
wasm-tools addr2line		Translate wasm offsets to filename/line numbers with DWARF
wasm-tools completion		Generate shell completion scripts for wasm-tools

The wasm-tools CLI contains useful tools for debugging WebAssembly modules and components. The various subcommands all have --help explainer texts to describe more about their functionality as well.

Libraries

As mentioned above many of the tools of the wasm-tools CLI have libraries implemented in this repository as well. These libraries are:

• wasmparser - a library to parse WebAssembly binaries
• wat - a library to parse the WebAssembly text format
• wast - like wat, except provides an AST
• wasmprinter - prints WebAssembly binaries in their string form
• wasm-mutate - a WebAssembly test case mutator
• wasm-shrink - a WebAssembly test case shrinker
• wasm-smith - a WebAssembly test case generator
• wasm-encoder - a crate to generate a binary WebAssembly module
• wit-parser - a crate to parse and manage *.wit files and interfaces.
• wit-component - a crate to create components from core wasm modules.
• wasm-metadata - a crate to manipulate name and producer metadata (custom sections) in a wasm module or component.

It's recommended to use the libraries directly rather than the CLI tooling when embedding into a separate project.

C/C++ bindings

Using the CMakeLists.txt in crates/c-api, wasm-tools can be used from the wasm-tools.h header. Note that these bindings do not comprehensively cover all the functionality of this repository at this time, but please feel free to contribute more if you find functions useful!

Contributing

See CONTRIBUTING.md for more information about contributing to this repository.

License

This project is licensed under the Apache 2.0 license with the LLVM exception. See LICENSE for more details.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.