CocoaPods integration

Starting with 1.3.30, an experimental integration with CocoaPods is added to Kotlin/Native. This feature allows you to represent a Kotlin/Native Gradle-project as a CocoaPods dependency. Such a representation provides the following advantages:

  • Such a dependency can be included in a Podfile of an Xcode project and automatically built (and rebuilt) along with this project. As a result, importing to Xcode is simplified since there is no need to write corresponding Gradle tasks and Xcode build steps manually.

  • When building from Xcode, you can use CocoaPods libraries without writing .def files manually and setting cinterop tool parameters. In this case, all required parameters can be obtained from the Xcode project configured by CocoaPods.

For an example of CocoaPods integration, refer to the cocoapods sample.

CocoaPods Gradle plugin

The CocoaPods support is implemented in a separate Gradle plugin: org.jetbrains.kotlin.native.cocoapods.

Note: The plugin is based on the multiplatform project model and requires applying the org.jetbrains.kotlin.multiplatform plugin. See details about the multiplatform plugin at the corresponding page.

When applied, the CocoaPods plugin does the following:

  1. Adds both debug and release frameworks as output binaries for all iOS and macOS targets.
  2. Creates a podspec task which generates a podspec file for the given project.

The podspec generated includes a path to an output framework and script phases which automate building this framework during a build process of an Xcode project. Some fields of the podspec file can be configured using the kotlin.cocoapods { ... } code block.

  1. // Apply plugins.
  2. plugins {
  3.     id("org.jetbrains.kotlin.multiplatform") version "1.3.30"
  4.     id("org.jetbrains.kotlin.native.cocoapods") version "1.3.30"
  5. }
  7. // CocoaPods requires the podspec to have a version.
  8. version = "1.0"
  10. kotlin {
  11.     cocoapods {
  12.         // Configure fields required by CocoaPods.
  13.         summary = "Some description for a Kotlin/Native module"
  14.         homepage = "Link to a Kotlin/Native module homepage"
  15.     }
  16. }

The following podspec fields are required by CocoaPods:

  • version
  • summary
  • homepage

A version of the Gradle project is used as a value for the version field. Fieldssummary and homepage can be configured using the cocoapods code block.

This podspec file can be referenced from a Podfile of an Xcode project. After that the framework built from the Kotlin/Native module can be used from this Xcode project. If necessary, this framework is automatically rebuilt during Xcode build process.

Workflow

To import a Kotlin/Native module in an existing Xcode project:

  1. Make sure that you have CocoaPods installed. We recommend using CocoaPods 1.6.1 or later.

  2. Configure a Gradle project: apply the org.jetbrains.kotlin.native.cocoapods plugin, add and configure the targets, and specify the required podspec fields.

  3. Run the podspec task. The podspec file described above will be generated.

    In order to avoid compatibility issues during an Xcode build, the plugin requires using a Gradle wrapper. To generate the wrapper automatically during execution of the podspec task, run it with the parameter -Pkotlin.native.cocoapods.generate.wrapper=true.

  4. Add a reference to the generated podspec in a Podfile of the Xcode project.

    1.  target 'my-ios-app' do
    2.      pod 'my_kotlin_library', :path => 'path/to/my-kotlin-library'
    3.  end

  5. Run pod install for the Xcode project.

After completing these steps, you can open the generated workspace (see CocoaPods documentation) and run an Xcode build.

Interoperability

The CocoaPods plugin also allows using CocoaPods libraries without manual configuring cinterop parameters (see the corresponding section of the multiplatform plugin documentation). The cocoapods { ... } code block allows you to add dependencies on CocoaPods libraries.

  1. kotlin {
  2.     cocoapods {
  3.         // Configure a dependency on AFNetworking.
  4.         // The CocoaPods version notation is supported.
  5.         // The dependency will be added to all macOS and iOS targets.
  6.         pod("AFNetworking", "~> 3.2.0")
  7.     }
  8. }

To use these dependencies from a Kotlin code, import a package cocoapods.<library-name>. In the example above, it’s cocoapods.AFNetworking.

The dependencies declared in this way are added in the podspec file and downloaded during the execution of pod install.

Important: To correctly import the dependencies into the Kotlin/Native module, the Podfile must contain either use_modular_headers! or use_frameworks! directive.

Search paths for libraries added in the Kotlin/Native module in this way are obtained from properties of the Xcode projects configured by CocoaPods. Thus if the module uses CocoaPods libraries, it can be build only from Xcode.

Current Limitations

  • If a Kotlin/Native module uses a CocoaPods library, you can build this module only from an Xcode project. Otherwise the CocoaPods library cannot be resolved by the Kotlin/Native infrastructure.
  • Subspecs are not supported.