OpenCV.frameworkをXCFrameworkに変換しSPMで利用する手順

はじめに

OpenCV の公式リリースには、iOS 向けの XCFramework が提供されていません。

公式で配布されている形式は従来の .framework 形式であり、そのままでは Swift Package Manager (SwiftPM) での組み込みや、モダンな環境での利用に制約があります。

本記事では、OpenCV の .framework を opencv2.xcframework に変換し、SwiftPM 経由で安全にプロジェクトに組み込むための手順をまとめます。

OpenCVのiOS frameworkをダウンロード

公式GitHub Releasesから、iOS用frameworkのZIPファイルをダウンロードします。

1. https://github.com/opencv/opencv にアクセス
2. 「Releases」タブへ移動
3. 最新のReleaseを開く
4. Assetsからopencv-4.x.x-ios-framework.zip をダウンロード

ZIP を解凍すると、以下のファイルが得られます。

opencv2.framework

作業フォルダの準備

ターミナルで作業用のフォルダを作成し、ダウンロードした .framework を配置します。

# デスクトップに移動
cd ~/Desktop
# 作業フォルダを作成
mkdir opencv-build
cd opencv-build

# ダウンロードした framework をコピー
cp -R ~/Desktop/opencv2.framework ./opencv2.framework

FAT バイナリの分解（lipo コマンド）

OpenCV の公式 .framework に含まれるバイナリ（opencv2）は、arm64（実機） と x86_64（シミュレータ） が混在したFATバイナリです。

XCFramework を作成するためには、このバイナリをアーキテクチャごとに分割する必要があります。

cd opencv2.framework

# arm64（実機用）を抽出
lipo -extract arm64 opencv2 -o opencv2_arm64

# x86_64（シミュレータ用）を抽出
lipo -extract x86_64 opencv2 -o opencv2_x86_64

これにより、以下の2つのファイルが生成されます。

opencv2_arm64    # iPhone 実機用バイナリ
opencv2_x86_64   # Simulator 用バイナリ

XCFrameworkの素材となるframeworkを作成

分割したバイナリと既存のヘッダファイル、モジュール情報を利用し、デバイス用とシミュレータ用の2つの独立した.frameworkフォルダを再構築します。

cd ~/Desktop/opencv-build

# --- デバイス用 (arm64) ---
mkdir -p device/opencv2.framework
# ヘッダファイル・モジュールをコピー
cp -R opencv2.framework/Headers device/opencv2.framework/
cp -R opencv2.framework/Modules device/opencv2.framework/
# arm64 バイナリを配置
cp opencv2.framework/opencv2_arm64 device/opencv2.framework/opencv2

# --- シミュレータ用 (x86_64) ---
mkdir -p sim/opencv2.framework
# ヘッダファイル・モジュールをコピー
cp -R opencv2.framework/Headers sim/opencv2.framework/
cp -R opencv2.framework/Modules sim/opencv2.framework/
# x86_64 バイナリを配置
cp opencv2.framework/opencv2_x86_64 sim/opencv2.framework/opencv2

XCFrameworkの作成

xcodebuild -create-xcframeworkコマンドを使用して、手順5で作成した2つの.frameworkからXCFrameworkを作成します。

cd ~/Desktop/opencv-build

xcodebuild -create-xcframework \
  -framework device/opencv2.framework \
  -framework sim/opencv2.framework \
  -output ~/Desktop/opencv2.xcframework

成功すると、デスクトップにopencv2.xcframeworkが生成されます。

SwiftPM での配布準備（ZIP化とChecksum生成）

Swift Package ManagerでbinaryTargetとして配布・利用する場合、XCFrameworkをZIPファイルにする必要があります。

cd ~/Desktop
# XCFramework を ZIP 圧縮
zip -r opencv2.xcframework.zip opencv2.xcframework

次に、SwiftPMのPackage.swiftに記述するためのSHA256 Checksumを生成します。

swift package compute-checksum opencv2.xcframework.zip

生成されたSHA256値をPackage.swiftのchecksumに貼り付けます。

.binaryTarget(
    name: "opencv2",
    url: "https://github.com/xxxx/opencv2.xcframework.zip", // ダウンロードURL
    checksum: "<ここに計算結果のSHA256値を貼る>"
)

XCFrameworkの利点（補足）

従来の .framework（FATバイナリ）ではなく XCFramework を利用する主な理由は以下の通りです。

• Swift Package Manager (SwiftPM) の要件: SwiftPM は、実機とシミュレータのバイナリが分離された .xcframework 形式を推奨（または必須）としています。FATバイナリは利用できません。
• Appleの推奨形式: XCFramework は、実機とシミュレータのバイナリを分離し、将来的なプラットフォーム（macOS/Apple Siliconなど）の互換性にも対応するための Apple の正式な配布形式です。
• SDK配布の標準化: ライブラリで外部依存性を管理する際に、ビルド環境によらず安定して動作する形式として最適です。