xcframework: CI, rolling release, arm64-only simulators, docs

apocryphx · claude · apocryphx · commit faa05ea19df9 · 2026-04-15T12:51:55.000-07:00
Follow-up polish on the fork's Apple-platform build:

1. CI workflow (.github/workflows/fork-xcframework-release.yml)
   Rebuilds the xcframework on push to master, weekly, and on-demand.
   Uploads a zip as a 30-day Actions artifact and publishes to a
   rolling "latest" prerelease so downstream consumers can curl
   a prebuilt framework without cloning the repo.

2. Drop x86_64 from iOS/visionOS/tvOS simulator slices
   Every modern Xcode Simulator runs arm64-on-arm64 on Apple Silicon.
   The x86_64 sim slice was dead weight — halves simulator build times
   and binary size. macOS keeps the Intel slice since real Intel Macs
   are still in use. Slice names change from e.g.
   "ios-arm64_x86_64-simulator" to "ios-arm64-simulator".

3. README: codesigning section
   Documents that the xcframework ships unsigned on purpose and that
   consumers must set "Embed &amp; Sign" in Xcode. Prevents the common
   mistake of pre-signing before embedding, which archive validation
   rejects.

4. README: prebuilt download section
   Points consumers at the rolling "latest" release from (1) instead
   of making them build from source.

5. .gitignore: /.claude/
   Prevents accidental commits of Claude Code workspace state.

