Skip to content

The all-in-one local AI studio for your desktop: chat, image and video generation and a coding agent in one free, open source app. Windows and Linux. No Docker, no terminal, no cloud required.

35.2 KB
Raw Blame
#!/usr/bin/env bash
#
# build-llama.sh — build the bundled llama.cpp `llama-server` sidecar for
# Locally Uncensored's built-in inference engine (P0 of the built-in-engine plan).
#
# mac: the produced binary is statically linked with Metal embedded, so a
# single self-contained file drops into `src-tauri/bin/llama-server-<triple>`
# and Tauri picks it up as an `externalBin` sidecar (target triple appended,
# code-signed with the app on macOS).
#
# Windows and Linux (K1, 3.0.1): the binary is dynamic and loads its CPU
# kernels and the Vulkan backend at runtime (GGML_BACKEND_DL +
# GGML_CPU_ALL_VARIANTS, see cmake_flags_for below): a fixed x86-64-v3
# binary made every pre-Haswell/pre-Excavator CPU crash with 0xC000001D
# (Windows) or SIGILL (Linux) before llama-server could log anything. The
# companion ggml-cpu-*/ggml-vulkan libraries this produces land in
# `src-tauri/resources/llama/<triple>/`, bundled as Tauri `resources`
# (tauri.windows.conf.json / tauri.linux.conf.json) alongside the exe
# sidecar, not as more externalBin entries.
#
# Idempotent: clones/pins llama.cpp once into a build cache, reuses it on reruns.
# Binaries and companion libraries are NOT committed, see
# src-tauri/bin/.gitignore and src-tauri/resources/llama/.gitignore.
#
# Usage:
#   scripts/build-llama.sh                 # build for the host target triple
#   scripts/build-llama.sh <triple> ...    # build for one or more explicit triples
#   scripts/build-llama.sh --check         # verify already-built host binary boots
#
# Supported triples:
#   aarch64-apple-darwin      (Metal, embedded shaders)   — mac-first
#   x86_64-apple-darwin       (Metal, embedded shaders)   — mac-first
#   x86_64-pc-windows-msvc    (Vulkan)                    — P6, after launch
#   x86_64-unknown-linux-gnu  (Vulkan)                    — P6, after launch
#
set -euo pipefail

# --- Pinned, reproducible llama.cpp revision -------------------------------
# LLAMA_COMMIT is the pin. A git tag is a mutable pointer: upstream can delete
# and recreate it, and whoever owns that repo (or anyone who takes it over) can
# point b9949 at different code tomorrow. This script builds the binary that
# ships inside the installer and is code-signed with the app, so "whatever the
# tag names on the day CI runs" is not a supply chain we can stand behind.
# LLAMA_TAG stays as the readable name and as the cross-check: on every run,
# cache hit included, ensure_src asserts BOTH that HEAD is LLAMA_COMMIT and
# that the working tree carries no change against it, and the build stops if
# either fails.
#
# To bump, resolve the tag yourself and paste BOTH — llama.cpp tags are build
# numbers and upstream SKIPS numbers whose CI failed, so the tag must exist:
#   git ls-remote --tags https://github.com/ggml-org/llama.cpp.git 'refs/tags/<tag>'
# CI reuses a cached checkout keyed on hashFiles('scripts/build-llama.sh')
# (release.yml, sidecar-windows.yml), so both values below are inside the cache
# key by construction — bumping one cannot silently reuse the old source tree.
LLAMA_TAG="${LLAMA_TAG:-b11960}"
LLAMA_COMMIT="${LLAMA_COMMIT:-8642541b255bfb5dc39cd351a178be09013a55d6}"
LLAMA_REPO="${LLAMA_REPO:-https://github.com/ggml-org/llama.cpp.git}"

# --- Paths -----------------------------------------------------------------
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Overridable only for tests (build-llama-script.test.ts), the same pattern as
# LLAMA_BUILD_CACHE below: a real build always derives it from the script's
# own location, so BIN_DIR/resources always land in the real checkout.
REPO_ROOT="${BUILD_LLAMA_REPO_ROOT:-$(cd "$SCRIPT_DIR/.." && pwd)}"
CACHE_DIR="${LLAMA_BUILD_CACHE:-$REPO_ROOT/.llama-build}"
SRC_DIR="$CACHE_DIR/llama.cpp"
BIN_DIR="$REPO_ROOT/src-tauri/bin"

log()  { printf '\033[1;35m[build-llama]\033[0m %s\n' "$*"; }
die()  { printf '\033[1;31m[build-llama] ERROR:\033[0m %s\n' "$*" >&2; exit 1; }

host_triple() {
  if command -v rustc >/dev/null 2>&1; then
    rustc --print host-tuple 2>/dev/null && return
    rustc -vV 2>/dev/null | awk '/^host:/{print $2}'
  else
    # Fallback for macOS without rustc on PATH.
    case "$(uname -sm)" in
      "Darwin arm64")  echo "aarch64-apple-darwin" ;;
      "Darwin x86_64") echo "x86_64-apple-darwin" ;;
      *) die "cannot infer host triple; pass one explicitly" ;;
    esac
  fi
}

