CocoaPods overview and setup

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

sudo gem install cocoapods

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

When your environment is set up, you can create a new Kotlin Multiplatform project. For that, use the Kotlin Multiplatform web wizard or the Kotlin Multiplatform plugin for Android Studio.

If you already have a project, you can add and configure the Kotlin CocoaPods Gradle plugin manually:

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

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

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

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

   note

   See the full syntax of Kotlin DSL in the Kotlin Gradle plugin repository.

3. Run Reload All Gradle Projects in IntelliJ IDEA (or 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.

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

1. Make changes in your Podfile:

   • If your project has any Git, HTTP, or custom Podspec repository dependencies, you should 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.

   • When you add a library from the custom Podspec repository, you should also 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 you 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 Reload All Gradle Projects in IntelliJ IDEA (or 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.