From 04e3d04ab8b21cdc2e7f7126379431c17efc24dc Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Mon, 22 Jun 2026 09:22:36 +0000 Subject: [PATCH] build(llama-cpp): isolate paged patches in patches/paged/ behind LLAMA_PAGED flag (default on) Move the paged-attention patch series (0001-0004 + docs) into patches/paged/, applied behind a new LLAMA_PAGED build flag (default on). The base patches/ dir is now clean, so a dep-bump that breaks a paged hook can be unblocked with LLAMA_PAGED=off (clean-against-upstream build) and the paged carry fixed independently - decoupling the paged-KV maintenance from routine bumps without a separate backend. Both apply paths wired (Makefile git-apply + prepare.sh re-apply, flag passed through). Runtime stays gated by LLAMA_KV_PAGED env, so an on build is byte-identical to stock until that env is set. Glob/flag logic verified in bash. Assisted-by: Claude:opus-4.8 [Claude Code] Signed-off-by: Ettore Di Giacinto --- backend/cpp/llama-cpp/Makefile | 23 ++++++++++++++++--- .../0001-vendor-paged-kv-manager.patch | 0 ...v-block-placement-env-LLAMA_KV_PAGED.patch | 0 .../{ => paged}/0003-gather-read-plan.md | 0 ...paged-gather-read-env-LLAMA_KV_PAGED.patch | 0 ...-block-allocation-env-LLAMA_KV_PAGED.patch | 0 .../patches/{ => paged}/ADDITIVE_DESIGN.md | 0 backend/cpp/llama-cpp/prepare.sh | 19 +++++++++++---- 8 files changed, 35 insertions(+), 7 deletions(-) rename backend/cpp/llama-cpp/patches/{ => paged}/0001-vendor-paged-kv-manager.patch (100%) rename backend/cpp/llama-cpp/patches/{ => paged}/0002-paged-kv-block-placement-env-LLAMA_KV_PAGED.patch (100%) rename backend/cpp/llama-cpp/patches/{ => paged}/0003-gather-read-plan.md (100%) rename backend/cpp/llama-cpp/patches/{ => paged}/0003-paged-gather-read-env-LLAMA_KV_PAGED.patch (100%) rename backend/cpp/llama-cpp/patches/{ => paged}/0004-paged-on-demand-block-allocation-env-LLAMA_KV_PAGED.patch (100%) rename backend/cpp/llama-cpp/patches/{ => paged}/ADDITIVE_DESIGN.md (100%) diff --git a/backend/cpp/llama-cpp/Makefile b/backend/cpp/llama-cpp/Makefile index 36dd88457..bbb5443a8 100644 --- a/backend/cpp/llama-cpp/Makefile +++ b/backend/cpp/llama-cpp/Makefile @@ -1,6 +1,14 @@ LLAMA_VERSION?=f3e182816421c648188b5eab269853bf1531d950 LLAMA_REPO?=https://github.com/ggerganov/llama.cpp +# LLAMA_PAGED controls whether the vendored paged-attention patch series +# (patches/paged/) is applied on top of the pinned llama.cpp. Default on; set +# LLAMA_PAGED=off to build a clean-against-upstream backend (e.g. to unblock a +# dep-bump if an upstream change breaks a paged hook - the paged carry is then +# fixed independently). Runtime behaviour stays gated by the LLAMA_KV_PAGED env +# regardless, so an LLAMA_PAGED=on build is byte-identical to stock until that +# env is set. +LLAMA_PAGED?=on CMAKE_ARGS?= BUILD_TYPE?= @@ -142,14 +150,23 @@ llama.cpp: [ -e "$$p" ] || continue; \ echo "applying llama.cpp patch: $$p"; \ git apply --verbose "$$p" || { echo "patch failed: $$p"; exit 1; }; \ - done + done && \ + if [ "$(LLAMA_PAGED)" = "off" ]; then \ + echo "LLAMA_PAGED=off: skipping paged-attention patch series"; \ + else \ + for p in $(CURRENT_MAKEFILE_DIR)patches/paged/0*.patch; do \ + [ -e "$$p" ] || continue; \ + echo "applying llama.cpp PAGED patch: $$p"; \ + git apply --verbose "$$p" || { echo "paged patch failed: $$p"; exit 1; }; \ + done; \ + fi llama.cpp/tools/grpc-server: llama.cpp mkdir -p llama.cpp/tools/grpc-server - bash prepare.sh + LLAMA_PAGED=$(LLAMA_PAGED) bash prepare.sh rebuild: - bash prepare.sh + LLAMA_PAGED=$(LLAMA_PAGED) bash prepare.sh rm -rf grpc-server $(MAKE) grpc-server diff --git a/backend/cpp/llama-cpp/patches/0001-vendor-paged-kv-manager.patch b/backend/cpp/llama-cpp/patches/paged/0001-vendor-paged-kv-manager.patch similarity index 100% rename from backend/cpp/llama-cpp/patches/0001-vendor-paged-kv-manager.patch rename to backend/cpp/llama-cpp/patches/paged/0001-vendor-paged-kv-manager.patch diff --git a/backend/cpp/llama-cpp/patches/0002-paged-kv-block-placement-env-LLAMA_KV_PAGED.patch b/backend/cpp/llama-cpp/patches/paged/0002-paged-kv-block-placement-env-LLAMA_KV_PAGED.patch similarity index 100% rename from backend/cpp/llama-cpp/patches/0002-paged-kv-block-placement-env-LLAMA_KV_PAGED.patch rename to backend/cpp/llama-cpp/patches/paged/0002-paged-kv-block-placement-env-LLAMA_KV_PAGED.patch diff --git a/backend/cpp/llama-cpp/patches/0003-gather-read-plan.md b/backend/cpp/llama-cpp/patches/paged/0003-gather-read-plan.md similarity index 100% rename from backend/cpp/llama-cpp/patches/0003-gather-read-plan.md rename to backend/cpp/llama-cpp/patches/paged/0003-gather-read-plan.md diff --git a/backend/cpp/llama-cpp/patches/0003-paged-gather-read-env-LLAMA_KV_PAGED.patch b/backend/cpp/llama-cpp/patches/paged/0003-paged-gather-read-env-LLAMA_KV_PAGED.patch similarity index 100% rename from backend/cpp/llama-cpp/patches/0003-paged-gather-read-env-LLAMA_KV_PAGED.patch rename to backend/cpp/llama-cpp/patches/paged/0003-paged-gather-read-env-LLAMA_KV_PAGED.patch diff --git a/backend/cpp/llama-cpp/patches/0004-paged-on-demand-block-allocation-env-LLAMA_KV_PAGED.patch b/backend/cpp/llama-cpp/patches/paged/0004-paged-on-demand-block-allocation-env-LLAMA_KV_PAGED.patch similarity index 100% rename from backend/cpp/llama-cpp/patches/0004-paged-on-demand-block-allocation-env-LLAMA_KV_PAGED.patch rename to backend/cpp/llama-cpp/patches/paged/0004-paged-on-demand-block-allocation-env-LLAMA_KV_PAGED.patch diff --git a/backend/cpp/llama-cpp/patches/ADDITIVE_DESIGN.md b/backend/cpp/llama-cpp/patches/paged/ADDITIVE_DESIGN.md similarity index 100% rename from backend/cpp/llama-cpp/patches/ADDITIVE_DESIGN.md rename to backend/cpp/llama-cpp/patches/paged/ADDITIVE_DESIGN.md diff --git a/backend/cpp/llama-cpp/prepare.sh b/backend/cpp/llama-cpp/prepare.sh index f9b7e3dd2..75aaa8875 100644 --- a/backend/cpp/llama-cpp/prepare.sh +++ b/backend/cpp/llama-cpp/prepare.sh @@ -2,12 +2,23 @@ ## Patches -## Apply patches from the `patches` directory +## Apply patches: the base `patches/` series, then the gated `patches/paged/` +## series (default on; LLAMA_PAGED=off skips it). Runs before `set -e` so a +## re-apply on rebuild is tolerated. Only *.patch files are applied (docs/dirs +## like patches/paged/ and *.md are skipped). if [ -d "patches" ]; then - for patch in $(ls patches); do + for patch in patches/*.patch; do + [ -e "$patch" ] || continue echo "Applying patch $patch" - patch -d llama.cpp/ -p1 < patches/$patch - done + patch -d llama.cpp/ -p1 < "$patch" + done + if [ "${LLAMA_PAGED:-on}" != "off" ] && [ -d "patches/paged" ]; then + for patch in patches/paged/*.patch; do + [ -e "$patch" ] || continue + echo "Applying paged patch $patch" + patch -d llama.cpp/ -p1 < "$patch" + done + fi fi set -e