# Map a Rust target triple → cmake flags for the llama-server build.
# LLAMA_OPENSSL=OFF: no HTTPS/downloader deps — the app manages model files.
# LLAMA_BUILD_UI/USE_PREBUILT_UI=OFF: headless sidecar — no npm build and no
# HF asset fetch at compile time.
#
# K1 (3.0.1): mac stays a single STATIC binary with Metal embedded. Apple
# Silicon has one relevant CPU family, so there is nothing to select at
# runtime and GGML_CPU_ALL_VARIANTS does not even claim ARM/Apple support for
# it (ggml/src/CMakeLists.txt only wires ALL_VARIANTS for x86, ARM/Android/
# PowerPC/s390x/riscv64, never "Apple x86_64" as a variant target; darwin
# stays out of that switch entirely).
#
# Windows and Linux (x86_64) switch to a DYNAMIC, multi-ISA build instead of
# one fixed x86-64-v3 binary. With GGML_NATIVE=OFF (unchanged, always was)
# and INS_ENB therefore ON, ggml/CMakeLists.txt:141-166 forces SSE4.2 + AVX +
# AVX2 + BMI2 + FMA + F16C into the ONE binary this script used to produce,
# any CPU older than Haswell/Excavator (2013+) gets 0xC000001D on Windows or
# SIGILL on Linux before llama-server can even log a line. Verified against
# the pinned llama.cpp checkout, not guessed:
#   GGML_BACKEND_DL=ON + GGML_CPU_ALL_VARIANTS=ON is the exact pair
#   ggml/src/CMakeLists.txt:371-376 requires (GGML_CPU_ALL_VARIANTS without
#   GGML_BACKEND_DL is a FATAL_ERROR there), and GGML_CPU_ALL_VARIANTS in turn
#   requires BUILD_SHARED_LIBS=ON (ggml/src/CMakeLists.txt:188-190, also a
#   FATAL_ERROR otherwise). Under MSVC this produces nine ggml-cpu-*.dll
#   variants (x64, sse42, sandybridge, haswell, skylakex, cannonlake,
#   cascadelake, icelake, alderlake (ggml/src/CMakeLists.txt:378-402); GCC on
#   Linux additionally gets ivybridge, piledriver, cooperlake, zen4 and
#   sapphirerapids (same block, the four "if (NOT MSVC)" branches). At
#   startup llama-server calls ggml_backend_load_all() (src/llama.cpp,
#   common/arg.cpp), which (per ggml/src/ggml-backend-reg.cpp:479-486)
#   scores every ggml-cpu-*.{dll,so} beside the executable and in the current
#   working directory and dlopen()s the best-scoring one for the CPU it is
#   actually running on. GGML_VULKAN stays on for both; it becomes a sibling
#   loadable backend (ggml-vulkan.dll/.so) the same way, discovered through
#   the identical search, so the GPU path is unaffected by this switch.
cmake_flags_for() {
  local triple="$1"
  local common="-DLLAMA_OPENSSL=OFF -DLLAMA_BUILD_UI=OFF -DLLAMA_USE_PREBUILT_UI=OFF -DGGML_NATIVE=OFF -DCMAKE_BUILD_TYPE=Release"
  case "$triple" in
    aarch64-apple-darwin)
      echo "$common -DBUILD_SHARED_LIBS=OFF -DGGML_METAL=ON -DGGML_METAL_EMBED_LIBRARY=ON -DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_OSX_DEPLOYMENT_TARGET=${MACOSX_DEPLOYMENT_TARGET:-14.0}" ;;
    x86_64-apple-darwin)
      echo "$common -DBUILD_SHARED_LIBS=OFF -DGGML_METAL=ON -DGGML_METAL_EMBED_LIBRARY=ON -DCMAKE_OSX_ARCHITECTURES=x86_64 -DCMAKE_OSX_DEPLOYMENT_TARGET=${MACOSX_DEPLOYMENT_TARGET:-14.0}" ;;
    x86_64-pc-windows-msvc)
      # -MAP, not /MAP (review-waechter-windows.md BL1): verify-sidecar-isa.sh's
      # Windows ISA guard needs a linker map to turn a VEX/EVEX hit's address
      # into an owning function and Lib:Object (the CRT/STL allowlist and the
      # own-code dominance check both key off that). MSYS/Git-Bash rewrites an
      # ARGV entry that looks like a Unix absolute path ("/MAP") into a native
      # Windows path before the (unquoted) cmake invocation in build_triple
      # below ever sees it, on the command line just as much as in an
      # environment variable: measured on the box, `cmd //c echo
      # -DCMAKE_SHARED_LINKER_FLAGS=/MAP` comes back as
      # `-DCMAKE_SHARED_LINKER_FLAGS=C:/Program Files/Git/MAP`, so the linker
      # never received /MAP at all and produced no .map file (an earlier
      # version of this comment claimed the cmake command line was exempt
      # from that rewriting; it measured that only against a Windows CI
      # workflow log that had been produced with a manual override, and the
      # claim was wrong). link.exe accepts the single-dash spelling exactly
      # the same way (`cmd //c echo -DCMAKE_SHARED_LINKER_FLAGS=-MAP` passes
      # through unchanged, since "-MAP" does not look like a Unix path to
      # MSYS's argv rewriter), so use that instead of the LDFLAGS/
      # MSYS2_ENV_CONV_EXCL environment-variable workaround the box bauer used
      # to prove this out (e2e/k1-avx, 04-BOX-SIDECAR-AVX-BEFUND.md Schritt 1).
      #
      # A REAL sidecar rebuild on the box with only the two flags above
      # (round 2's first attempt) surfaced a second, genuine gap: cmake has
      # THREE linker-flags cache variables, not two.
      # ggml/src/CMakeLists.txt:267 adds every GGML_BACKEND_DL backend
      # (`add_library(${backend} MODULE ${ARGN})`, both the nine
      # ggml-cpu-*.dll variants and ggml-vulkan.dll) as a CMake MODULE
      # library, not SHARED, and MSVC/CMake links a MODULE target with
      # CMAKE_MODULE_LINKER_FLAGS, a cache variable CMAKE_SHARED_LINKER_FLAGS
      # never reaches. Measured: a build with only
      # CMAKE_SHARED_LINKER_FLAGS/CMAKE_EXE_LINKER_FLAGS set to -MAP produced
      # ggml.map, ggml-base.map, llama.map, llama-common.map,
      # llama-server-impl.map, mtmd.map and llama-server.map (the exe) but
      # NOT ONE .map for any ggml-cpu-*.dll or ggml-vulkan.dll, exactly the
      # files verify-sidecar-isa.sh's Windows guard most needs a map for,
      # since they are where an unconditional-AVX regression would actually
      # ship. All three linker-flags variables now carry -MAP.
      #
      # -jumptablerdata (FEHLER-E1 #1, FEHLER-P11 #9): MSVC puts switch jump
      # tables in .text beside the code by default (learn.microsoft.com,
      # /jumptablerdata), and their entries are image RVAs that the ISA guard
      # decodes as instructions. With b11960 it read one in llama.dll as
      # "vsqrtph zmm28" at $LN954 of unicode.obj; nothing in that object can
      # emit EVEX (no /arch outside ggml-cpu). In .rdata the guard no longer
      # reads tables as code, so a hit that stays is real code. Set through
      # CMAKE_<LANG>_FLAGS_INIT, which CMake's Windows-MSVC module appends its
      # defaults (/EHsc and the rest) to; CMAKE_<LANG>_FLAGS would replace
      # them. Dash spelling for the same MSYS reason as -MAP. MSVC 17.7+, x64.
      #
      # LLAMA_MSVC_TOOLSET (3.1.2, 19.11.2026): the Visual Studio toolset cmake
      # hands to MSBuild (-T). verify-sidecar-isa.sh only trusts linker
      # versions whose CRT/STL code was reviewed (WINDOWS_REVIEWED_LINKER_
      # VERSIONS), and the hosted windows-latest image moved its default to
      # MSVC 14.52 overnight, which that guard rightly refuses. CI pins the
      # reviewed 14.44 toolset the image still installs
      # (Microsoft.VisualStudio.Component.VC.14.44.17.14.x86.x64). Empty
      # (default, e.g. on the box) leaves the generator's own choice.
      local toolset=""
      [ -z "${LLAMA_MSVC_TOOLSET:-}" ] || toolset=" -T ${LLAMA_MSVC_TOOLSET}"
      echo "$common -DBUILD_SHARED_LIBS=ON -DGGML_BACKEND_DL=ON -DGGML_CPU_ALL_VARIANTS=ON -DGGML_VULKAN=ON -DCMAKE_SHARED_LINKER_FLAGS=-MAP -DCMAKE_EXE_LINKER_FLAGS=-MAP -DCMAKE_MODULE_LINKER_FLAGS=-MAP -DCMAKE_C_FLAGS_INIT=-jumptablerdata -DCMAKE_CXX_FLAGS_INIT=-jumptablerdata${toolset}" ;;
    x86_64-unknown-linux-gnu)
      # CMAKE_BUILD_RPATH_USE_ORIGIN=ON (BLOCKER B3): without it,
      # CMAKE_BUILD_WITH_INSTALL_RPATH's OFF default still makes CMake write
      # an RPATH into every linked .so/exe, and that RPATH is an ABSOLUTE
      # path into the CI runner's own build directory (a path that will not
      # exist once shipped) unless told to compute an $ORIGIN-relative one
      # instead. This is not visible by grepping CMakeLists.txt for the word
      # RPATH, since no CMakeLists.txt line requests it either way, it is
      # CMake's own default: only readelf on the actual output proves what
      # landed (see check_no_absolute_build_rpath in verify-sidecar-isa.sh).
      echo "$common -DBUILD_SHARED_LIBS=ON -DGGML_BACKEND_DL=ON -DGGML_CPU_ALL_VARIANTS=ON -DGGML_VULKAN=ON -DCMAKE_BUILD_RPATH_USE_ORIGIN=ON" ;;
    *)
      die "unsupported target triple: $triple" ;;
  esac
}

