From c6eebf62c2238baf561e29ef2bdbadc75acc6dbc Mon Sep 17 00:00:00 2001
From: Kaloyan Nikolov <konik98@gmail.com>
Date: Mon, 6 Apr 2026 15:39:01 +0200
Subject: [PATCH] Document build-from-source attempt and issues encountered

- Added BUILD_FROM_SOURCE.md with detailed error analysis
- Documented SDK version issues and miniaudio cross-compilation problems
- Provided alternative approaches and recommendations
---
 BUILD_FROM_SOURCE.md | 138 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 138 insertions(+)
 create mode 100644 BUILD_FROM_SOURCE.md

diff --git a/BUILD_FROM_SOURCE.md b/BUILD_FROM_SOURCE.md
new file mode 100644
index 0000000..7610e96
--- /dev/null
+++ b/BUILD_FROM_SOURCE.md
@@ -0,0 +1,138 @@
+# Building LiteRT-LM for iOS from Source
+
+## Status: Build Issues Encountered
+
+We attempted to build LiteRT-LM iOS binaries from source but encountered significant cross-compilation challenges with Bazel.
+
+## Build Attempt Summary
+
+### Environment
+- **Machine**: Mac Mini (Apple Silicon)
+- **OS**: macOS 15.x
+- **Xcode**: CommandLineTools SDK 15.5
+- **Bazel**: 7.6.1 (via Bazelisk)
+
+### Commands Attempted
+
+```bash
+# Clone repository
+git clone https://github.com/google-ai-edge/LiteRT-LM.git
+cd LiteRT-LM
+
+# Build for iOS device (arm64)
+bazel build --config=ios_arm64 //c:engine
+
+# Build for iOS simulator (arm64)
+bazel build --config=ios_sim_arm64 //c:engine
+```
+
+### Issues Encountered
+
+#### 1. SDK Version Mismatch
+```
+ERROR: SDK version [10.11] for platform [MacOSX] is unsupported
+xcrun: error: SDK "macosx10.11" cannot be located
+```
+
+**Attempted Fix**: Created `.bazelrc.user` with `--macos_sdk_version=15.5`
+
+#### 2. OpenGLES Header Missing
+```
+fatal error: 'OpenGLES/EAGL.h' file not found
+#import <OpenGLES/EAGL.h>
+```
+
+**Root Cause**: The miniaudio library uses AVFoundation framework which on macOS includes CoreImage, which requires OpenGLES headers. When cross-compiling for iOS from macOS, Bazel incorrectly uses the host macOS SDK for some compilation steps.
+
+**Attempted Fixes**:
+- Patched `BUILD.miniaudio` to use different SDK frameworks
+- Patched `runtime/components/preprocessor/BUILD` to use C version instead of ObjC version
+- Neither fully resolved the issue
+
+#### 3. Objective-C Syntax Errors
+```
+error: expected identifier or '('
+@class NSInvocation, NSMethodSignature, NSCoder, NSString, NSEnumerator;
+```
+
+**Root Cause**: After switching to C version of miniaudio, the C compiler tried to parse Objective-C headers.
+
+### Patches Applied
+
+1. **`.bazelrc.user`** - SDK version override:
+```
+build --macos_sdk_version=15.5
+build --ios_sdk_version=18.0
+```
+
+2. **`BUILD.miniaudio`** - Added more SDK frameworks
+
+3. **`runtime/components/preprocessor/BUILD`** - Changed miniaudio selection to use C version
+
+### Why These Issues Occur
+
+1. **Complex Cross-Compilation**: LiteRT-LM uses Bazel with rules_apple for iOS builds, which requires precise toolchain configuration.
+
+2. **Audio Dependencies**: The miniaudio library needs platform-specific audio backends (AVFoundation on iOS/macOS), which creates complications during cross-compilation.
+
+3. **Host vs Target Toolchains**: Bazel is mixing host (macOS) and target (iOS) toolchains, causing SDK mismatches.
+
+## Alternative Approaches
+
+### Option 1: Use Full Xcode (Not CommandLineTools)
+The build may work better with full Xcode installation which has proper iOS SDKs:
+```bash
+sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
+```
+
+### Option 2: Build on Linux with iOS Cross-Compilation
+Use a Linux machine with proper iOS cross-compilation toolchain setup.
+
+### Option 3: Wait for Official Binaries
+Google may provide prebuilt iOS binaries in future releases.
+
+### Option 4: Use MediaPipe Tasks (Working Alternative)
+While deprecated, MediaPipe Tasks LLM Inference has a working Swift API:
+```ruby
+pod 'MediaPipeTasksGenAI', '~> 0.10.0'
+```
+
+### Option 5: Use LiteRT C API with Custom Bridge
+Build only the core LiteRT runtime (without LLM features) and implement the conversation handling in Swift.
+
+## Recommendation
+
+**For immediate use**: Use the Objective-C++ bridge pattern with stub implementation (already provided in the project) and wait for:
+1. Official LiteRT-LM iOS binaries from Google
+2. LiteRT-LM Swift API release (marked as "coming soon")
+
+**For production**: Consider building on a CI service like GitHub Actions with proper macOS/iOS build environment.
+
+## Build Scripts
+
+The following scripts were created during the build attempt:
+
+### `/tmp/build_litert_lm_ios.sh`
+Main build script that attempts to build both device and simulator libraries.
+
+### `/tmp/patch_miniaudio_build.py`
+Patches the miniaudio BUILD file to add additional SDK frameworks.
+
+### `/tmp/patch_preprocessor_build.py`
+Patches the preprocessor BUILD file to use C version of miniaudio.
+
+## Next Steps
+
+To successfully build from source, you would need to:
+
+1. Install full Xcode (not just CommandLineTools)
+2. Set up proper iOS signing certificates
+3. Modify the Bazel build configuration to handle audio dependencies correctly
+4. Potentially disable audio features entirely for a text-only build
+5. Build in a clean environment with sufficient disk space (20GB+)
+
+## References
+
+- [LiteRT-LM Build Instructions](https://github.com/google-ai-edge/LiteRT-LM/blob/main/docs/getting-started/build-and-run.md)
+- [Bazel Apple Rules](https://github.com/bazelbuild/rules_apple)
+- [iOS Cross-Compilation with Bazel](https://bazel.build/concepts/platforms)