# 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)