# True for a triple this script builds as a dynamic, multi-ISA sidecar (a
# main executable plus loadable ggml-cpu-*/ggml-vulkan companion libraries).
# False for mac, which stays the old single static binary. Both the copy step
# and the resource layout branch on this, so it is one function instead of
# two case statements that could drift apart.
is_dynamic_isa_triple() {
  case "$1" in
    x86_64-pc-windows-msvc | x86_64-unknown-linux-gnu) return 0 ;;
    *) return 1 ;;
  esac
}

# Directory the companion ggml/llama shared libraries for a dynamic-ISA
# triple are staged into, so Tauri can bundle them as `resources` (see
# tauri.windows.conf.json / tauri.linux.conf.json) and so the same path is a
# stable, known location in dev (no bundling involved, engine.rs reads it
# straight off disk, see resolve_engine_backend_dir).
resource_llama_dir_for() {
  echo "$REPO_ROOT/src-tauri/resources/llama/$1"
}

# The bundled file carries the app prefix (GitHub #120): Tauri's deb bundler
# copies external binaries into /usr/bin, and Debian's own llama.cpp-tools
# package already owns /usr/bin/llama-server, so a plain name made dpkg refuse
# the whole install. Only the OUTPUT name changes; the binary llama.cpp itself
# builds is still called llama-server and is found under that name above.
out_name_for() {
  case "$1" in
    *-windows-*) echo "lu-llama-server-$1.exe" ;;
    *)           echo "lu-llama-server-$1" ;;
  esac
}

