CocoaPods の概要とセットアップ

これはローカル統合の手法です。以下の場合に適しています：

CocoaPods を使用する iOS プロジェクトを含むモノリポジトリ構成である。
Kotlin マルチプラットフォームプロジェクトに CocoaPods の依存関係がある。

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

CocoaPods 統合のアプローチは、直接統合で使用される embedAndSignAppleFrameworkForXcode メカニズムと一緒に使用することはできません。

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

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

CocoaPods を使用するための環境構築

お好みのインストールツールを使用して、CocoaPods 依存関係マネージャーをインストールします：

RVMRbenvデフォルトの RubyHomebrew

RVM をまだインストールしていない場合は、インストールします。
Ruby をインストールします。特定のバージョンを選択できます：
bash
```
rvm install ruby 3.4.7
```

CocoaPods をインストールします：

bash

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

GitHub から rbenv をまだインストールしていない場合は、インストールします。
Ruby をインストールします。特定のバージョンを選択できます：
bash
```
rbenv install 3.4.7
```
Ruby のバージョンを特定のディレクトリに対してローカルに設定するか、マシン全体に対してグローバルに設定します：
bash
```
rbenv global 3.4.7
```

CocoaPods をインストールします：

bash

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

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

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

bash

sudo gem install cocoapods

Homebrew による CocoaPods のインストールは、互換性の問題を引き起こす可能性があります。
CocoaPods をインストールする際、Homebrew は Xcode での作業に必要な Xcodeproj gem もインストールします。しかし、これは Homebrew では更新できず、インストールされた Xcodeproj が最新の Xcode バージョンをまだサポートしていない場合、Pod のインストール時にエラーが発生します。その場合は、他のツールを使用して CocoaPods をインストールしてみてください。

Homebrew をまだインストールしていない場合は、インストールします。
CocoaPods をインストールします：
bash
```
brew install cocoapods
```

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

プロジェクトの作成

CocoaPods 環境が整ったら、Kotlin マルチプラットフォームプロジェクトを Pod と連携するように構成できます。以下の手順は、新しく生成されたプロジェクトでの構成方法を示しています：

Kotlin Multiplatform IDE プラグインまたは Kotlin Multiplatform Web ウィザードを使用して、Android および iOS 用の新しいプロジェクトを生成します。 Web ウィザードを使用する場合は、アーカイブを解凍し、IDE でプロジェクトをインポートします。
バージョンカタログ（gradle/libs.versions.toml ファイル）の [plugins] ブロックに、Kotlin CocoaPods Gradle プラグインを追加します：
toml
```
[plugins]
kotlinCocoapods = { id = "org.jetbrains.kotlin.native.cocoapods", version.ref = "kotlin" }
```
プロジェクトのルートにある build.gradle.kts ファイルに移動し、plugins {} ブロックに以下のエイリアスを追加します：
kotlin
```
alias(libs.plugins.kotlinCocoapods) apply false
```
CocoaPods を統合したいモジュール（例：sharedLogic モジュール）を開き、その build.gradle.kts ファイルの plugins {} ブロックに以下のエイリアスを追加します：
kotlin
```
alias(libs.plugins.kotlinCocoapods)
```

これで、Kotlin マルチプラットフォームプロジェクトで CocoaPods を構成する準備が整いました。

プロジェクトの構成

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

プロジェクトの共有モジュールの build.gradle(.kts) で、Kotlin マルチプラットフォームプラグインとともに CocoaPods プラグインを適用します。
IDE プラグインまたは Web ウィザードでプロジェクトを作成した場合は、この手順をスキップしてください。
kotlin
```
plugins {
    kotlin("multiplatform") version "2.3.0"
    kotlin("native.cocoapods") version "2.3.0"
}
```

cocoapods ブロック内で、Podspec ファイルの version、summary、homepage、および baseName を構成します：

kotlin

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

