Build for iOS (Experimental)

Step-by-step instructions for cross-compiling llama.cpp for iOS (ARM64) for use with GenAI Llama’s embedded inference.

Prerequisites

macOS with Xcode installed (includes the iOS SDK and toolchain)
CMake 3.14 or later
```
brew install cmake
```
Git

GPU Backend

Backend	Notes
Metal	Hardware accelerated on all Apple Silicon iOS devices (A7 and later). Recommended.
CPU	Always works, significantly slower.

All modern iPhones and iPads support Metal. There is no reason to build CPU-only for iOS unless you need to debug a Metal-specific issue.

Build Steps

1. Clone llama.cpp

git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
git checkout b3600  # or any later release tag

2. Configure and Build

Metal (Recommended)

cmake -B build \
  -DCMAKE_SYSTEM_NAME=iOS \
  -DCMAKE_OSX_ARCHITECTURES=arm64 \
  -DBUILD_SHARED_LIBS=OFF \
  -DGGML_METAL=ON
cmake --build build --config Release

CPU Only

cmake -B build \
  -DCMAKE_SYSTEM_NAME=iOS \
  -DCMAKE_OSX_ARCHITECTURES=arm64 \
  -DBUILD_SHARED_LIBS=OFF
cmake --build build --config Release

Simulator Builds

If you need to test on the iOS Simulator (Apple Silicon Mac), add -DCMAKE_OSX_SYSROOT=iphonesimulator to the cmake command. Note that Unreal Engine's iOS packaging targets real devices, not the simulator.

3. Copy Libraries

Copy all .a files from build/ (and its subdirectories) into your plugin directory:

<YourProject>/Plugins/GenAILlama/ThirdParty/LlamaCpp/lib/IOS/

find build -name "*.a" -exec cp {} /path/to/ThirdParty/LlamaCpp/lib/IOS/ \;

The plugin automatically links the required Apple frameworks (Accelerate, Metal, MetalKit, Foundation) when building for iOS.

4. Rebuild Your Unreal Project

After placing the files, rebuild your Unreal project targeting iOS. Check the build log for:

GenAILlama: llama.cpp libraries found at <path>. Embedded inference enabled.

Model Size Considerations

iOS devices have limited RAM. Choose models carefully to avoid system termination:

Model	Q4_K_M Size	RAM Usage (Approx.)	Recommended For
Qwen2.5-0.5B	~400 MB	~600 MB	iPhone / iPad (any)
TinyLlama 1.1B	~637 MB	~900 MB	iPhone 12+ / iPad Air+
Gemma-2B	~1.4 GB	~2 GB	iPhone 14 Pro+ / iPad Pro

Memory Warning

iOS aggressively terminates apps that use too much memory. Test on real devices with representative model sizes. Use smaller quantizations (Q4_K_M or Q4_K_S) to reduce memory usage.

Troubleshooting

CMake fails to find iOS SDK

Ensure Xcode is installed (not just Command Line Tools).
Run sudo xcode-select -s /Applications/Xcode.app to set the active developer directory.

Linker errors about missing symbols

Verify you built with the iOS toolchain (CMAKE_SYSTEM_NAME=iOS), not the macOS default.
Ensure all .a files were copied (including libggml-metal.a for Metal builds).

App terminated on device

Check memory usage — the model may be too large for the device.
Reduce Context Size and use smaller models.

Muddy Terrain Games