# llama-quantize ships on macOS only (static binary, nothing beside it).
quantize_ships_for() {
  case "$1" in
    *-apple-darwin) return 0 ;;
    *)              return 1 ;;
  esac
}

quantize_out_name_for() {
  echo "lu-llama-quantize-$1"
}

# llama-cvector-generator (3.0.9, P11 Neuron tweaker) ships on all three
# desktop platforms: it turns two short lists of example prompts into a
# control vector for the model the user has, which llama-server then applies
# with --control-vector. FEHLER-P11 #7: everything a feature needs must come
# with the install.
#
# It comes out of the server's own build on every platform, linked against
# the same libraries: on the Mac the static Metal build, on Windows and Linux
# the GGML_BACKEND_DL build with the CPU variants and Vulkan as loadable
# modules (K1). Upstream defines the target only without GGML_BACKEND_DL,
# because the generator calls ggml-cpu directly; LU's patch
# 0002-cvector-generator-backend-dl.patch reaches those through the backend
# registry instead and lifts that condition. So the tool computes on the
# GPU (LU passes -ngl 99) and otherwise on the best CPU variant, like the
# server. Until E1 (3.0.9) Windows and Linux had a static CPU-only baseline
# build of their own (FEHLER-P11 #8), without SSE4.2/AVX/AVX2: LFM3 1.7B
# took ~25 min on the box against 30 s on the Mac, a 9B model hours. That
# build is gone; its ISA rules hold for the tool as for the server exe.
cvector_ships_for() {
  case "$1" in
    *-apple-darwin | x86_64-pc-windows-msvc | x86_64-unknown-linux-gnu) return 0 ;;
    *)                                                                 return 1 ;;
  esac
}

# Where the tool is built, and where verify-sidecar-isa.sh finds its linker
# map on Windows: the server's build directory.
cvector_build_dir_for() {
  echo "$CACHE_DIR/build-$1"
}

cvector_out_name_for() {
  case "$1" in
    *-windows-*) echo "lu-llama-cvector-generator-$1.exe" ;;
    *)           echo "lu-llama-cvector-generator-$1" ;;
  esac
}

# A 40-hex commit SHA and nothing else. A short SHA, a tag name or an empty
# override would all silently reduce the pin back to "whatever origin says".
assert_pinned_commit() {
  case "$LLAMA_COMMIT" in
    *[!0-9a-f]* | "") die "LLAMA_COMMIT must be a full 40-char lowercase commit SHA, got '$LLAMA_COMMIT'" ;;
  esac
  [ "${#LLAMA_COMMIT}" -eq 40 ] \
    || die "LLAMA_COMMIT must be a full 40-char lowercase commit SHA, got '$LLAMA_COMMIT'"
}

ensure_src() {
  command -v git >/dev/null 2>&1 || die "git not found"
  assert_pinned_commit
  mkdir -p "$CACHE_DIR"
  if [ ! -d "$SRC_DIR/.git" ]; then
    log "initialising llama.cpp checkout for $LLAMA_TAG ($LLAMA_COMMIT)"
    git init -q "$SRC_DIR"
    git -C "$SRC_DIR" remote add origin "$LLAMA_REPO"
  fi
  local have
  have="$(git -C "$SRC_DIR" rev-parse HEAD 2>/dev/null || true)"
  if [ "$have" != "$LLAMA_COMMIT" ]; then
    log "fetching llama.cpp $LLAMA_TAG ($LLAMA_COMMIT)"
    # Fetch the object by SHA — GitHub serves any commit reachable from a ref,
    # and a request for a SHA cannot be answered with different code. The tag
    # is only the fallback for a mirror that refuses SHA fetches; the check
    # below is what decides whether we got the right object either way.
    git -C "$SRC_DIR" fetch --depth 1 origin "$LLAMA_COMMIT" 2>/dev/null \
      || git -C "$SRC_DIR" fetch --depth 1 origin "refs/tags/$LLAMA_TAG"
    git -C "$SRC_DIR" checkout -f --detach FETCH_HEAD
  fi
  # Re-asserted on every run, cache hit included: a restored build cache is an
  # artifact from an earlier run, not evidence about what is in it now.
  have="$(git -C "$SRC_DIR" rev-parse HEAD)"
  [ "$have" = "$LLAMA_COMMIT" ] \
    || die "llama.cpp checkout is at $have, expected $LLAMA_COMMIT ($LLAMA_TAG) — upstream tag moved, or the build cache is stale"
  # A clean tree gets LU's patches; a tree that carries them already (a
  # cache from an earlier run) is checked to carry exactly them.
  if [ -z "$(git -C "$SRC_DIR" status --porcelain --untracked-files=all 2>/dev/null)" ]; then
    apply_lu_patches
  fi
  assert_patched_tree
}

