CocoaPods Plugin — 概要、KMM用プラグインと設定

CocoaPods Pluginとは？

CocoaPods Plugin（kotlin.cocoapodsとしても知られる）は、CocoaPodsをKotlin Multiplatform Mobileと統合するためのJetBrains公式プラグインです。このプラグインはKotlin Gradle DSLの一部であり、KMMモジュールのbuild.gradle.ktsで直接設定されます。Podfileの作成と保守、.xcworkspaceの生成、ポッド依存関係の管理を自動化し、手動によるXcodeプロジェクト設定を不要にします。

CocoaPods Plugin以前は、KMM開発者はPodfileを手動で作成し、pod installを実行し、ブリッジヘッダーを設定し、Gradle依存関係とは別にポッドバージョンを追跡する必要がありました。これにより、バージョンの非同期化やCI/CDパイプラインでの困難が生じていました。プラグインは、iOS依存関係管理をAndroidモジュールでのGradle依存関係管理と同じくらい簡単にすることで、これらの問題を解決しました。

プラグインは、CocoaPods Trunkからのパブリックポッドとプライベートリポジトリからのカスタムポッドの両方をサポートしています。ローカルPodspecおよびgitベースのリポジトリでの作業もサポートされています。プラグインはKotlin 1.6.0以上と互換性があり、開発マシンにCocoaPods（gem install cocoapods）がインストールされている必要があります。

CocoaPods Pluginの仕組み

CocoaPods PluginはGradleタスクグラフレベルで動作し、CocoaPodsを操作するための専門タスクを追加します。主要なタスクには、podInstall（ポッドのインストール）、podGenXcodeWorkspace（.xcworkspaceの生成）、podBuildDebugFramework（フレームワークのDebugバージョンのビルド）が含まれます。プラグインはbuild.gradle.ktsのcocoapodsセクションを分析し、宣言された依存関係に基づいてPodfileを作成し、必要なパラメーターでpod installを実行します。

プラグインのアーキテクチャには3つのコンポーネントがあります：build.gradle.kts用のDSL拡張、Podfileを作成するPodfileジェネレーター、.xcworkspaceを設定するXcode統合レイヤーです。DSL拡張は、依存関係を宣言するためのネストされたpod()関数、プライベートリポジトリを指定するためのspecRepo()、出力フレームワークを設定するためのframework { }を備えたcocoapods { }ブロックを提供します。Podfileジェネレーターはこれらの宣言をCocoaPodsが理解できるRuby構文に変換します。

kotlin {
    cocoapods {
        summary = "Shared module for iOS project"
        homepage = "https://itsectr.com"
        framework {
            baseName = "Shared"
            isStatic = true
            export(project(":core"))
        }
        pod("Alamofire") {
            version = "~> 5.9"
        }
        pod("Kingfisher") {
            version = "7.12"
        }
    }
}

podInstallタスクのライフサイクル

podInstallを実行すると、プラグインは順次：プロジェクトルートにPodfileを生成し、コマンドラインからpod installを実行し、.xcworkspaceを生成し、ポッドバージョンが宣言されたものと一致することを確認し、Podfile.lockをキャッシュします。設定変更がない後続の実行では、Podfile.lockが変更されていない場合、podInstallはスキップされます。これにより、クリーンインストールでpod installに最大2〜3分かかる可能性があるCI/CDで時間を節約できます。

KMMプロジェクトでのCocoaPods Pluginのセットアップ

CocoaPods Pluginのセットアップにはいくつかの手順が必要です。開発マシンへのCocoaPodsのインストール（gem install cocoapods）が前提条件です。次に、sharedモジュールのbuild.gradle.ktsに、フレームワーク設定と依存関係を含むcocoapods { }ブロックを追加します。設定後、podInstallタスクを実行すると、Podfileが作成されポッドがインストールされます。生成された.xcworkspaceは、Podfileの横のプロジェクトルートに配置されます。

プラグインはXcode Build Phasesと統合します。iOSアプリをビルドする際、XcodeはembedAndSignAppleFrameworkForXcodeを実行します。これはKotlin/Nativeフレームワークをアプリバンドルにコピーするタスクです。CocoaPods Pluginは.xcworkspaceを生成する際に、このビルドフェーズを自動的に追加します。.xcworkspaceが生成された場合は、ポッド依存関係で正しくビルドするために、.xcodeprojの代わりにそれを開く必要があります。

コード例：ポッド設定

CocoaPods Pluginでポッドを宣言するさまざまなシナリオを見てみましょう。基本的なケースは、バージョンを指定してCocoaPods Trunkからパブリックポッドを接続することです。より複雑なシナリオには、カスタムpodspec、ローカルポッド、gitリポジトリからのポッドの使用が含まれます。

