CocoaPodsの概要とセットアップ

これはローカル統合方法です。以下の場合に役立ちます。

• CocoaPodsを使用するiOSプロジェクトを含むモノレポ構成である。
• Kotlin MultiplatformプロジェクトがCocoaPodsに依存している。
  

最適な統合方法を選択する

Kotlin/Nativeは、CocoaPods依存関係マネージャーとの統合を提供します。Podライブラリへの依存関係を追加したり、KotlinプロジェクトをCocoaPodsの依存関係として使用したりできます。

IntelliJ IDEAまたはAndroid StudioでPodの依存関係を直接管理でき、コードハイライトや補完などの追加機能をすべて利用できます。Xcodeに切り替えることなく、GradleでKotlinプロジェクト全体をビルドできます。

Swift/Objective-Cコードを変更したり、Appleシミュレーターまたはデバイスでアプリケーションを実行したりする場合にのみXcodeが必要です。Xcodeで作業するには、最初にPodfileを更新してください。

CocoaPodsで作業するための環境をセットアップする

選択したインストールツールを使用して、CocoaPods依存関係マネージャーをインストールします。

RVMRbenvデフォルトのRubyHomebrew

1. RVMをまだ持っていない場合はインストールします。

2. Rubyをインストールします。特定のバージョンを選択できます。

   rvm install ruby 3.0.0

3. CocoaPodsをインストールします。

   sudo gem install -n /usr/local/bin cocoapods

1. GitHubからrbenvをまだ持っていない場合はインストールします。

2. Rubyをインストールします。特定のバージョンを選択できます。

   rbenv install 3.0.0

3. Rubyバージョンを特定のディレクトリのローカル、またはマシン全体のグローバルに設定します。

   rbenb global 3.0.0

4. CocoaPodsをインストールします。

   sudo gem install -n /usr/local/bin cocoapods

このインストール方法はApple Mチップ搭載デバイスでは動作しません。CocoaPodsで作業するための環境をセットアップするには、他のツールを使用してください。

macOSで利用可能なデフォルトのRubyを使用して、CocoaPods依存関係マネージャーをインストールできます。

sudo gem install cocoapods

HomebrewによるCocoaPodsのインストールは、互換性の問題を引き起こす可能性があります。

CocoaPodsをインストールすると、HomebrewはXcodeとの連携に必要なXcodeprojgemもインストールします。 しかし、それはHomebrewでは更新できず、インストールされたXcodeprojが最新のXcodeバージョンをまだサポートしていない場合、Podのインストールでエラーが発生します。この場合は、CocoaPodsをインストールするために他のツールを試してください。

1. Homebrewをまだ持っていない場合はインストールします。

2. CocoaPodsをインストールします。

   brew install cocoapods

インストール中に問題が発生した場合は、考えられる問題と解決策セクションを確認してください。

プロジェクトを作成する

環境がセットアップされたら、新しいKotlin Multiplatformプロジェクトを作成できます。そのためには、Kotlin MultiplatformウェブウィザードまたはAndroid Studio用のKotlin Multiplatformプラグインを使用します。

ウェブウィザードを使用する

ウェブウィザードを使用してプロジェクトを作成し、CocoaPods統合を設定するには：

1. Kotlin Multiplatformウィザードを開き、プロジェクトのターゲットプラットフォームを選択します。

2. Downloadボタンをクリックし、ダウンロードしたアーカイブを展開します。

3. Android Studioで、メニューからFile | Openを選択します。

4. 展開したプロジェクトフォルダーに移動し、Openをクリックします。

5. Kotlin CocoaPods Gradleプラグインをバージョンカタログに追加します。gradle/libs.versions.tomlファイルに、[plugins]ブロックに以下の宣言を追加します。

   kotlinCocoapods = { id = "org.jetbrains.kotlin.native.cocoapods", version.ref = "kotlin" }

6. プロジェクトのルートbuild.gradle.ktsファイルに移動し、plugins {}ブロックに以下のエイリアスを追加します。

   alias(libs.plugins.kotlinCocoapods) apply false

7. CocoaPodsを統合したいモジュール（例：composeAppモジュール）を開き、plugins {}ブロックに以下のエイリアスを追加します。

   alias(libs.plugins.kotlinCocoapods)

これで、Kotlin MultiplatformプロジェクトでCocoaPodsを設定する準備ができました。

Android Studioで

CocoaPods統合でAndroid Studioにプロジェクトを作成するには：

1. Android StudioにKotlin Multiplatformプラグインをインストールします。

2. Android Studioで、メニューからFile | New | New Projectを選択します。

3. プロジェクトテンプレートのリストで、Kotlin Multiplatform Appを選択し、Nextをクリックします。