# LU's own changes to the pinned source, reviewed in this repo
# (scripts/llama-patches/*.patch). 0001-0004 only touch
# tools/cvector-generator. 0005 (A40, 3.1.2) is upstream llama.cpp PR 31360
# backported: two `constexpr` words out of ggml-metal/kernels/unary.metal, so
# the embedded Metal library compiles on macOS 14 and 15 again. Drop it once
# LLAMA_COMMIT is at or past c9daee1. Everything else in the server binary is
# the pinned source unchanged.
#
# P11 FEHLER 10 (David's test build, 31.10.2026): the vector tool aborted
# on Qwen3.5 (GGML_ASSERT diff_filtered.size() == n_layers - 1): b9949 keeps
# the last block's full rows there, so one layer too many came through.
LU_PATCH_DIR="${LLAMA_LU_PATCH_DIR:-$REPO_ROOT/scripts/llama-patches}"

lu_patches() {
  [ -d "$LU_PATCH_DIR" ] || return 0
  find "$LU_PATCH_DIR" -maxdepth 1 -name '*.patch' | LC_ALL=C sort
}

apply_lu_patches() {
  local p
  for p in $(lu_patches); do
    log "applying $(basename "$p")"
    git -C "$SRC_DIR" apply "$p" || die "LU patch $(basename "$p") does not apply to $LLAMA_COMMIT ($LLAMA_TAG)"
  done
}

# The files LU's patches touch, one per line.
lu_patched_files() {
  local p
  for p in $(lu_patches); do
    sed -n 's|^+++ b/||p' "$p"
  done | LC_ALL=C sort -u
}

# What is compiled is the pinned commit plus LU's patches and nothing else:
# every change in the tree is a file a patch touches, and each such file is
# byte for byte the pinned file with the patches applied.
assert_patched_tree() {
  git -C "$SRC_DIR" update-index -q --really-refresh >/dev/null 2>&1 || true
  local dirty allowed line path
  dirty="$(git -C "$SRC_DIR" status --porcelain --untracked-files=all 2>/dev/null || true)"
  allowed="$(lu_patched_files)"
  while IFS= read -r line; do
    [ -n "$line" ] || continue
    path="${line:3}"
    case "$line" in
      " M "*) printf '%s\n' "$allowed" | grep -qxF "$path" && continue ;;
    esac
    die "llama.cpp source tree does not match $LLAMA_COMMIT ($LLAMA_TAG) plus LU's patches — the checkout carries local changes, so the build would not be the pinned source:
$dirty"
  done <<EOF_DIRTY
$dirty
EOF_DIRTY
  [ -n "$allowed" ] || return 0
  local tmp p f
  tmp="$(mktemp -d)"
  while IFS= read -r f; do
    mkdir -p "$tmp/$(dirname "$f")"
    git -C "$SRC_DIR" show "HEAD:$f" > "$tmp/$f"
  done <<EOF_FILES
$allowed
EOF_FILES
  for p in $(lu_patches); do
    (cd "$tmp" && git apply "$p") || { rm -rf "$tmp"; die "LU patch $(basename "$p") does not apply to $LLAMA_COMMIT ($LLAMA_TAG)"; }
  done
  while IFS= read -r f; do
    cmp -s "$tmp/$f" "$SRC_DIR/$f" || { rm -rf "$tmp"; die "llama.cpp source tree does not match $LLAMA_COMMIT ($LLAMA_TAG) plus LU's patches: $f differs"; }
  done <<EOF_FILES
$allowed
EOF_FILES
  rm -rf "$tmp"
}

# rev-parse only proves where HEAD POINTS. cmake does not compile HEAD, it
# compiles the WORKING TREE under $SRC_DIR — and a restored cache is a tarball
# somebody else produced, in which the files can say anything while .git/HEAD
# still names the pinned SHA. Verifying the pointer and calling that a verified
# source tree was the whole gap.
#
# `git status` closes it: the index is force-refreshed so nothing rides on a
# stale stat cache, and then any tracked file whose CONTENT differs from the
# pinned commit, and any untracked file that is not covered by llama.cpp's own
# .gitignore, makes the build stop. Together with the SHA check above that is
# the statement the comment always claimed: what gets compiled is the tree the
# pinned commit names.
#
# Ignored paths are deliberately not in scope — the cmake build directory lives
# outside $SRC_DIR, so nothing in the ignore set reaches the compiler.
assert_clean_tree() {
  git -C "$SRC_DIR" update-index -q --really-refresh >/dev/null 2>&1 || true
  local dirty
  dirty="$(git -C "$SRC_DIR" status --porcelain --untracked-files=all 2>/dev/null || true)"
  [ -z "$dirty" ] || die "llama.cpp source tree does not match $LLAMA_COMMIT ($LLAMA_TAG) — the checkout carries local changes, so the build would not be the pinned source:
$dirty"
}