kotlin {
    iosArm64()
    iosSimulatorArm64()

    cocoapods {
        framework {
            baseName = "Shared"
            isStatic = false
        }

        // CocoaPods Trunkからのパブリックポッド
        pod("Alamofire") { version = "5.9.0" }

        // 演算子付きカスタムバージョン
        pod("SnapKit") { version = "~> 5.6" }

        // プライベートリポジトリからのポッド
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // パス付きローカルポッド
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

        // gitリポジトリからのポッド
        pod(name = "PrivateSDK",
            git = "https://git.itsectr.com/ios/sdk.git",
            tag = "2.1.0")
    }
}

ポッドの接続は設定の一部にすぎません。プラグインは、他のKotlinモジュールからiOSフレームワークへの依存関係のエクスポートも可能にします。export(project(":core"))関数は、:coreモジュールのすべてのパブリックAPIが生成されたフレームワークのObjective-Cヘッダーからアクセス可能である必要があることを指定します。これは、共有Kotlinコードが別のモジュールのクラスを使用し、それらがSwiftからアクセス可能である必要がある場合に必要です。

cocoapods {
    framework {
        baseName = "Shared"
        // モジュールをiOSフレームワークにエクスポート
        export(project(":network"))
        export(project(":domain"))

        // 静的または動的リンク
        isStatic = true
    }

    // エクスポートされたモジュールに必要なポッド
    pod("Moya") { version = "15.0" }
}

ビルドとテスト

設定後、Podfileを生成して依存関係をインストールするためにpodInstallを実行する必要があります。次に、生成された.xcworkspaceをXcodeで開き、標準的な方法でアプリをビルドできます。CI/CDの場合は、ビルドマシンにCocoaPodsとRubyがインストールされていることを確認してください。プラグインはCI環境で動作するための--no-daemonフラグをサポートしています。

// ポッドをインストールするとPodfile + xcworkspaceが生成されます
./gradlew :shared:podInstall

// テスト用のデバッグフレームワークをビルド
./gradlew :shared:podBuildDebugFramework

// コマンドラインから完全なiOSビルド
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager（SPM）はAppleの代替依存関係マネージャーであり、人気が高まっており、iOSコミュニティで徐々にCocoaPodsを置き換えつつあります。しかし、CocoaPods Pluginはいくつかの理由で依然として重要です。SPMはKMMコンテキストで動的フレームワークをサポートしておらず、SPMを介したKotlin/Nativeフレームワークの統合には追加の設定が必要です。CocoaPods Pluginはより成熟して文書化された統合パスを提供します。

CocoaPods Pluginと直接SPM統合の比較では、前者が自動化で優れ、後者がネイティブAppleサポートで優れていることが示されています。CocoaPods PluginはPodfileを自動生成し、バージョンを管理し、Xcode Build Phasesを設定します。SPMはPackage.swiftを介してKotlinフレームワークを手動で接続する必要があり、大規模なKMMプロジェクトでは保守が困難です。JetBrainsはKotlin/NativeのSPMサポートに取り組んでいますが、2025年時点ではSPM統合は実験的なままです。

一般的な問題と解決策

CocoaPods Pluginを使用する際、KMM開発者はいくつかの典型的な問題に直面します。ポッドのバージョン競合が最も一般的な問題で、2つのポッドが同じ依存関係の異なるバージョンを必要とする場合です。解決策は、pod("Dependency") { version = "x.x" }を介して競合する依存関係のバージョンを明示的に指定することです。2つ目の一般的なケースはバージョンの非互換性で、ポッドがKMMプロジェクトの最小バージョンよりも新しいiOS SDKを必要とする場合です。

.xcworkspaceの問題は、プラグイン設定後に.xcodeprojを.xcworkspaceの代わりに開いた場合に発生します。プラグインはpodInstallログでこれについて警告します。もう1つの頻繁なエラーは、開発マシンにCocoaPodsがないことです。プラグインはpodInstallを実行する前にpodコマンドの存在を確認し、明確なエラーメッセージを表示します。CI/CDの場合は、CocoaPodsをインストールしてください：gem install cocoapods。

// バージョン競合を解決
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // 競合を明示的に解決
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// Gradle経由でCocoaPodsインストールを確認
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("CocoaPodsバージョン：$result")
    }
}

podInstallのデバッグ

podInstallが失敗した場合は、詳細な出力のために--infoフラグを使用してください：./gradlew podInstall --info。プラグインは各ステップ（Podfile生成、pod installの実行、Podfile.lockの解析）をログに記録します。ほとんどの場合、エラーはネットワークの問題（CocoaPods Trunkにアクセスできない）またはPodfileの構文エラーに関連しています。そのような場合は、プロジェクトルートでpod installを手動で実行して、CocoaPodsからより詳細なエラーメッセージを取得してみてください。