README_WASI.md

Building and running Basis Universal under WASI / Wasmtime

This document describes how to build the basisu command-line tool as a WASI (WebAssembly System Interface) executable, and how to run it using Wasmtime.
WASI builds run the encoder inside a secure, portable WebAssembly sandbox with no native dependencies.

1. Install Wasmtime

Install Wasmtime using the official installer:

curl https://wasmtime.dev/install.sh | bash

Verify:

wasmtime --version

2. Install WASI-SDK (WASI toolchain)

Download the latest WASI SDK from:

https://github.com/WebAssembly/wasi-sdk/releases/latest https://github.com/WebAssembly/wasi-sdk/releases

Example (adjust version if needed):

wget https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-29/wasi-sdk-29.0-x86_64-linux.tar.gz
tar xf wasi-sdk-29.0-x86_64-linux.tar.gz

3. Set the WASI_SDK_PATH environment variable

You must set the path so CMake can find the WASI compiler:

export WASI_SDK_PATH=/path/to/wasi-sdk-29.0-x86_64-linux

Example:

export WASI_SDK_PATH=$HOME/wasi-sdk-29.0-x86_64-linux

Verify:

$WASI_SDK_PATH/bin/clang --version

4. Configure the WASI build using CMake

WASI builds come in two modes:

  • Single-threaded (default)
  • Multi-threaded (requires wasi-sdk-pthread.cmake and Wasmtime threading flags)

Create a fresh build directory and configure using the WASI toolchain file:

mkdir build
cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=$WASI_SDK_PATH/share/cmake/wasi-sdk-pthread.cmake -DCMAKE_BUILD_TYPE=Release -DBASISU_WASM_THREADING=ON

Or for a single threaded build (will run much slower):

cmake .. -DCMAKE_TOOLCHAIN_FILE=$WASI_SDK_PATH/share/cmake/wasi-sdk.cmake -DCMAKE_BUILD_TYPE=Release -DBASISU_WASM_THREADING=OFF

5. Build the WASI .wasm executable

Build using:

make

This produces:

bin/basisu.wasm
bin/examples.wasm    (if EXAMPLES=ON)

6. Running basisu.wasm with Wasmtime

WASI programs are sandboxed and cannot access your filesystem unless you explicitly grant permission.

Use one or more --dir= arguments to allow input/output files.

Run internal test suite for ETC1S

bin$ wasmtime run --wasm threads=yes --wasi threads=yes --dir=. --dir=.. --dir=../test_files basisu.wasm -test

Use backslashes under Windows: “wasmtime run --wasm threads=yes --wasi threads=yes --dir=. --dir=.. --dir=..\test_files basisu.wasm -test”

For the single threaded wasm executables, “--wasm threads=yes --wasi threads=yes” isn't needed.

A Windows .cmd batch script example:

wasmtime --dir=. --dir=.. --dir=..\test_files --dir=d:/dev/test_images::/test_images --dir=d:/dev/test_images/bik::/bik basisu.wasm %*

A shell script example:

#!/usr/bin/env bash
wasmtime run --dir=. --dir=../test_files --dir=/mnt/d/dev/test_images::/test_images --dir=/mnt/d/dev/test_images/bik::/test_images/bik --wasm threads=yes --wasi threads=yes ./basisu.wasm "$@"

Example: run compression on a PNG to ETC1S

wasmtime run --wasm threads=yes --wasi threads=yes --dir=. basisu.wasm xmen.png -stats

Example: transcode a KTX2 file to .ktx/.png/etc.

wasmtime run --wasm threads=yes --wasi threads=yes --dir=. basisu.wasm xmen.ktx2

Notes

  • WASI builds run inside a secure sandbox with no filesystem access unless explicitly granted via --dir=.
  • The CMake configuration sets a larger stack size to support ASTC/UASTC compression.
  • WASI SDK and Wasmtime can be installed anywhere; just update WASI_SDK_PATH.

Summary

To build and run BasisU under WASI:

  1. Install Wasmtime
  2. Install WASI SDK
  3. Set WASI_SDK_PATH
  4. Run cmake using the WASI toolchain in “build” directory
  5. Build with make
  6. Run using wasmtime with --dir= permissions on .wasm executables in “bin” directory

This produces a safe, portable, sandboxed version of the Basis Universal encoder that runs anywhere.