CLI for externref Crate

This crate provides command-line interface for externref. It allows transforming WASM modules that use externref shims to use real externref types.

Installation

Install with

cargo install --locked externref-cli
# This will install `externref` executable, which can be checked
# as follows:
externref --help

By default, tracing is enabled via the tracing crate feature. You can disable the feature manually by adding a --no-default-features arg to the installation command. Tracing is performed with the externref::* targets, mostly on the DEBUG and INFO levels. Tracing events are output to the stderr using the standard subscriber; its filtering can be configured using the RUST_LOG env variable (e.g., RUST_LOG=externref=debug).

Alternatively, you may use the app Docker image as described below, or download a pre-built app binary for popular targets (x86_64 for Linux / macOS / Windows and AArch64 for macOS) from GitHub Releases.

Minimum supported Rust version

The crate supports the latest stable Rust version. It may support previous stable Rust versions, but this is not guaranteed.

Usage

The executable provides the same functionality as the WASM processor from the externref crate. See its docs and the output of externref --help for a detailed description of available options.

Warning

The processor should run before WASM optimization tools such as wasm-opt from binaryen.

Using Docker image

As a lower-cost alternative to the local installation, you may install and use the CLI app from the GitHub Container registry. To run the app in a Docker container, use a command like

docker run -i --rm ghcr.io/slowli/externref:main - \
  < module.wasm \
  > processed-module.wasm

Here, - is the argument to the CLI app instructing to read the input module from the stdin. To output tracing information, set the RUST_LOG env variable in the container, e.g. using docker run --env RUST_LOG=debug ....

Examples

The terminal capture below demonstrates transforming a test WASM module. The capture includes the tracing output, which was switched on by setting the RUST_LOG env variable. Tracing info includes each transformed function and some other information that could be useful for debugging.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

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