From 21c71a32e27a87a5d67a50a6881494c9b6e99a4f Mon Sep 17 00:00:00 2001
From: Richard Geldreich <richgel99@protonmail.com>
Date: Mon, 19 Jan 2026 01:56:47 -0500
Subject: [PATCH] adding new file

---
 readme_wasi.md | 167 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 167 insertions(+)
 create mode 100644 readme_wasi.md

diff --git a/readme_wasi.md b/readme_wasi.md
new file mode 100644
index 0000000..270dc81
--- /dev/null
+++ b/readme_wasi.md
@@ -0,0 +1,167 @@
+# 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.
+