# sha256 of a file, or "" where no hasher is on PATH. macOS ships `shasum`,
# Linux and Git-Bash ship `sha256sum`; neither is guaranteed on the other.
sha256_of() {
  local line hash
  if command -v shasum >/dev/null 2>&1; then
    line="$(shasum -a 256 "$1")"
  elif command -v sha256sum >/dev/null 2>&1; then
    line="$(sha256sum "$1")"
  else
    return 0
  fi
  # The leading backslash is not noise and not a fluke: GNU coreutils prefixes
  # the WHOLE line with `\` whenever it had to escape the file name (`\` → `\\`,
  # newline → `\n`), which under Git Bash on Windows is every single call,
  # because the paths there contain backslashes. Taking $1 verbatim then yields
  # `\5ec30eef…` — and this digest is the record of the binary that ships
  # signed with the app, so one foreign character makes it compare unequal
  # forever. Strip that one marker byte, then cut at the separator: whatever
  # escaping GNU applied lives in the NAME, behind the separator, and is never
  # part of the hash — so only the hash field needs looking at.
  hash="${line#\\}"
  hash="${hash%% *}"
  # Anything that is not exactly 64 lowercase hex is not a digest. Report
  # nothing rather than something wrong — the caller prints "unavailable".
  case "$hash" in
    *[!0-9a-f]* | "") return 0 ;;
  esac
  [ "${#hash}" -eq 64 ] || return 0
  printf '%s\n' "$hash"
}

# cmake is checked HERE, at the compiler, and deliberately NOT in ensure_src.
# ensure_src does git work only — clone, check out the pinned commit, verify
# that HEAD and the working tree really are that commit — and it never invokes
# a compiler. Guarding it with a cmake check made the supply-chain
# VERIFICATION unrunnable on every machine without cmake (a stock Windows box,
# a reviewer who only wants to re-check the pin), for a tool it does not use.
# Every path that reaches `cmake` below goes through this function, so the
# build still stops with the same message and nothing gets built without it.
require_cmake() {
  command -v cmake >/dev/null 2>&1 \
    || die "cmake not found — install it (macOS: brew install cmake, Windows: winget install Kitware.CMake)"
}

# K1 (3.0.1): for a dynamic-ISA triple, `llama-server` no longer stands
# alone: GGML_BACKEND_DL/GGML_CPU_ALL_VARIANTS build it next to a
# ggml-cpu-<variant>.{dll,so} per CPU tier plus ggml-vulkan and the base
# ggml/llama runtime libraries, ALL written into the executable's own build
# output directory (ggml/src/CMakeLists.txt:269 pins every backend MODULE's
# LIBRARY_OUTPUT_DIRECTORY to the same CMAKE_RUNTIME_OUTPUT_DIRECTORY the
# exe uses). None of that is guessed or hardcoded here: whatever cmake
# actually built next to the exe is what gets staged, so a variant list
# upstream adds or drops later is picked up automatically.
#
# A copy, not a symlink: Linux SONAME resolution needs the exact versioned
# filename the loader was linked against (e.g. libggml-base.so.1), which is
# commonly a symlink to the real file. Plain `cp` (no -P/-d) dereferences, so
# every matched name becomes its own real file, a little larger on disk, but
# nothing a resource bundler or an installer can leave dangling.
#
# A standalone function (not inlined in build_triple) so it can be unit
# tested against a directory of fake .dll/.so files, without paying for a
# real cmake build to check the staging logic itself. Prints one
# "path: digest" line per file it staged, plus the exe's own; empty stdin/no
# output means "not a dynamic-ISA triple, nothing to stage" and is not an
# error.
stage_dynamic_isa_companions() {
  local triple="$1" bin_out_dir="$2" exe_out="$3"
  is_dynamic_isa_triple "$triple" || return 0
  local companions_dir; companions_dir="$(resource_llama_dir_for "$triple")"
  rm -rf "$companions_dir"
  mkdir -p "$companions_dir"
  local lib_glob
  case "$triple" in
    *-windows-*) lib_glob='*.dll' ;;
    *)           lib_glob='*.so*' ;;
  esac
  local found_any=""
  local lib
  while IFS= read -r lib; do
    [ -n "$lib" ] || continue
    found_any=1
    local lib_out="$companions_dir/$(basename "$lib")"
    cp "$lib" "$lib_out"
    local lib_digest; lib_digest="$(sha256_of "$lib_out")"
    printf '%s: %s\n' "$lib_out" "${lib_digest:-unavailable}"
  # -L: follow symlinks so `-type f` also matches them. Without it, both BSD
  # find (macOS, where this runs in dev/tests) and GNU find (the Linux
  # runner) skip a symlink even when it points at a regular file, and Linux's
  # own SONAME symlinks (libggml-base.so -> libggml-base.so.1 ->
  # libggml-base.so.1.2.3) are exactly that: only the fully-versioned real
  # file would be found, and the literal SONAME the dynamic linker actually
  # looks for would be silently missing from what gets staged. Measured, not
  # assumed: caught by the Linux companion-staging test below, red without
  # this flag.
  done < <(find -L "$bin_out_dir" -maxdepth 1 -type f -iname "$lib_glob")
  [ -n "$found_any" ] \
    || die "GGML_BACKEND_DL build for $triple produced no $lib_glob next to $exe_out: the dynamic CPU-variant libraries are missing, the sidecar would only run on the build host's own CPU"

  # Belt and suspenders for BLOCKER B3, Linux only: CMAKE_BUILD_RPATH_USE_ORIGIN
  # (see cmake_flags_for) should already have made every .so carry an
  # $ORIGIN-relative RPATH, but that flag depends on the cmake/linker version
  # on the build host honouring it. Force the point with patchelf when it is
  # on PATH, so the staged, shippable copy is right even if the build-time
  # flag was silently ignored upstream. Best-effort: patchelf is not
  # installed on every dev machine, only on the Linux CI runner (release.yml
  # already apt-gets it), and this repo does not want a build TOOL to be a
  # hard requirement for staging files that were already produced.
  case "$triple" in
    *-linux-*)
      if command -v patchelf >/dev/null 2>&1; then
        while IFS= read -r staged_so; do
          patchelf --set-rpath '$ORIGIN' "$staged_so" 2>/dev/null || true
        done < <(find "$companions_dir" -maxdepth 1 -type f -iname '*.so*')
      fi
      ;;
  esac
}

