build(webui): build llama.cpp WebUI once in CI, share to all native builds

claude · claude · commit 75cae601f4f5 · 2026-06-19T20:44:20.000Z
Implements the build-once-share-artifact approach for embedding the llama.cpp Svelte WebUI into libjllama, so the in-process server (server-http.cpp) serves the real UI instead of the empty-asset stub. The repo commits no build outputs, so the WebUI is produced per-pipeline and never checked in (same policy as the native libs). CI (.github/workflows/publish.yml): - New build-webui job (ubuntu; the only job that runs npm): resolves the pinned b<nnnn> tag from CMakeLists.txt GIT_TAG, sparse-checks-out ggml-org/llama.cpp@<tag> tools/ui, runs the upstream Svelte build (npm ci && npm run build), gzips dist/ (LLAMA_UI_GZIP parity), builds the self-contained llama-ui-embed host tool (plain C++17, no npm) and runs it to produce the platform-independent webui-generated/ ui.cpp + ui.h, uploaded as the webui-generated artifact. - All 10 release-artifact build jobs now use needs:[startgate, build-webui] and download the artifact into webui-generated/ before building. npm never runs in the dockcross cross-compilers (no node) or per-platform — only once, in one job. CMake (CMakeLists.txt "WebUI assets" block): - When webui-generated/ui.cpp + ui.h are present, compile ui.cpp in and add its dir to the include path; the generated ui.h #defines LLAMA_UI_HAS_ASSETS, activating server-http.cpp's static-asset routes (compiled out under the stub). When absent, fall back to the empty-asset stub webui_stub/ui.h so local builds and any job without the artifact still build and run (no embedded UI). The WebUI version auto-follows GIT_TAG, so a llama.cpp bump needs no extra step. webui-generated/ is git-ignored; CLAUDE.md documents the pipeline + a local recipe. Verified locally (Linux x86_64) with the real llama-ui-embed tool (no npm) on a synthetic 9-asset dist: generated ui.cpp/ui.h carry LLAMA_UI_HAS_ASSETS + use_gzip (9 assets); jllama rebuilds with server-http.cpp's asset routes compiled in, ui.cpp compiled, libjllama.so linked (llama_ui_get_assets/find_asset defined, 0 undefined); NativeLibraryLoadSmokeTest passes; removing webui-generated/ -> CMake reports the stub fallback and jllama still builds. publish.yml parses (pyyaml); exactly the 10 native build jobs gate on build-webui. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JdLpWD8nedY7LwNnHefZLF
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -80,12 +80,98 @@ jobs:
           echo "=== internal package dependency graph (jdeps, bytecode) ==="
           jdeps -verbose:package target/classes | grep 'net.ladenthin.llama' || true
 
