CocoaPods 概述与设置

Kotlin/Native provides integration with the CocoaPods dependency manager. You can add dependencies on Pod libraries as well as use a multiplatform project with native targets as a CocoaPods dependency.

You can manage Pod dependencies directly in IntelliJ IDEA and enjoy all the additional features such as code highlighting and completion. You can build the whole Kotlin project with Gradle and not ever have to switch to Xcode.

Use Xcode only when you need to write Swift/Objective-C code or run your application on a simulator or device. To work correctly with Xcode, you should update your Podfile.

Depending on your project and purposes, you can add dependencies between a Kotlin project and a Pod library as well as a Kotlin Gradle project and an Xcode project.

Set up an environment to work with CocoaPods

Install the CocoaPods dependency manager:

sudo gem install cocoapods

If your current version of Kotlin is earlier than 1.7.0, additionally install the cocoapods-generate plugin:

sudo gem install cocoapods-generate

Mind that cocoapods-generate couldn't be installed on Ruby 3.0.0 and later. If it's your case, downgrade Ruby or upgrade Kotlin to 1.7.0 or later.

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

Add and configure Kotlin CocoaPods Gradle plugin

If your environment is set up correctly, you can create a new Kotlin Multiplatform project and choose CocoaPods Dependency Manager as the iOS framework distribution option. The plugin will automatically generate the project for you.

If you want to configure your project manually:

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

     plugins {
         kotlin("multiplatform") version "1.8.0"
         kotlin("native.cocoapods") version "1.8.0"
     }
    
  2. Configure version, summary, homepage, and baseName of the Podspec file in the cocoapods block:

     plugins {
         kotlin("multiplatform") version "1.8.0"
         kotlin("native.cocoapods") version "1.8.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
                 export(project(":anotherKMMModule"))
                 transitiveExport = false // This is default.
                 // Bitcode embedding
                 embedBitcode(BITCODE)
             }
    
             // Maps custom Xcode configuration to NativeBuildType
             xcodeConfigurationToNativeBuildType["CUSTOM_DEBUG"] = NativeBuildType.DEBUG
             xcodeConfigurationToNativeBuildType["CUSTOM_RELEASE"] = NativeBuildType.RELEASE
         }
     }
    

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

  3. 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 in an Xcode project, you need to make some changes to your Podfile:

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

Re-import the project after making changes in the Podfile.

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

Check out the withXcproject branch of the sample project, which contains an example of Xcode integration with an existing Xcode project named kotlin-cocoapods-xcproj.

Possible issues and solutions

CocoaPods installation

Ruby installation

CocoaPods is built with Ruby, and you can install it with the default Ruby that should be available on macOS. Ruby 1.9 or later has a built-in RubyGems package management framework that help you install the CocoaPods dependency manager.

If you're experiencing problems installing CocoaPods and getting it to work, follow this guide to install Ruby or refer to the RubyGems website to install the framework.

Version compatibility

We recommend using the latest Kotlin version. If your current version is earlier than 1.7.0, you'll need to additionally install the cocoapods-generate plugin.

However, cocoapods-generate is not compatible with Ruby 3.0.0 or later. In this case, downgrade Ruby or upgrade Kotlin to 1.7.0 or later.

Module not found

You may encounter a module 'SomeSDK' not found error that is connected with the C-interop issue. Try these workarounds to avoid this error:

Specify the framework name

  1. Find the module.modulemap file in the downloaded Pod directory:

     [shared_module_name]/build/cocoapods/synthetic/IOS/Pods/[pod_name]
    
  2. Check the framework name inside the module, for example AppsFlyerLib {}. If the framework name doesn't match the Pod name, specify it explicitly:

     pod("AFNetworking") {
         moduleName = "AppsFlyerLib"
     }
    

    Check the definition file

If the Pod doesn't contain a .modulemap file, like the pod("NearbyMessages"), in the generated .def file, replace modules with headers with the pointing main header:

tasks.named<org.jetbrains.kotlin.gradle.tasks.DefFileTask>("generateDefNearbyMessages").configure {
    doLast {
        outputFile.writeText("""
            language = Objective-C
            headers = GNSMessages.h
        """.trimIndent())
    }
}

Check the CocoaPods documentation for more information. If nothing works, and you still encounter this error, report an issue in YouTrack.