kotlin {
    cocoapods {
        // 必須プロパティ
        // ここで必要な Pod のバージョンを指定します
        // 指定しない場合は Gradle プロジェクトのバージョンが使用されます
        version = "1.0"
        summary = "Some description for a Kotlin/Native module"
        homepage = "Link to a Kotlin/Native module homepage"

        // 任意プロパティ
        // Gradle プロジェクト名を変更する代わりに、ここで Pod 名を構成します
        name = "MyCocoaPod"

        framework {
            // 必須プロパティ              
            // フレームワーク名の構成。非推奨の 'frameworkName' の代わりにこのプロパティを使用してください
            baseName = "MyFramework"
            
            // 任意プロパティ
            // フレームワークのリンクタイプを指定します。デフォルトは dynamic です。
            isStatic = false
            // 依存関係のエクスポート
            // 他のプロジェクトモジュールがある場合は、コメントを解除して指定してください：
            // export(project(":<your other KMP module>"))
            transitiveExport = false // これがデフォルトです。
        }

        // カスタム Xcode 構成を NativeBuildType にマッピングします
        xcodeConfigurationToNativeBuildType["CUSTOM_DEBUG"] = NativeBuildType.DEBUG
        xcodeConfigurationToNativeBuildType["CUSTOM_RELEASE"] = NativeBuildType.RELEASE
    }
}

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

IntelliJ IDEA で Build | Reload All Gradle Projects を実行する（または Android Studio で File | Sync Project with Gradle Files を実行する）と、プロジェクトが再インポートされます。
Xcode ビルド中の互換性の問題を避けるために、Gradle ラッパーを生成します。

適用されると、CocoaPods プラグインは以下の処理を行います：

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

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

Xcode 用に Podfile を更新する

Kotlin プロジェクトを Xcode プロジェクトにインポートする場合：

Kotlin プロジェクトの iOS 部分で、Podfile を変更します：
- プロジェクトに Git、HTTP、またはカスタム Podspec リポジトリの依存関係がある場合は、Podfile で Podspec へのパスを指定します。
  例えば、podspecWithFilesExample への依存関係を追加する場合、Podfile で Podspec へのパスを宣言します：
  ruby
```
target 'ios-app' do
   # ... 他の依存関係 ...
   pod 'podspecWithFilesExample', :path => 'cocoapods/externalSources/url/podspecWithFilesExample' 
end
```
  :path には Pod へのファイルパスを含める必要があります。
- カスタム Podspec リポジトリからライブラリを追加する場合は、Podfile の冒頭で spec の場所を指定します：
  ruby
```
source 'https://github.com/Kotlin/kotlin-cocoapods-spec.git'

target 'kotlin-cocoapods-xcproj' do
    # ... 他の依存関係 ...
    pod 'example'
end
```
プロジェクトディレクトリで pod install を実行します。
初めて pod install を実行すると、.xcworkspace ファイルが作成されます。このファイルには、元の .xcodeproj と CocoaPods プロジェクトが含まれています。
.xcodeproj を閉じ、代わりに新しい .xcworkspace ファイルを開きます。これにより、プロジェクトの依存関係に関する問題を回避できます。
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 の Web サイトを参照してフレームワークをインストールしてください。

バージョンの互換性

最新の Kotlin バージョンの使用を推奨します。この CocoaPods セットアップに必要な最小バージョンは 1.7.0 です。

Xcode 使用時のビルドエラー

CocoaPods のインストール状況によっては、Xcode でビルドエラーが発生することがあります。通常、Kotlin Gradle プラグインは PATH 内の pod 実行ファイルを見つけますが、環境によってこれが一致しない場合があります。

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

コードエディターを使用する場合、local.properties ファイルに以下の行を追加します：
text
```
kotlin.apple.cocoapods.bin=/Users/Jane.Doe/.rbenv/shims/pod
```
ターミナルを使用する場合、以下のコマンドを実行します：
shell
```
echo -e "kotlin.apple.cocoapods.bin=$(which pod)" >> local.properties
```

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

Pod をインストールする際、C interop の問題に関連して module 'SomeSDK' not found や framework 'SomeFramework' not found というエラーが発生することがあります。このようなエラーを解決するには、以下の解決策を試してください：

パッケージの更新

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

RVMRbenvHomebrew

RVM を更新します：
bash
```
rvm get stable
```
Ruby のパッケージマネージャーである RubyGems を更新します：
bash
```
gem update --system
```
インストールされているすべての gem を最新バージョンにアップグレードします：
bash
```
gem update
```