Sanity-verified locally by reconfiguring and building the arm64-only
iOS simulator slice — libllama.a / libggml-metal.a produced as
non-fat arm64 archives.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/fork-xcframework-release.yml b/.github/workflows/fork-xcframework-release.yml
@@ -0,0 +1,115 @@
+name: Fork — xcframework build & rolling release
+
+# Fork-specific workflow for apocryphx/llama.cpp. Builds the Apple
+# xcframework using the Ninja-patched build-xcframework.sh and publishes
+# it to the rolling "latest" prerelease so downstream consumers can curl
+# a prebuilt zip.
+#
+# Separate from upstream's build-apple.yml so upstream syncs don't
+# clobber it. See README.md § "Downloading a prebuilt xcframework".
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [master]
+    paths:
+      - 'build-xcframework.sh'
+      - 'CMakeLists.txt'
+      - 'ggml/**'
+      - 'src/**'
+      - 'include/**'
+      - 'common/**'
+      - '.github/workflows/fork-xcframework-release.yml'
+  schedule:
+    # Weekly rebuild so the "latest" asset doesn't go stale against
+    # upstream security/bugfix releases.
+    - cron: '17 7 * * 1'
+
+concurrency:
+  group: fork-xcframework-release
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: macos-latest
+    timeout-minutes: 60
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Xcode
+        uses: ggml-org/setup-xcode@v1
+        with:
+          xcode-version: latest-stable
+
+      - name: Install Ninja + ensure CMake 4.x
+        run: |
+          brew install ninja
+          brew upgrade cmake || brew install cmake
+          cmake --version
+          ninja --version
+          xcodebuild -version
+
+      - name: Build xcframework
+        run: |
+          ./build-xcframework.sh
+
+      - name: Capture build metadata
+        id: meta
+        run: |
+          set -e
+          UPSTREAM_TAG=$(git describe --tags --abbrev=0 --match 'b*' 2>/dev/null || echo "unknown")
+          COMMIT_SHORT=$(git rev-parse --short HEAD)
+          BUILD_DATE=$(date -u +%Y-%m-%d)
+          {
+            echo "upstream_tag=$UPSTREAM_TAG"
+            echo "commit_short=$COMMIT_SHORT"
+            echo "build_date=$BUILD_DATE"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Zip xcframework
+        run: |
+          cd build-apple
+          zip -r -y ../llama.xcframework.zip llama.xcframework
+          cd ..
+          ls -lh llama.xcframework.zip
+          shasum -a 256 llama.xcframework.zip | tee llama.xcframework.zip.sha256
+
+      - name: Upload workflow artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: llama-xcframework-${{ steps.meta.outputs.commit_short }}
+          path: |
+            llama.xcframework.zip
+            llama.xcframework.zip.sha256
+          retention-days: 30
+
+      - name: Publish rolling "latest" prerelease
+        if: github.event_name != 'pull_request'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: latest
+          name: "Rolling build (${{ steps.meta.outputs.build_date }})"
+          body: |
+            Automatically rebuilt xcframework on every push to `master` and weekly.
+
+            - upstream tag: `${{ steps.meta.outputs.upstream_tag }}`
+            - fork commit: `${{ steps.meta.outputs.commit_short }}`
+            - built: ${{ steps.meta.outputs.build_date }}
+            - slices: ios-arm64, ios-arm64-simulator, macos-arm64_x86_64, xros-arm64, xros-arm64-simulator, tvos-arm64, tvos-arm64-simulator
+
+            ```
+            curl -LO https://github.com/${{ github.repository }}/releases/download/latest/llama.xcframework.zip
+            unzip llama.xcframework.zip
+            ```
+
+            SHA-256: see `llama.xcframework.zip.sha256`.
+          prerelease: true
+          make_latest: false
+          files: |
+            llama.xcframework.zip
+            llama.xcframework.zip.sha256
diff --git a/.gitignore b/.gitignore
@@ -143,5 +143,6 @@ poetry.toml
 # IDE
 /*.code-workspace
 /.windsurf/
+/.claude/
 # emscripten
 a.out.*
diff --git a/README.md b/README.md
@@ -26,6 +26,17 @@ CMake Error at ggml/src/ggml-cpu/CMakeLists.txt:57 (target_compile_features):
 
 The failure reproduces against `upstream/master`, verified 2026-04-15. Ninja bypasses it entirely because it does not rely on Xcode's toolchain detection for cross-SDK builds. The resulting xcframework is equivalent — the Xcode-specific `-DCMAKE_XCODE_ATTRIBUTE_*` arguments in `COMMON_CMAKE_ARGS` are harmless no-ops under Ninja, so they were left alone rather than stripped.
 
+## Downloading a prebuilt xcframework
+
+GitHub Actions rebuilds the xcframework on every push to `master` and on a weekly schedule. The latest artifact is attached to a rolling prerelease tagged `latest`:
+
+```bash
+curl -LO https://github.com/apocryphx/llama.cpp/releases/download/latest/llama.xcframework.zip
+unzip llama.xcframework.zip
+```
+
+Drag `llama.xcframework` into your Xcode project's *Frameworks, Libraries, and Embedded Content* section. Each workflow run also uploads the zip as a 30-day Actions artifact if you need a specific build.
+
 ## Building the xcframework
 
 ```bash
@@ -37,12 +48,14 @@ Output: `build-apple/llama.xcframework/` containing 7 slices:
 | Slice | Architectures |
 |---|---|
 | `ios-arm64` | arm64 |
-| `ios-arm64_x86_64-simulator` | arm64, x86_64 |
+| `ios-arm64-simulator` | arm64 |
 | `macos-arm64_x86_64` | arm64, x86_64 |
 | `xros-arm64` | arm64 |
-| `xros-arm64_x86_64-simulator` | arm64, x86_64 |
+| `xros-arm64-simulator` | arm64 |
 | `tvos-arm64` | arm64 |
-| `tvos-arm64_x86_64-simulator` | arm64, x86_64 |
+| `tvos-arm64-simulator` | arm64 |
+
+Simulator slices are **arm64-only** — every modern Xcode Simulator runs arm64-on-arm64 on Apple Silicon. The x86_64 simulator slice has been dropped to halve simulator build times and binary sizes. macOS keeps the Intel slice since real Intel Macs are still in use.
 
 Mac Catalyst is **not** in the xcframework — CMake's cross-compile flags conflict when combining both Catalyst architectures in a single configure step. See [APPLE-PLATFORMS-BUILD.md](APPLE-PLATFORMS-BUILD.md) for the manual lipo workflow.
 
@@ -64,7 +77,7 @@ CMake Warning at ggml/src/ggml-cpu/CMakeLists.txt:558 (message):
   Unknown CPU architecture.  Falling back to generic implementations.
 ```
 
-This is **not** a Metal fallback. It fires only when x86_64 is part of the architecture list (iOS sim, macOS, visionOS sim, tvOS sim) and means the x86_64 **CPU backend** slice uses generic scalar kernels instead of AVX/AVX2. The arm64 CPU backend and the Metal backend are unaffected. For shipping on Apple Silicon devices this warning is cosmetic — no one runs production inference on an x86_64 simulator.
+This is **not** a Metal fallback. It fires only when x86_64 is part of the architecture list (now just the `macos-arm64_x86_64` slice) and means the x86_64 **CPU backend** slice uses generic scalar kernels instead of AVX/AVX2. The arm64 CPU backend and the Metal backend are unaffected. For shipping on Apple Silicon devices this warning is cosmetic.
 
 ### Requirements
 
@@ -100,6 +113,18 @@ Reference numbers from the 2026-04-15 verification (SmolLM2-135M-Instruct Q4_K_M
 
 The xcframework slices contain identical Metal backend code — same `_ggml_metallib_start`/`_end` symbols, same 110 kernels — so a working host Metal build is a reliable proxy for the framework slices.
 
+## Code signing
+
+**The xcframework is unsigned.** `build-xcframework.sh` sets `CODE_SIGNING_ALLOWED=NO` on purpose — a redistributable framework must not carry its own signature, because the consuming app has to re-sign embedded binaries with its own Team ID at archive time. This is the expected pattern for distributing a third-party `.xcframework`.
+
+When you embed `llama.xcframework` in an Xcode project:
+
+- In the *Frameworks, Libraries, and Embedded Content* section, set *Embed* to **Embed & Sign**. Xcode will sign the embedded `llama.framework` with your app's signing identity during the build.
+- No action needed in your entitlements — the framework uses only public `Metal.framework` / `Accelerate.framework` APIs.
+- For distribution outside the App Store (Developer ID / notarization), the framework will be signed and notarized as part of your app's archive, not separately.
+
+If Xcode refuses to build with a signature error, the fix is almost always switching *Embed* from *Do Not Embed* to *Embed & Sign*. Do **not** pre-sign the framework with `codesign` before embedding — that produces nested signatures that archive validation rejects.
+
 ## Syncing with upstream
 
 ```bash
diff --git a/build-xcframework.sh b/build-xcframework.sh
@@ -270,7 +270,7 @@ combine_static_libraries() {
         "ios")
             if [[ "$is_simulator" == "true" ]]; then
                 sdk="iphonesimulator"
-                archs="arm64 x86_64"
+                archs="arm64"
                 min_version_flag="-mios-simulator-version-min=${IOS_MIN_OS_VERSION}"
             else
                 sdk="iphoneos"
@@ -288,7 +288,7 @@ combine_static_libraries() {
         "visionos")
             if [[ "$is_simulator" == "true" ]]; then
                 sdk="xrsimulator"
-                archs="arm64 x86_64"
+                archs="arm64"
                 min_version_flag="-mtargetos=xros${VISIONOS_MIN_OS_VERSION}-simulator"
             else
                 sdk="xros"
@@ -301,7 +301,7 @@ combine_static_libraries() {
         "tvos")
             if [[ "$is_simulator" == "true" ]]; then
                 sdk="appletvsimulator"
-                archs="arm64 x86_64"
+                archs="arm64"
                 min_version_flag="-mtvos-simulator-version-min=${TVOS_MIN_OS_VERSION}"
             else
                 sdk="appletvos"
@@ -408,7 +408,7 @@ cmake -B build-ios-sim -G Ninja \
     -DIOS=ON \
     -DCMAKE_SYSTEM_NAME=iOS \
     -DCMAKE_OSX_SYSROOT=iphonesimulator \
-    -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64" \
+    -DCMAKE_OSX_ARCHITECTURES="arm64" \
     -DCMAKE_XCODE_ATTRIBUTE_SUPPORTED_PLATFORMS=iphonesimulator \
     -DCMAKE_C_FLAGS="${COMMON_C_FLAGS}" \
     -DCMAKE_CXX_FLAGS="${COMMON_CXX_FLAGS}" \
@@ -460,7 +460,7 @@ echo "Building for visionOS simulator..."
 cmake -B build-visionos-sim -G Ninja \
     "${COMMON_CMAKE_ARGS[@]}" \
     -DCMAKE_OSX_DEPLOYMENT_TARGET=${VISIONOS_MIN_OS_VERSION} \
-    -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64" \
+    -DCMAKE_OSX_ARCHITECTURES="arm64" \
     -DCMAKE_SYSTEM_NAME=visionOS \
     -DCMAKE_OSX_SYSROOT=xrsimulator \
     -DCMAKE_XCODE_ATTRIBUTE_SUPPORTED_PLATFORMS=xrsimulator \
@@ -478,7 +478,7 @@ cmake -B build-tvos-sim -G Ninja \
     -DCMAKE_OSX_DEPLOYMENT_TARGET=${TVOS_MIN_OS_VERSION} \
     -DCMAKE_SYSTEM_NAME=tvOS \
     -DCMAKE_OSX_SYSROOT=appletvsimulator \
-    -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64" \
+    -DCMAKE_OSX_ARCHITECTURES="arm64" \
     -DGGML_METAL=ON \
     -DCMAKE_XCODE_ATTRIBUTE_SUPPORTED_PLATFORMS=appletvsimulator \
     -DCMAKE_C_FLAGS="${COMMON_C_FLAGS}" \
