securityos/node_modules/@wasmer/wasm-transformer/lib/wasm-pack/node/README.md

wasm_transformer

Library to run transformations on WebAssembly binaries. 🦀♻️

This README covers the instructions for installing, using, and contributing to the wasm_transformer rust crate. The wasm-transformer Javascript package is available here.

Table of Contents

• Features
• Installation
• Quick Start
• Reference API
• Contributing
  • Guidelines
  • Building the project

Features

This project depends on wasmparser, and the wasm-pack workflow. Huge shoutout to them! 🙏

• Runs transformations on Wasm binaries to modify the actual code that gets run, and introduces new features (such as introducing trampoline functions for i64 WASI imports). ✨

• Installable on both crates.io, and npm! 📦

• The project builds with wasm-pack. Thus, you can use this library in a Javascript library, to modify WebAssembly Binaries, with WebAssembly. 🤯

• Super fast! Can run the lower_i64_imports transformations on my 2018 MackBook Pro, with the Chrome Devtools 6x CPU slowdown in ~ 1 second. ⚡

Installation

# Cargo.toml
[dependencies]
wasm_transformer = "LATEST_VERSION_HERE"

Quick Start

For a larger example, see the simple wasm_transformer_cli.

use wasm_transformer::*;

// Some Code here

// Read in a Wasm file as a Vec<u8>
let mut Wasm = fs::read(wasm_file_path).unwrap();
// Add trampoline functions to lower the i64 imports in the Wasm file
let lowered_wasm = wasm_transformer::lower_i64_imports(wasm);
// Write back out the new Wasm file
fs::write("./out.wasm", &lowered_wasm).expect("Unable to write file");

Reference API

version()

Returns the version of the crate/package

---

lower_i64_imports(mut wasm_binary: Vec<u8>) -> Vec<u8>

Inserts trampoline functions for imports that have i64 params or returns. This is useful for running Wasm modules in browsers that do not support JavaScript BigInt -> Wasm i64 integration. Especially in the case for i64 WASI Imports.

Contributing

Guidelines

This project follows the all-contributors specification.

Contributions of any kind are welcome! 👍

Building the project

To get started using the project:

• Install the latest Nightly version of Rust (which includes cargo).

• Install the latest version of wasm-pack.

• To test and build the project, run the wasm_transformer_build.sh script. Or, feel free to look through the script to see the documented commands for performing their respective actions individually. The script performs:

  • Running Clippy

  • Running tests

  • Building the project, moving output into the correct directories in the javascript package.