+  # ---------------------------------------------------------------------------
+  # Build the llama.cpp WebUI ONCE, from the same pinned tag CMakeLists.txt fetches,
+  # and share it to every native build as the generated, platform-independent
+  # ui.cpp/ui.h ("webui-generated" artifact).  The native builds embed it into
+  # libjllama (CMake's "WebUI assets" block); when this job's artifact is absent the
+  # build falls back to the empty-asset stub.  npm runs only here, in one controlled
+  # job — never in the dockcross cross-compilers (which have no node) or per-platform.
+  # ---------------------------------------------------------------------------
+  build-webui:
+    name: Build WebUI assets (shared)
+    needs: startgate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Resolve pinned llama.cpp tag from CMakeLists.txt
+        id: tag
+        shell: bash
+        run: |
+          TAG=$(grep -oE 'GIT_TAG[[:space:]]+b[0-9]+' CMakeLists.txt | grep -oE 'b[0-9]+' | head -1)
+          if [ -z "$TAG" ]; then
+            echo "could not resolve llama.cpp GIT_TAG (b<nnnn>) from CMakeLists.txt" >&2
+            exit 1
+          fi
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "Pinned llama.cpp WebUI tag: $TAG"
+      - name: Checkout llama.cpp tools/ui at the pinned tag
+        uses: actions/checkout@v6
+        with:
+          repository: ggml-org/llama.cpp
+          ref: ${{ steps.tag.outputs.tag }}
+          path: llamacpp-ui
+          sparse-checkout: tools/ui
+          sparse-checkout-cone-mode: true
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: llamacpp-ui/tools/ui/package-lock.json
+      - name: Build WebUI (Svelte/Vite)
+        working-directory: llamacpp-ui/tools/ui
+        env:
+          HF_UI_VERSION: ${{ steps.tag.outputs.tag }}
+          LLAMA_BUILD_NUMBER: ${{ steps.tag.outputs.tag }}
+        run: |
+          npm ci
+          npm run build
+          test -f dist/index.html
+      - name: Embed assets into ui.cpp / ui.h (gzip parity with upstream)
+        working-directory: llamacpp-ui/tools/ui
+        shell: bash
+        run: |
+          set -euo pipefail
+          # gzip every asset into dist/_gzip/<path> so llama-ui-embed embeds the
+          # compressed bytes (LLAMA_UI_GZIP parity); embed auto-detects _gzip.
+          ( cd dist && find . -type f -not -path './_gzip/*' | while read -r f; do
+              mkdir -p "_gzip/$(dirname "$f")"
+              gzip -9 -c "$f" > "_gzip/$f"
+            done )
+          # llama-ui-embed is a self-contained C++17 host tool (no npm) — build + run it.
+          g++ -O2 -std=c++17 -o llama-ui-embed embed.cpp
+          mkdir -p "$GITHUB_WORKSPACE/webui-generated"
+          ./llama-ui-embed \
+            "$GITHUB_WORKSPACE/webui-generated/ui.cpp" \
+            "$GITHUB_WORKSPACE/webui-generated/ui.h" \
+            dist
+          echo "=== generated WebUI assets ==="
+          ls -la "$GITHUB_WORKSPACE/webui-generated"
+          if grep -q LLAMA_UI_HAS_ASSETS "$GITHUB_WORKSPACE/webui-generated/ui.h"; then
+            echo "LLAMA_UI_HAS_ASSETS: present (real WebUI embedded)"
+          else
+            echo "ERROR: embed produced an empty asset table" >&2
+            exit 1
+          fi
+      - name: Upload WebUI artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: webui-generated
+          path: ${{ github.workspace }}/webui-generated/
+          retention-days: 1
+          if-no-files-found: error
+
   crosscompile-linux-x86_64-cuda:
     name: Cross-Compile manylinux_2_28 x86_64 (CUDA)
-    needs: startgate
+    needs: [startgate, build-webui]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+      - name: Download shared WebUI assets
+        uses: actions/download-artifact@v8
+        with:
+          name: webui-generated
+          path: ${{ github.workspace }}/webui-generated/
       - name: Display CPU Info
         shell: bash
         run: |
@@ -106,10 +192,15 @@ jobs:
 
   crosscompile-linux-x86_64:
     name: Cross-Compile manylinux2014 x86_64
-    needs: startgate
+    needs: [startgate, build-webui]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+      - name: Download shared WebUI assets
+        uses: actions/download-artifact@v8
+        with:
+          name: webui-generated
+          path: ${{ github.workspace }}/webui-generated/
       - name: Display CPU Info
         shell: bash
         run: |
@@ -130,10 +221,15 @@ jobs:
 
   crosscompile-linux-aarch64:
     name: Cross-Compile Linux aarch64 (LTS)
-    needs: startgate
+    needs: [startgate, build-webui]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+      - name: Download shared WebUI assets
+        uses: actions/download-artifact@v8
+        with:
+          name: webui-generated
+          path: ${{ github.workspace }}/webui-generated/
       - name: Display CPU Info
         shell: bash
         run: |
