CocoaPods overview and setup

Set up an environment to work with CocoaPods

Install the CocoaPods dependency manager using the installation tool of your choice:

If you encounter problems during the installation, check the Possible issues and solutions section.

Create a project

When your CocoaPods environment is set up, you can configure your Kotlin Multiplatform project to work with Pods. The following steps show the configuration on a freshly generated project:

1. Generate a new project for Android and iOS using the Kotlin Multiplatform IDE plugin or the Kotlin Multiplatform web wizard. If using the web wizard, unpack the archive and import the project in your IDE.

2. Add the Kotlin CocoaPods Gradle plugin to the version catalog (the gradle/libs.versions.toml file):

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

3. Navigate to the root build.gradle.kts file of your project and add the following alias to the plugins {} block:

   alias(libs.plugins.kotlinCocoapods) apply false

4. Open the module where you want to integrate CocoaPods, for example, the sharedLogic module, and add the following alias to the plugins {} block of the build.gradle.kts file:

   alias(libs.plugins.kotlinCocoapods)

Now you are ready to configure CocoaPods in your Kotlin Multiplatform project.

Configure the project

To configure the Kotlin CocoaPods Gradle plugin in your multiplatform project:

1. In the shared module's build.gradle(.kts) of your project, apply the CocoaPods plugin as well as the Kotlin Multiplatform plugin.

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

2. Configure version, summary, homepage, and baseName of the Podspec file in the cocoapods block:

   plugins { kotlin("multiplatform") version "2.4.0" kotlin("native.cocoapods") version "2.4.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 } }

3. Run Build | Reload All Gradle Projects in IntelliJ IDEA (or File | Sync Project with Gradle Files in Android Studio) to re-import the project.

4. Generate the Gradle wrapper to avoid compatibility issues during an Xcode build.

When applied, the CocoaPods plugin does the following:

• Adds both debug and release frameworks as output binaries for all macOS, iOS, tvOS, and watchOS targets.

• Creates a podspec task which generates a Podspec file for the project.

The Podspec file includes a path to an output framework and script phases that automate building this framework during the build process of an Xcode project.

Update Podfile for Xcode

If you want to import your Kotlin project to an Xcode project:

1. In the iOS part of your Kotlin project, make changes to the Podfile:

   • If your project has any Git, HTTP, or custom Podspec repository dependencies, specify the path to the Podspec in the Podfile.

     For example, if you add a dependency on podspecWithFilesExample, declare the path to the Podspec in the Podfile:

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

     The :path should contain the filepath to the Pod.

   • If you add a library from the custom Podspec repository, specify the location of specs at the beginning of your Podfile:

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

2. Run pod install in your project directory.

   When you run pod install for the first time, it creates the .xcworkspace file. This file includes your original .xcodeproj and the CocoaPods project.

3. Close your .xcodeproj and open the new .xcworkspace file instead. This way you avoid issues with project dependencies.

4. Run Build | Reload All Gradle Projects in IntelliJ IDEA (or File | Sync Project with Gradle Files in Android Studio) to re-import the project.

If you don't make these changes in the Podfile, the podInstall task will fail, and the CocoaPods plugin will show an error message in the log.

Possible issues and solutions

What's next

• Add dependencies on a Pod library in your Kotlin project

• Set up dependencies between a Kotlin project and an Xcode project

• See the full CocoaPods Gradle plugin DSL reference