wasm-tools

wit-dylib is a tool (available as a wasm-tools subcommand) that generates a WebAssembly shared-everything dynamic library from a WIT (WebAssembly Interface Type) world.

It works by translating any possible WIT interface through a single C header file, wit_dylib.h. This allows for creating components that are suitable for both implementing and using a WIT interface.

Primary Use Case: Componentizing Interpreted Languages It is designed to decouple an interpreter from the target WIT world. This provides several benefits:

• Independence: The interpreter is independent of the user's chosen WIT world.
• Pre-built Interpreters: Users can use pre-built interpreter binaries to create components for any WIT world without building custom interpreters.
• Code Sharing: Engines can share code between components using the same interpreter binary.
• Dynamic API Access: Interpreters can provide access to WIT worlds that were not known at the time the interpreter was compiled.

A predicate script defines whether a WebAssembly file is "interesting" (e.g., it triggers a specific bug).

Requirements:

• The script is given the Wasm file as its first and only argument.
• The script must exit with a zero status code if the Wasm file is interesting.
• The script must exit with a non-zero status code if the Wasm file is not interesting.
• The script must not depend on the current working directory.
• The script must be safe to run in parallel (it must not assume only one instance is running at a time).

Example script to detect a specific panic message in wasmtime using grep --quiet:

#!/usr/bin/env bash

# Exit the script if any subcommand fails.
set -e

# The Wasm file is given as the first and only argument to the script.
WASM=$1

# Run the Wasm in Wasmtime and `grep` for our target bug's panic
# message.
wasmtime run $WASM 2>&1 | grep --quiet 'assertion failed: invalid stack map'

WAVE (Web Assembly Value Encoding) defines a grammar for representing values. A value can be any of the following types:

• number: Finite numbers, nan, inf, or -inf.
• char: A single character enclosed in single quotes (e.g., 'a').
• string: A double-quoted string or a triple-quoted multiline-string.
• variant-case: A labeled value, often used for Bool, Variant, Enum, Option, and Result types. It follows the pattern label (payload).
• tuple: A sequence of values enclosed in parentheses: (val1, val2).
• list: A sequence of values enclosed in square brackets: [val1, val2].
• flags: A set of labels enclosed in curly braces: {label1, label2}.
• record: A collection of key-value pairs enclosed in curly braces: {label: value}.

Note that variant-case, Bool, Variant, Enum, Option, and Result are grouped under variant-case because they require type information to be distinguished. Many applications allow whitespace (value-ws) around these values, including comments starting with //.

value ::= number
        | char
        | string
        | variant-case
        | tuple
        | list
        | flags
        | record

The wasm-tools repository uses a specific versioning scheme to indicate API stability across its CLI and various Rust crates. Understanding this helps you manage dependencies and upgrades:

• wasm-tools (CLI): Follows 1.X.Y. The X version is bumped during major repository releases.
• wat (Rust crate): Follows 1.X.Y and matches the wasm-tools CLI version, indicating high API stability.
• wast (Rust crate): Follows X.0.Y, where X matches the X in the wasm-tools version.
• All other crates: Follow 0.X.Y, where X matches the X in the wasm-tools version. These crates receive major version bumps that are not automatically considered API compatible, reflecting the evolving nature of the WebAssembly standard.

Note that the Y component (patch version) is synchronized across all these components for any given release. While all crates are suitable for production use, API stability is not guaranteed for the non-wat crates.