@@ -154,10 +250,15 @@ jobs:
 
   crosscompile-android-aarch64:
     name: Cross-Compile Android aarch64
-    needs: startgate
+    needs: [startgate, build-webui]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+      - name: Download shared WebUI assets
+        uses: actions/download-artifact@v8
+        with:
+          name: webui-generated
+          path: ${{ github.workspace }}/webui-generated/
       - name: Display CPU Info
         shell: bash
         run: |
@@ -178,10 +279,15 @@ jobs:
 
   crosscompile-android-aarch64-opencl:
     name: Cross-Compile Android aarch64 (OpenCL/Adreno)
-    needs: startgate
+    needs: [startgate, build-webui]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+      - name: Download shared WebUI assets
+        uses: actions/download-artifact@v8
+        with:
+          name: webui-generated
+          path: ${{ github.workspace }}/webui-generated/
       - name: Build libraries
         shell: bash
         run: |
@@ -198,10 +304,15 @@ jobs:
 
   build-macos-arm64-no-metal:
     name: Build and Test macOS 15 arm64 (no Metal)
-    needs: startgate
+    needs: [startgate, build-webui]
     runs-on: macos-15
     steps:
       - uses: actions/checkout@v6
+      - name: Download shared WebUI assets
+        uses: actions/download-artifact@v8
+        with:
+          name: webui-generated
+          path: ${{ github.workspace }}/webui-generated/
       - uses: actions/setup-java@v5
         with:
           distribution: 'temurin'
@@ -229,10 +340,15 @@ jobs:
 
   build-macos-arm64-metal:
     name: Build and Test macOS 14 arm64 (Metal)
-    needs: startgate
+    needs: [startgate, build-webui]
     runs-on: macos-14
     steps:
       - uses: actions/checkout@v6
+      - name: Download shared WebUI assets
+        uses: actions/download-artifact@v8
+        with:
+          name: webui-generated
+          path: ${{ github.workspace }}/webui-generated/
       - uses: actions/setup-java@v5
         with:
           distribution: 'temurin'
@@ -260,10 +376,15 @@ jobs:
 
   build-windows-x86_64:
     name: Build and Test Windows 2025 x86_64 (VS 2026)
-    needs: startgate
+    needs: [startgate, build-webui]
     runs-on: windows-2025-vs2026
     steps:
       - uses: actions/checkout@v6
+      - name: Download shared WebUI assets
+        uses: actions/download-artifact@v8
+        with:
+          name: webui-generated
+          path: ${{ github.workspace }}/webui-generated/
       - name: Display CPU Info
         shell: pwsh
         run: |
@@ -289,10 +410,15 @@ jobs:
 
   build-windows-x86:
     name: Build and Test Windows 2025 x86 (VS 2026)
-    needs: startgate
+    needs: [startgate, build-webui]
     runs-on: windows-2025-vs2026
     steps:
       - uses: actions/checkout@v6
+      - name: Download shared WebUI assets
+        uses: actions/download-artifact@v8
+        with:
+          name: webui-generated
+          path: ${{ github.workspace }}/webui-generated/
       - name: Display CPU Info
         shell: pwsh
         run: |
@@ -346,10 +472,15 @@ jobs:
 
   build-macos-arm64-metal-15:
     name: Build and Test macOS 15 arm64 (Metal)
-    needs: startgate
+    needs: [startgate, build-webui]
     runs-on: macos-15
     steps:
       - uses: actions/checkout@v6
+      - name: Download shared WebUI assets
+        uses: actions/download-artifact@v8
+        with:
+          name: webui-generated
+          path: ${{ github.workspace }}/webui-generated/
       - uses: actions/setup-java@v5
         with:
           distribution: 'temurin'
diff --git a/.gitignore b/.gitignore
@@ -46,6 +46,11 @@ src/main/resources/**/*.dll
 src/main/resources/**/*.metal
 src/test/resources/**/*.gbnf
 
