Commit 921257f50 for llama.cpp
commit 921257f5000e82864d4166242f5e67b6475fd661
Author: Mendy Berger <12537668+MendyBerger@users.noreply.github.com>
Date: Mon Oct 19 19:09:55 2026 -0400
ci, docs: add WASI CI and docs (#30754)
* ci, docs: add WASI CI and docs
* accept review feedback
diff --git a/.github/workflows/build-wasi.yml b/.github/workflows/build-wasi.yml
new file mode 100644
index 000000000..c6dbd6666
--- /dev/null
+++ b/.github/workflows/build-wasi.yml
@@ -0,0 +1,142 @@
+name: CI (wasi)
+
+on:
+ workflow_dispatch: # allows manual triggering
+ push:
+ branches:
+ - master
+ paths: [
+ '.github/workflows/build-wasi.yml',
+ '**/CMakeLists.txt',
+ '**/.cmake',
+ '**/*.h',
+ '**/*.hpp',
+ '**/*.c',
+ '**/*.cpp',
+ '**/*.wgsl',
+ '**/*.tmpl',
+ 'ggml/src/ggml-webgpu/wgsl-shaders/embed_wgsl.py'
+ ]
+
+ pull_request:
+ types: [opened, synchronize, reopened]
+ paths: [
+ '.github/workflows/build-wasi.yml',
+ '**/CMakeLists.txt',
+ '**/.cmake',
+ '**/*.h',
+ '**/*.hpp',
+ '**/*.c',
+ '**/*.cpp',
+ '**/*.wgsl',
+ '**/*.tmpl',
+ 'ggml/src/ggml-webgpu/wgsl-shaders/embed_wgsl.py'
+ ]
+
+cache-mode: none
+permissions:
+ contents: read
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.head_ref && github.ref || github.run_id }}
+ cancel-in-progress: true
+
+env:
+ WASI_SDK_VERSION: 34
+ DAWN_VERSION: v20260908.214631
+ DAWN_COMMIT: 94c3c9cc0d5fb2e85aebb370fa8d37b71aa34655
+ WASI_WEBGPU_HEADERS_COMMIT: 917765edd7cb8f8cf95bda1217514c78f71b582b
+
+jobs:
+ ubuntu-webgpu:
+ runs-on: ubuntu-24.04-arm
+
+ steps:
+ - name: Clone
+ id: checkout
+ uses: actions/checkout@v6
+
+ - name: ccache
+ uses: ggml-org/ccache-action@v1.2.24
+ with:
+ restore: false
+ save: false
+
+ - name: Install wasi-sdk
+ uses: bytecodealliance/setup-wasi-sdk-action@77d09f3df1e8da344d8403cf8631af8977938b4c # v1.0.0
+ with:
+ version: ${{ env.WASI_SDK_VERSION }}
+ add-to-path: false
+
+ - name: wasi:webgpu Dependency
+ run: |
+ mkdir -p wasi-webgpu/dawn-headers
+ curl -fL "https://github.com/google/dawn/releases/download/${DAWN_VERSION}/dawn-headers-${DAWN_COMMIT}.tar.gz" |
+ tar -xz -C wasi-webgpu/dawn-headers --strip-components=1
+
+ git init -q wasi-webgpu/wasi-webgpu-headers
+ cd wasi-webgpu/wasi-webgpu-headers
+ git fetch -q --depth 1 https://github.com/wasi-gfx/wasi-webgpu-headers.git ${WASI_WEBGPU_HEADERS_COMMIT}
+ git checkout -q FETCH_HEAD
+ git submodule update -q --init --depth 1
+ cd ../..
+
+ # ggml-webgpu does find_package(Dawn) and links dawn::webgpu_dawn. There is no Dawn on WASI,
+ # so this target instead compiles wasi-webgpu-headers (webgpu.h over wasi:webgpu imports)
+ # and exposes Dawn's webgpu_cpp.h on top of it.
+ cat > wasi-webgpu/DawnConfig.cmake << 'EOF'
+ set(_wasi_webgpu "${CMAKE_CURRENT_LIST_DIR}/wasi-webgpu-headers")
+ add_library(dawn::webgpu_dawn INTERFACE IMPORTED)
+ set_target_properties(dawn::webgpu_dawn PROPERTIES
+ INTERFACE_SOURCES "${_wasi_webgpu}/webgpu.c;${_wasi_webgpu}/async_futures.c;${_wasi_webgpu}/imports.c;${_wasi_webgpu}/imports_component_type.o"
+ INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_LIST_DIR}/dawn-headers/include/webgpu_upstream;${_wasi_webgpu}")
+ EOF
+
+ - name: ccache-buckets-restore
+ uses: ./.github/actions/ccache-buckets
+ env:
+ HF_TOKEN: ${{ secrets.HF_TOKEN_CI }}
+ with:
+ key: webgpu-ubuntu-24.04-arm-wasi
+ folder: llama.cpp
+ hf_bucket: ggml-org/cache
+
+ # llama-common does not build for WASI, so the executables are linked by hand
+ - name: Build
+ id: cmake_build
+ run: |
+ WASI_FLAGS="-msimd128 -D_WASI_EMULATED_SIGNAL -fwasm-exceptions -mllvm -wasm-use-legacy-eh=false"
+ cmake -B build-wasi \
+ -G "Ninja" \
+ -DCMAKE_TOOLCHAIN_FILE=${WASI_SDK_PATH}/share/cmake/wasi-sdk-p3.cmake \
+ -DCMAKE_BUILD_TYPE=Release \
+ -DCMAKE_C_FLAGS="${WASI_FLAGS}" \
+ -DCMAKE_CXX_FLAGS="${WASI_FLAGS}" \
+ -DCMAKE_HAVE_LIBC_PTHREAD=1 \
+ -DBUILD_SHARED_LIBS=OFF \
+ -DGGML_NATIVE=OFF \
+ -DGGML_OPENMP=OFF \
+ -DGGML_WEBGPU=ON \
+ -DDawn_DIR=$PWD/wasi-webgpu \
+ -DLLAMA_BUILD_COMMON=OFF
+
+ time cmake --build build-wasi --config Release --target llama -j $(nproc)
+
+ LIBS="build-wasi/ggml/src/libggml.a build-wasi/ggml/src/ggml-webgpu/libggml-webgpu.a build-wasi/ggml/src/libggml-cpu.a build-wasi/ggml/src/libggml-base.a"
+ LDFLAGS="-lunwind -ldl -Wl,-z,stack-size=8388608"
+ CXX="${WASI_SDK_PATH}/bin/clang++ --target=wasm32-wasip3 -O3 -std=c++17 ${WASI_FLAGS} -I include -I ggml/include"
+
+ $CXX examples/simple/simple.cpp build-wasi/src/libllama.a $LIBS $LDFLAGS -o build-wasi/llama-simple.wasm
+ $CXX tests/test-backend-ops.cpp $LIBS $LDFLAGS -o build-wasi/test-backend-ops.wasm
+
+ - name: ccache-buckets-save
+ if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+ uses: ./.github/actions/ccache-buckets
+ env:
+ HF_TOKEN: ${{ secrets.HF_TOKEN_CACHE_OUTPUT }}
+ with:
+ key: webgpu-ubuntu-24.04-arm-wasi
+ folder: llama.cpp
+ evict-old-files: 1d
+ hf_bucket: ggml-org/cache
+ save: true
diff --git a/docs/build.md b/docs/build.md
index 7286ec58d..42c726127 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -852,6 +852,36 @@ WebGPU allows cross-platform access to the GPU from supported browsers. We utili
Follow the instructions [here](https://dawn.googlesource.com/dawn/+/refs/heads/main/src/emdawnwebgpu/) to download or build the emdawnwebgpu package (Note that it might be safer to build the emdawnwebgpu package locally, so that it stays in sync with the version of Dawn you have installed above). When building using CMake, the path to the emdawnwebgpu port file needs to be set with the flag `EMDAWNWEBGPU_DIR`.
+## WASI
+
+Requires [wasi-sdk](https://github.com/WebAssembly/wasi-sdk) 34+ with `WASI_SDK_PATH` set. Only the libraries build (`llama-common` does not support WASI yet), so link your program against them:
+
+```bash
+FLAGS="-msimd128 -D_WASI_EMULATED_SIGNAL -fwasm-exceptions -mllvm -wasm-use-legacy-eh=false"
+cmake -B build-wasi -DCMAKE_TOOLCHAIN_FILE=$WASI_SDK_PATH/share/cmake/wasi-sdk-p2.cmake \
+ -DCMAKE_C_FLAGS="$FLAGS" -DCMAKE_CXX_FLAGS="$FLAGS" -DCMAKE_HAVE_LIBC_PTHREAD=1 \
+ -DBUILD_SHARED_LIBS=OFF -DGGML_NATIVE=OFF -DGGML_OPENMP=OFF -DLLAMA_BUILD_COMMON=OFF
+cmake --build build-wasi --target llama
+
+$WASI_SDK_PATH/bin/clang++ --target=wasm32-wasip3 -O3 $FLAGS -I include -I ggml/include examples/simple/simple.cpp \
+ build-wasi/src/libllama.a build-wasi/ggml/src/libggml*.a -lunwind -ldl -Wl,-z,stack-size=8388608 -o llama-simple.wasm
+wasmtime run -W exceptions=y --dir models llama-simple.wasm -m models/model.gguf "Hello"
+```
+
+### wasi:webgpu
+
+The WebGPU backend can target [wasi:webgpu](https://github.com/WebAssembly/wasi-webgpu) via [wasi-webgpu-headers](https://github.com/wasi-gfx/wasi-webgpu-headers) (with its submodule) and Dawn's `dawn-headers` release. Point `Dawn_DIR` at a directory containing this `DawnConfig.cmake` next to both:
+
+```cmake
+set(_wasi_webgpu "${CMAKE_CURRENT_LIST_DIR}/wasi-webgpu-headers")
+add_library(dawn::webgpu_dawn INTERFACE IMPORTED)
+set_target_properties(dawn::webgpu_dawn PROPERTIES
+ INTERFACE_SOURCES "${_wasi_webgpu}/webgpu.c;${_wasi_webgpu}/async_futures.c;${_wasi_webgpu}/imports.c;${_wasi_webgpu}/imports_component_type.o"
+ INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_LIST_DIR}/dawn-headers/include/webgpu_upstream;${_wasi_webgpu}")
+```
+
+Then build as above, but with `wasi-sdk-p3.cmake` / `--target=wasm32-wasip3`, `-DGGML_WEBGPU=ON -DDawn_DIR=...` at configure, and `build-wasi/ggml/src/ggml-webgpu/libggml-webgpu.a` added at link. See `.github/workflows/build-wasi.yml` for a more complete example.
+
## IBM Z & LinuxONE
To read documentation for how to build on IBM Z & LinuxONE, [click here](./build-s390x.md)