1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
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.
|
