LiteRt iOS Swift Package (SPM)

A lightweight, high-performance, Bazel-free Swift Package distribution of the official LiteRT (formerly TensorFlow Lite) CompiledModel C/C++ API for Apple devices.

This package enables iOS application developer teams to build hardware-accelerated ML apps (CPU, GPU, and NPU acceleration slices) using standard native Swift and Objective-C++ tools inside standard Xcode, completely bypassing the complex Bazel build environments, toolchain configuration setups, and python script dependencies.

---

📦 Package Targets Layout

The Swift Package is structured as a layered dependency stack to decouple precompiled binary dynamic slices, public C++ header references, and high-level Swift interfaces cleanly:

┌────────────────────────────────────────────────────────┐
│                      Swift Domain                      │
│     Target: LiteRt (Standard Swift utility module)     │
└───────────────────────────┬────────────────────────────┘
                            │
                      Depends on API
                            │
                            ▼
┌────────────────────────────────────────────────────────┐
│            Objective-C++ Bridge Domain (Opaque)        │
│   Target: LiteRtCPlusPlus (C++ cc/ and c/ API Headers) │
└───────────────────────────┬────────────────────────────┘
                            │
                      Links Dynamic
                            │
                            ▼
┌────────────────────────────────────────────────────────┐
│                C++ Core Domain (LiteRT)                │
│    Target: LiteRtRuntime (Precompiled xcframework)     │
└────────────────────────────────────────────────────────┘

1. LiteRtRuntime (Binary Dynamic Target): Exposes the precompiled multi-architecture dynamic framework .xcframework containing binary symbols for physical iOS Devices (arm64) and iOS Simulators (arm64/x86_64 slices).
2. LiteRtCPlusPlus (Header-Only Target): Houses the official public C API headers (litert/c/) and modern C++ wrapper APIs (litert/cc/), exposing search path declarations to any target linking the package.
3. LiteRt (Swift API Target): Houses native Swift classes, structs, and modern Swift wrapper modules.

---

🛠️ How to Integrate in Your Xcode Project

Developer teams can integrate this package into any standard iOS application without a Bazel environment:

Step 1: Add Swift Package Dependency

1. Open your standard iOS Application project in Xcode.
2. Navigate to File > Add Package Dependencies...
3. Paste this repository URL in the search bar:

   https://github.com/aravindmurali22/LiteRt-iOS-SPM.git
   

4. Set the Dependency Rule to Up to Next Major Version starting at 2.1.4.
5. Select your application target to link the modules.

Step 2: Critical Codesigning Configuration (Embed & Sign)

Caution

Launch Crash Prevention Check: Because the core engine target LiteRtRuntime is a C++ dynamic framework (dylib), iOS developer sandboxing requires the dynamic binary files to be copied into the application package Frameworks directory at build time. Failing to do this causes your app to build successfully but crash immediately on startup with a dynamic loader error (dyld: Library not loaded).

To configure this correctly:

1. Select your Application project in the Xcode File Inspector and open your target settings General tab.
2. Scroll down to the Frameworks, Libraries, and Embedded Content section.
3. Locate LiteRtRuntime in the table list and set its action in the Embed column to Embed & Sign.

Step 3: Configure Target Compiler Settings

To compile your custom Objective-C++ bridge classes and map them cleanly to your Swift ViewModel lifecycle, configure the following target properties inside the target Build Settings tab in Xcode:

• Objective-C Bridging Header: Set your bridging header path (e.g., $(PROJECT_DIR)/ImageSegmentation/ImageSegmentation-Bridging-Header.h).
• C++ Language Standard: Set C++ Language Standard to C++20 or GNU++20 (-std=c++20).
• Objective-C ARC: Verify that Objective-C Automatic Reference Counting is enabled (Yes / -fobjc-arc flag).

---

⚙️ Package Maintenance: Compiling the .xcframework

Package maintainers and CI pipelines build and assemble new dynamic framework versions as follows:

Step 1: Build the Dynamic Framework Slices with Bazel

Compile the dynamic libraries for physical devices and simulator architectures once on a secure CI platform:

# 1. Compile physical iOS Device binary slice (arm64)
bazel build @litert_archive//litert/c:litert_runtime_c_api_shared_lib \
  --apple_platform_type=ios --cpu=ios_arm64 --compilation_mode=opt

# 2. Compile iOS Simulator binary slice (arm64)
bazel build @litert_archive//litert/c:litert_runtime_c_api_shared_lib \
  --apple_platform_type=ios --cpu=ios_sim_arm64 --compilation_mode=opt

Step 2: Assemble the Multi-Architecture .xcframework

Combine the compiled dynamic framework slices into a standard unified Apple .xcframework:

xcodebuild -create-xcframework \
  -framework bazel-bin/path/to/device/LiteRtRuntime.framework \
  -framework bazel-bin/path/to/simulator/LiteRtRuntime.framework \
  -output Frameworks/LiteRtRuntime.xcframework

Step 3: Remote CDN Distribution (Recommended Best Practice)

To prevent checking heavy binary framework files directly into your Git repository, distribute the precompiled .xcframework as a compressed remote dependency target:

1. Compress the framework:

   cd Frameworks/
   zip -r LiteRtRuntime.xcframework.zip LiteRtRuntime.xcframework

2. Upload the LiteRtRuntime.xcframework.zip archive to your secure web hosting CDN or Git Release assets page.
3. Compute the SHA-256 cryptographic hash:

   swift package compute-checksum LiteRtRuntime.xcframework.zip

4. Update the url and the checksum parameters of the .binaryTarget rule in your package's Package.swift manifest!

---

📜 License

This Swift Package is distributed under the Apache License 2.0. Refer to the LICENSE file for core guidelines and permissions details.