build_triple() {
  require_cmake
  local triple="$1"
  local build_dir="$CACHE_DIR/build-$triple"
  local flags; flags="$(cmake_flags_for "$triple")"
  log "configuring $triple  ($flags)"
  # shellcheck disable=SC2086
  cmake -S "$SRC_DIR" -B "$build_dir" $flags
  log "building llama-server for $triple"
  # Bare `-j` (no count) lets Make fork a compile per ready target and OOM-kills
  # CI runners mid llama.cpp.o (SIGTERM 143). Cap to a finite, memory-safe count;
  # CI lowers it further via BUILD_JOBS=2.
  cmake --build "$build_dir" --config Release --target llama-server -j "${BUILD_JOBS:-4}"
  # macOS also ships llama-quantize (lu-llama-quantize, tauri.macos.conf.json):
  # the refusal-removal tool (A14) writes its copy in the original's quant
  # type with it. Same static Metal build, same source tree. Windows and
  # Linux do not ship it yet; the tool writes Q8_0 there instead.
  if quantize_ships_for "$triple"; then
    cmake --build "$build_dir" --config Release --target llama-quantize -j "${BUILD_JOBS:-4}"
  fi
  if cvector_ships_for "$triple"; then
    cmake --build "$build_dir" --config Release --target llama-cvector-generator -j "${BUILD_JOBS:-4}"
  fi
  # Locate the produced binary (path differs by generator/platform).
  local built
  built="$(find "$build_dir" -type f \( -name 'llama-server' -o -name 'llama-server.exe' \) -print -quit)"
  [ -n "$built" ] || die "llama-server binary not found under $build_dir"
  mkdir -p "$BIN_DIR"
  local out="$BIN_DIR/$(out_name_for "$triple")"
  cp "$built" "$out"
  chmod +x "$out"
  if quantize_ships_for "$triple"; then
    local built_q
    built_q="$(find "$build_dir" -type f -name 'llama-quantize' -print -quit)"
    [ -n "$built_q" ] || die "llama-quantize binary not found under $build_dir"
    cp "$built_q" "$BIN_DIR/$(quantize_out_name_for "$triple")"
    chmod +x "$BIN_DIR/$(quantize_out_name_for "$triple")"
  fi
  if cvector_ships_for "$triple"; then
    local built_cv
    built_cv="$(find "$build_dir" -type f \( -name 'llama-cvector-generator' -o -name 'llama-cvector-generator.exe' \) -print -quit)"
    [ -n "$built_cv" ] || die "llama-cvector-generator binary not found under $build_dir"
    cp "$built_cv" "$BIN_DIR/$(cvector_out_name_for "$triple")"
    chmod +x "$BIN_DIR/$(cvector_out_name_for "$triple")"
  fi

  local out_digest; out_digest="$(sha256_of "$out")"
  local digest_lines="$out: ${out_digest:-unavailable}"
  local companion_lines
  companion_lines="$(stage_dynamic_isa_companions "$triple" "$(dirname "$built")" "$out")"
  [ -z "$companion_lines" ] || digest_lines="$digest_lines
$companion_lines"

  # Record what actually got produced. A from-source build is not bit-for-bit
  # reproducible across machines, so none of these can be pinned to a
  # constant, but the digest of every file that ships, next to the source
  # revision they came from, is what an "which binaries were those?" question
  # after the fact needs. A list now, not a single line: the pin check in
  # ensure_src/assert_clean_tree verifies the SOURCE TREE once per run and
  # already covers every file this step produces (nothing here compiles from
  # anything outside $SRC_DIR), but the digest log is per-OUTPUT-FILE by
  # nature, so a multi-file build means a multi-line log, not a new pin
  # mechanism.
  log "installed (llama.cpp $LLAMA_TAG @ ${LLAMA_COMMIT:0:12}):"
  while IFS= read -r line; do log "  $line"; done <<<"$digest_lines"
}