+# Generated WebUI assets (ui.cpp/ui.h) produced once by the build-webui CI job and
+# downloaded into every native build; embedded into libjllama, never committed
+# (this repo commits no build outputs — same policy as the native libs above).
+/webui-generated/
+
 **/*.etag
 **/*.lastModified
 src/main/cpp/llama.cpp/
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -121,6 +121,50 @@ At runtime the device must provide its own OpenCL ICD (`libOpenCL.so`);
 Qualcomm Adreno drivers do. Devices without an ICD should use the default
 CPU-only Android JAR.
 
+## WebUI (llama.cpp Svelte UI) embedding
+
+The llama.cpp WebUI is **built once in CI and shared to every native build**, then
+compiled into `libjllama` so the embedded server (`server-http.cpp`) can serve it.
+This repo commits no build outputs, so the assets are produced per-pipeline, never
+checked in (same policy as the native libs).
+
+Pipeline (`.github/workflows/publish.yml`):
+
+1. **`build-webui` job** (ubuntu — the *only* job that runs `npm`): resolves the
+   pinned `b<nnnn>` tag from `CMakeLists.txt`'s `GIT_TAG`, sparse-checks-out
+   `ggml-org/llama.cpp@<tag>` `tools/ui`, runs the upstream Svelte build
+   (`npm ci && npm run build`), gzips `dist/` into `dist/_gzip/` (LLAMA_UI_GZIP
+   parity), builds the self-contained `llama-ui-embed` host tool (plain C++17, **no
+   npm**) and runs it to produce the platform-independent **`webui-generated/ui.cpp`
+   + `ui.h`**, uploaded as the `webui-generated` artifact.
+2. **Every native build job** (`needs: [startgate, build-webui]`) downloads that
+   artifact into `webui-generated/` before building. npm never runs in the dockcross
+   cross-compilers (which have no node) or per-platform.
+3. **CMake** (the "WebUI assets" block in `CMakeLists.txt`): if
+   `webui-generated/ui.cpp` + `ui.h` exist, compiles `ui.cpp` in and adds its dir to
+   the include path — the generated `ui.h` `#define`s `LLAMA_UI_HAS_ASSETS`, which
+   activates `server-http.cpp`'s static-asset routes. If absent, it falls back to the
+   empty-asset stub `src/main/cpp/webui_stub/ui.h` (no embedded UI) so local builds —
+   and any job without the artifact — still build and run.
+
+The WebUI version **auto-follows** the pinned `GIT_TAG`: a llama.cpp version bump
+needs no extra step here, `build-webui` re-reads the tag and rebuilds the matching UI.
+
+**Building the WebUI locally** (optional — a plain `cmake` build uses the stub and
+ships no UI):
+```bash
+# needs node/npm + network; embed.cpp is plain C++17 (no npm)
+git clone --depth 1 --branch b9682 https://github.com/ggml-org/llama.cpp /tmp/lc
+( cd /tmp/lc/tools/ui && npm ci && npm run build \
+  && ( cd dist && find . -type f -not -path './_gzip/*' \
+       | while read -r f; do mkdir -p "_gzip/$(dirname "$f")"; gzip -9 -c "$f" > "_gzip/$f"; done ) \
+  && g++ -O2 -std=c++17 -o /tmp/llama-ui-embed embed.cpp )
+mkdir -p webui-generated
+/tmp/llama-ui-embed webui-generated/ui.cpp webui-generated/ui.h /tmp/lc/tools/ui/dist
+cmake -B build && cmake --build build --target jllama   # now embeds the real UI
+```
+`webui-generated/` is git-ignored.
+
 ## Upgrading/Downgrading llama.cpp Version
 
 To change the llama.cpp version, update the following **three** files:
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -286,11 +286,13 @@ endif()
 # and link.
 #
 # server-http.cpp does `#include "ui.h"` — the WebUI asset table that tools/ui