4. アプリケーションに名前を付け、Nextをクリックします。

5. iOSフレームワークの配布オプションとしてCocoaPods Dependency Managerを選択します。

   

6. 他のオプションはすべてデフォルトのままにします。Finishをクリックします。

   プラグインがCocoaPods統合をセットアップした状態でプロジェクトを自動的に生成します。

プロジェクトを設定する

マルチプラットフォームプロジェクトでKotlin CocoaPods Gradleプラグインを設定するには：

1. プロジェクトの共有モジュールのbuild.gradle(.kts)で、CocoaPodsプラグインとKotlin Multiplatformプラグインを適用します。

   ウェブウィザードまたはAndroid Studio用のKotlin Multiplatformプラグインでプロジェクトを作成した場合は、この手順をスキップしてください。

   plugins {
       kotlin("multiplatform") version "2.2.0"
       kotlin("native.cocoapods") version "2.2.0"
   }

2. cocoapodsブロックでPodspecファイルのversion、summary、homepage、baseNameを設定します。

   plugins {
       kotlin("multiplatform") version "2.2.0"
       kotlin("native.cocoapods") version "2.2.0"
   }
   
   kotlin {
       cocoapods {
           // Required properties
           // Specify the required Pod version here
           // Otherwise, the Gradle project version is used
           version = "1.0"
           summary = "Some description for a Kotlin/Native module"
           homepage = "Link to a Kotlin/Native module homepage"
   
           // Optional properties
           // Configure the Pod name here instead of changing the Gradle project name
           name = "MyCocoaPod"
   
           framework {
               // Required properties              
               // Framework name configuration. Use this property instead of deprecated 'frameworkName'
               baseName = "MyFramework"
               
               // Optional properties
               // Specify the framework linking type. It's dynamic by default. 
               isStatic = false
               // Dependency export
               // Uncomment and specify another project module if you have one:
               // export(project(":<your other KMP module>"))
               transitiveExport = false // This is default.
           }
   
           // Maps custom Xcode configuration to NativeBuildType
           xcodeConfigurationToNativeBuildType["CUSTOM_DEBUG"] = NativeBuildType.DEBUG
           xcodeConfigurationToNativeBuildType["CUSTOM_RELEASE"] = NativeBuildType.RELEASE
       }
   }

   Kotlin DSLの完全な構文は、Kotlin Gradleプラグインリポジトリを参照してください。

3. IntelliJ IDEAでBuild | Reload All Gradle Projectsを実行（またはAndroid StudioでFile | Sync Project with Gradle Filesを実行）して、プロジェクトを再インポートします。

4. Xcodeビルド時の互換性問題を避けるために、Gradle wrapperを生成します。

適用すると、CocoaPodsプラグインは以下を実行します。

• debugおよびreleaseフレームワークの両方を、すべてのmacOS、iOS、tvOS、watchOSターゲットの出力バイナリとして追加します。
• プロジェクトのPodspecファイルを生成するpodspecタスクを作成します。

Podspecファイルには、出力フレームワークへのパスと、Xcodeプロジェクトのビルドプロセス中にこのフレームワークのビルドを自動化するスクリプトフェーズが含まれます。

Xcode用のPodfileを更新する

KotlinプロジェクトをXcodeプロジェクトにインポートしたい場合は：

1. KotlinプロジェクトのiOS部分で、Podfileに変更を加えます。

   • プロジェクトにGit、HTTP、またはカスタムPodspecリポジトリの依存関係がある場合は、PodfileにPodspecへのパスを指定します。

     例えば、podspecWithFilesExampleに依存関係を追加する場合、PodfileにPodspecへのパスを宣言します。

     target 'ios-app' do
        # ... other dependencies ...
        pod 'podspecWithFilesExample', :path => 'cocoapods/externalSources/url/podspecWithFilesExample' 
     end

     :pathにはPodへのファイルパスを含める必要があります。

   • カスタムPodspecリポジトリからライブラリを追加する場合は、Podfileの冒頭にスペックの場所を指定します。

     source 'https://github.com/Kotlin/kotlin-cocoapods-spec.git'
     
     target 'kotlin-cocoapods-xcproj' do
         # ... other dependencies ...
         pod 'example'
     end

2. プロジェクトディレクトリでpod installを実行します。

   pod installを初めて実行すると、.xcworkspaceファイルが作成されます。このファイルには、元の.xcodeprojとCocoaPodsプロジェクトが含まれます。

3. .xcodeprojを閉じ、代わりに新しい.xcworkspaceファイルを開きます。これにより、プロジェクトの依存関係に関する問題を回避できます。