# Boot the host binary and probe /health on an ephemeral port. Without a
# model llama-server starts in router mode (no weights loaded), so /health
# answers 200 on any machine.
#
# K1 (3.0.1): for a dynamic-ISA triple this MUST run the same way engine.rs
# spawns it in the app: cwd set to the resource directory holding the
# ggml-cpu-*/ggml-vulkan companion libraries, nothing copied next to the exe
# because ggml_backend_load_best only scans the executable's own directory
# and the process's current directory (ggml-backend-reg.cpp:479-486). A check
# that ran the bare exe from $BIN_DIR would pass on a build host that also
# happens to have those libraries lying around and prove nothing about the
# layout a real install actually has.
check_binary() {
  local triple; triple="$(host_triple)"
  local bin="$BIN_DIR/$(out_name_for "$triple")"
  [ -x "$bin" ] || die "no built binary at $bin — build first"
  local run_dir="$BIN_DIR"
  if is_dynamic_isa_triple "$triple"; then
    run_dir="$(resource_llama_dir_for "$triple")"
    [ -d "$run_dir" ] || die "no companion libraries at $run_dir, build first"
  fi
  # N1: the exe itself (in $BIN_DIR) and its companion libraries (in
  # $run_dir) live in DIFFERENT directories once bundled (deb/AppImage), the
  # same split engine.rs's apply_engine_backend_dir sets LD_LIBRARY_PATH for
  # at the real spawn site. cwd alone (what this check used before) only
  # covers the dlopen'd ggml-cpu-*/ggml-vulkan companions, which ggml itself
  # searches for beside the exe and in cwd (ggml-backend-reg.cpp:479-486);
  # it does not cover the exe's own DT_NEEDED libs (libggml-base.so etc, on
  # a triple where $ORIGIN does not reach across directories), which the
  # loader needs before main() ever runs. Mirror the real environment here
  # too, or this check can pass for a reason the shipped app does not share.
  if [ "${triple}" = "x86_64-unknown-linux-gnu" ]; then
    local ld_path="$run_dir"
    [ -z "${LD_LIBRARY_PATH:-}" ] || ld_path="$run_dir:$LD_LIBRARY_PATH"
    export LD_LIBRARY_PATH="$ld_path"
  fi
  ( cd "$run_dir" && "$bin" --version >/dev/null 2>&1 ) || die "$bin --version failed (run from $run_dir, LD_LIBRARY_PATH=${LD_LIBRARY_PATH:-unset})"
  # BUILD_LLAMA_CHECK_PORT only for build-llama-script.test.ts, which takes a
  # free port so a server already on 8129 cannot answer for the one under test.
  local port="${BUILD_LLAMA_CHECK_PORT:-8129}"
  log "boot check: $bin on 127.0.0.1:$port, cwd=$run_dir (no model, router mode, /health only)"
  # exec: $! has to be the server itself. Without it $! was the subshell, the
  # kill below ended only that, and a check that failed (E1: the 9 s Metal
  # first start) left a llama-server holding port 8129 behind.
  ( cd "$run_dir" && exec "$bin" --host 127.0.0.1 --port "$port" >/dev/null 2>&1 ) &
  local pid=$!
  trap 'kill "$pid" 2>/dev/null || true' EXIT
  local ok=""
  # E1 (b11960): the first start of a freshly built Metal binary compiles its
  # embedded shader libraries (measured 9.3 s on an M5 Pro, "loaded 36
  # libraries ... in 9.314 sec"; later starts come out of the system's shader
  # cache in 0.3 s). The 9 s this loop used to allow is exactly that first
  # start, so it waits up to 60 s now.
  # BUILD_LLAMA_CHECK_TRIES only for build-llama-script.test.ts.
  for _ in $(seq 1 "${BUILD_LLAMA_CHECK_TRIES:-200}"); do
    if curl -fsS "http://127.0.0.1:$port/health" >/dev/null 2>&1; then ok=1; break; fi
    sleep 0.3
  done
  kill "$pid" 2>/dev/null || true
  trap - EXIT
  [ -n "$ok" ] || die "health endpoint never came up"
  log "OK — llama-server boots and answers /health"
}

main() {
  if [ "${1:-}" = "--check" ]; then check_binary; exit 0; fi
  local targets=("$@")
  if [ "${#targets[@]}" -eq 0 ]; then targets=("$(host_triple)"); fi
  # Fail fast, exactly as before: a build without cmake aborts here, before the
  # clone/fetch, instead of after it. build_triple re-checks for any other
  # caller — this line is about the ordering, not about the guarantee.
  require_cmake
  ensure_src
  for t in "${targets[@]}"; do build_triple "$t"; done
  log "done: ${targets[*]}"
}

# Only run when executed directly, so tests can source the pure functions.
if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
  main "$@"
fi