-# normally GENERATES.  We do not ship the Svelte WebUI (it needs npm / a prebuilt
-# asset download), so src/main/cpp/webui_stub/ui.h supplies the upstream "empty
-# asset table" interface instead (see that file).  <cpp-httplib/httplib.h> already
-# resolves via llama-common's vendor/ include dir, whose bundled nlohmann/json is
-# the same 3.12.0 as our FetchContent copy, so adding nothing there shadows it.
+# normally GENERATES.  The WebUI is built once in CI (the build-webui job) and
+# shared to every native build as a generated, platform-independent ui.cpp/ui.h;
+# the "WebUI assets" block below compiles it in when present and otherwise falls
+# back to the empty-asset stub (src/main/cpp/webui_stub/ui.h).
+# <cpp-httplib/httplib.h> already resolves via llama-common's vendor/ include dir,
+# whose bundled nlohmann/json is the same 3.12.0 as our FetchContent copy, so
+# adding nothing there shadows it.
 target_sources(jllama PRIVATE
     ${llama.cpp_SOURCE_DIR}/tools/server/server-http.cpp
     ${llama.cpp_SOURCE_DIR}/vendor/cpp-httplib/httplib.cpp
@@ -315,14 +317,33 @@ if(WIN32 AND NOT MSVC)
     target_link_libraries(jllama PRIVATE ws2_32)
 endif()
 
+# WebUI assets.  The llama.cpp WebUI is built once in CI by the build-webui job
+# (upstream Svelte build + llama-ui-embed, run against the pinned llama.cpp tag)
+# and shared to every native build as the generated, platform-independent
+# ui.cpp / ui.h under webui-generated/ (git-ignored; downloaded as the
+# "webui-generated" artifact — this repo commits no build outputs).  When present,
+# compile it in so libjllama serves the real WebUI: the generated ui.h #defines
+# LLAMA_UI_HAS_ASSETS, which activates server-http.cpp's static-asset routes.  When
+# absent (local builds, or any job without the artifact) fall back to the empty-
+# asset stub so the server still builds and runs, just without an embedded WebUI.
+set(JLLAMA_WEBUI_GENERATED_DIR ${CMAKE_SOURCE_DIR}/webui-generated)
+if(EXISTS ${JLLAMA_WEBUI_GENERATED_DIR}/ui.cpp AND EXISTS ${JLLAMA_WEBUI_GENERATED_DIR}/ui.h)
+    message(STATUS "WebUI: embedding generated assets from ${JLLAMA_WEBUI_GENERATED_DIR}")
+    target_sources(jllama PRIVATE ${JLLAMA_WEBUI_GENERATED_DIR}/ui.cpp)
+    target_include_directories(jllama PRIVATE ${JLLAMA_WEBUI_GENERATED_DIR})
+else()
+    message(STATUS "WebUI: no generated assets found; using empty-asset stub (no embedded WebUI)")
+    target_include_directories(jllama PRIVATE ${CMAKE_SOURCE_DIR}/src/main/cpp/webui_stub)
+endif()
+
 set_target_properties(jllama PROPERTIES POSITION_INDEPENDENT_CODE ON)
 target_include_directories(jllama PRIVATE
     src/main/cpp
-    # webui_stub/ui.h stands in for the generated llama-ui header (see Phase 2 above)
-    src/main/cpp/webui_stub
     ${JNI_INCLUDE_DIRS}
     ${llama.cpp_SOURCE_DIR}/tools/mtmd
     ${llama.cpp_SOURCE_DIR}/tools/server)
+# Note: the WebUI ui.h include dir (generated webui-generated/ or the empty stub
+# src/main/cpp/webui_stub) is added by the "WebUI assets" conditional above.
 target_link_libraries(jllama PRIVATE llama-common mtmd llama nlohmann_json)
 target_compile_features(jllama PRIVATE cxx_std_11)
 