4. IntelliJ IDEAでBuild | Reload All Gradle Projectsを実行（またはAndroid StudioでFile | Sync Project with Gradle Filesを実行）して、プロジェクトを再インポートします。

Podfileにこれらの変更を加えない場合、podInstallタスクは失敗し、CocoaPodsプラグインはログにエラーメッセージを表示します。

考えられる問題と解決策

CocoaPodsのインストール

Rubyのインストール

CocoaPodsはRubyでビルドされており、macOSで利用可能なデフォルトのRubyでインストールできます。Ruby 1.9以降には、CocoaPods依存関係マネージャーのインストールに役立つRubyGemsパッケージ管理フレームワークが内蔵されています。

CocoaPodsのインストールや動作に問題が発生している場合は、このガイドに従ってRubyをインストールするか、RubyGemsのウェブサイトを参照してフレームワークをインストールしてください。

バージョンの互換性

最新のKotlinバージョンを使用することをお勧めします。現在のバージョンが1.7.0より古い場合、追加でcocoapods-generateプラグインをインストールする必要があります。

ただし、cocoapods-generateはRuby 3.0.0以降と互換性がありません。この場合、Rubyをダウングレードするか、Kotlinを1.7.0以降にアップグレードしてください。

Xcode使用時のビルドエラー

CocoaPodsのインストール方法によっては、Xcodeでビルドエラーが発生する場合があります。一般的に、Kotlin GradleプラグインはPATH内のpod実行可能ファイルを発見しますが、これは環境によって一貫性がない場合があります。

CocoaPodsのインストールパスを明示的に設定するには、プロジェクトのlocal.propertiesファイルに手動で、またはシェルコマンドを使用して追加します。

• コードエディタを使用している場合は、local.propertiesファイルに以下の行を追加します。

  kotlin.apple.cocoapods.bin=/Users/Jane.Doe/.rbenv/shims/pod

• ターミナルを使用している場合は、以下のコマンドを実行します。

  echo -e "kotlin.apple.cocoapods.bin=$(which pod)" >> local.properties

モジュールまたはフレームワークが見つからない

Podのインストール時に、C interopの問題に関連するmodule 'SomeSDK' not foundまたはframework 'SomeFramework' not foundエラーが発生する場合があります。これらのエラーを解決するには、以下の解決策を試してください。

パッケージを更新する

インストールツールとインストール済みパッケージ（gem）を更新します。

RVMRbenvHomebrew

1. RVMを更新します。

   rvm get stable

2. RubyのパッケージマネージャーであるRubyGemsを更新します。

   gem update --system

3. インストールされているすべてのgemを最新バージョンにアップグレードします。

   gem update

1. Rbenvを更新します。

   cd ~/.rbenv
   git pull

2. RubyのパッケージマネージャーであるRubyGemsを更新します。

   gem update --system

3. インストールされているすべてのgemを最新バージョンにアップグレードします。

   gem update

1. Homebrewパッケージマネージャーを更新します。

   brew update

2. インストールされているすべてのパッケージを最新バージョンにアップグレードします。

   brew upgrade

フレームワーク名を指定する

1. ダウンロードされたPodディレクトリ[shared_module_name]/build/cocoapods/synthetic/IOS/Pods/...内でmodule.modulemapファイルを探します。

2. モジュール内のフレームワーク名（例：SDWebImageMapKit {}）を確認します。フレームワーク名がPod名と一致しない場合は、明示的に指定します。

   pod("SDWebImage/MapKit") {
       moduleName = "SDWebImageMapKit"
   }

ヘッダーを指定する

Podに.modulemapファイルが含まれていない場合（例：pod("NearbyMessages")）、メインヘッダーを明示的に指定します。

pod("NearbyMessages") {
    version = "1.1.1"
    headers = "GNSMessages.h"
}

詳細については、CocoaPodsドキュメントを確認してください。何も解決せず、このエラーが引き続き発生する場合は、YouTrackで問題を報告してください。

Rsyncエラー

rsync error: some files could not be transferredエラーに遭遇する場合があります。これは、Xcodeのアプリケーションターゲットでユーザースクリプトのサンドボックス化が有効になっている場合に発生する既知の問題です。

この問題を解決するには：

1. アプリケーションターゲットでユーザースクリプトのサンドボックス化を無効にします。

   

2. サンドボックス化されている可能性のあるGradleデーモンプロセスを停止します。

   ./gradlew --stop

次のステップ

• KotlinプロジェクトでPodライブラリへの依存関係を追加する
• KotlinプロジェクトとXcodeプロジェクト間の依存関係をセットアップする
• CocoaPods GradleプラグインのDSLリファレンス全体を見る