Rbenv を更新します：
bash
```
cd ~/.rbenv
git pull
```
Ruby のパッケージマネージャーである RubyGems を更新します：
bash
```
gem update --system
```
インストールされているすべての gem を最新バージョンにアップグレードします：
bash
```
gem update
```

Homebrew パッケージマネージャーを更新します：
bash
```
brew update
```
インストールされているすべてのパッケージを最新バージョンにアップグレードします：
bash
```
brew upgrade
```

フレームワーク名の指定

ダウンロードされた Pod ディレクトリ [shared_module_name]/build/cocoapods/synthetic/IOS/Pods/... 内で module.modulemap ファイルを探します。
モジュール内のフレームワーク名を確認します（例：SDWebImageMapKit {}）。フレームワーク名が Pod 名と一致しない場合は、明示的に指定してください：
kotlin
```
pod("SDWebImage/MapKit") {
    moduleName = "SDWebImageMapKit"
}
```

ヘッダーの指定

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

kotlin

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

詳細については CocoaPods のドキュメントを確認してください。解決しない場合は、YouTrack で問題を報告してください。

アプリバンドル内のリソースが見つからない

iOS アプリのビルドには成功するが起動時にクラッシュする場合、またはカスタムフォントや画像などのリソースが最終的な .ipa パッケージに含まれていない場合、Pod とプロジェクトの統合方法に問題がある可能性があります。

この問題を回避するには: pod install コマンドを直接実行するのではなく、Kotlin CocoaPods Gradle プラグインが提供する Gradle の podInstall タスクを使用してください。このタスクは必要なディレクトリを作成し、すべてを自動的に構成します：

bash

./gradlew podInstall
open iosApp/iosApp.xcworkspace

問題が発生する理由: クリーンなプロジェクト（例えば、リポジトリをクローンした後や CI/CD パイプラインで作業している場合）でネイティブの pod install コマンドを実行すると、リソースディレクトリがまだ作成されていません。Compose Multiplatform Gradle プラグインは、生成された .podspec ファイル内でリソースの場所を指定しています（spec.resources = ['build/compose/cocoapods/compose-resources']）。しかし、そのパスはビルド後にのみ存在します。その結果、CocoaPods は存在しないディレクトリを無視し、これらのリソースを含めずに Xcode プロジェクトを構成します。プロジェクトがビルドされリソースが生成されても、Xcode はそれらを最終的なバンドルにコピーしません。

Rsync エラー

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

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

アプリケーションターゲットでユーザースクリプトのサンドボックス化を無効にします：
サンドボックス化されていた可能性のある Gradle デーモンプロセスを停止します：
shell
```
./gradlew --stop
```

以前のバージョン

CocoaPods の概要とセットアップ

CocoaPods を使用するための環境構築

プロジェクトの作成

プロジェクトの構成

Xcode 用に Podfile を更新する

考えられる問題と解決策

CocoaPods のインストール

Ruby のインストール

バージョンの互換性

Xcode 使用時のビルドエラー

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

パッケージの更新

フレームワーク名の指定

ヘッダーの指定

アプリバンドル内のリソースが見つからない

Rsync エラー

次のステップ

CocoaPods の概要とセットアップ ​

CocoaPods を使用するための環境構築 ​

プロジェクトの作成 ​

プロジェクトの構成 ​

Xcode 用に Podfile を更新する ​

考えられる問題と解決策 ​

CocoaPods のインストール ​

Ruby のインストール ​

バージョンの互換性 ​

Xcode 使用時のビルドエラー ​

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

パッケージの更新 ​

フレームワーク名の指定 ​

ヘッダーの指定 ​

アプリバンドル内のリソースが見つからない ​

Rsync エラー ​

次のステップ ​

CocoaPods の概要とセットアップ

CocoaPods を使用するための環境構築

プロジェクトの作成

プロジェクトの構成

Xcode 用に Podfile を更新する

考えられる問題と解決策

CocoaPods のインストール

Ruby のインストール

バージョンの互換性

Xcode 使用時のビルドエラー

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

パッケージの更新

フレームワーク名の指定

ヘッダーの指定

アプリバンドル内のリソースが見つからない

Rsync エラー

次のステップ