From dea64b7c09f422f5ad25382d9f54b4c1fcab20cd Mon Sep 17 00:00:00 2001 From: Ilya Matveev Date: Tue, 2 Apr 2019 21:59:14 +0700 Subject: [PATCH] Docs: Add a CocoaPods integration readme --- COCOAPODS.md | 147 +++++++++++++++++++++++++++++++++++++++++++++ _nav_reference.yml | 4 ++ 2 files changed, 151 insertions(+) create mode 100644 COCOAPODS.md diff --git a/COCOAPODS.md b/COCOAPODS.md new file mode 100644 index 00000000000..5241317a927 --- /dev/null +++ b/COCOAPODS.md @@ -0,0 +1,147 @@ +# CocoaPods integration + +Starting with 1.3.30, an experimental integration with [CocoaPods](https://cocoapods.org/) 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`](https://github.com/JetBrains/kotlin-native/tree/master/samples/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](https://kotlinlang.org/docs/reference/building-mpp-with-gradle.html). + +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](https://guides.cocoapods.org/syntax/podspec.html) +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. + +
+ +```kotlin +// Apply plugins. +plugins { + id("org.jetbrains.kotlin.multiplatform") version "1.3.30" + id("org.jetbrains.kotlin.native.cocoapods") version "1.3.30" +} + +// CocoaPods requires the podspec to have a version. +version = "1.0" + +kotlin { + cocoapods { + // Configure fields required by CocoaPods. + summary = "Some description for a Kotlin/Native module" + homepage = "Link to a Kotlin/Native module homepage" + } +} +``` + +
+ +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. +Fields`summary` and `homepage` can be configured using the `cocoapods` code block. + +This podspec file can be referenced from a [Podfile](https://guides.cocoapods.org/using/the-podfile.html) +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: + +0. Make sure that you have CocoaPods [installed](https://guides.cocoapods.org/using/getting-started.html#installation). +We recommend using CocoaPods 1.6.1 or later. + +1. Configure a Gradle project: apply the `org.jetbrains.kotlin.native.cocoapods` plugin, add +and configure the targets, and specify the required podspec fields. + +2. 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](https://docs.gradle.org/current/userguide/gradle_wrapper.html). + To generate the wrapper automatically during execution of the `podspec` task, + run it with the parameter `-Pkotlin.native.cocoapods.generate.wrapper=true`. + +3. Add a reference to the generated podspec in a Podfile of the Xcode project. + +
+ + ```ruby + target 'my-ios-app' do + pod 'my_kotlin_library', :path => 'path/to/my-kotlin-library' + end + ``` + +
+ +4. Run `pod install` for the Xcode project. + +After completing these steps, you can +open the generated workspace (see [CocoaPods documentation](https://guides.cocoapods.org/using/using-cocoapods.html#installation)) +and run an Xcode build. + +## Interoperability + +The CocoaPods plugin also allows using CocoaPods libraries without manual configuring cinterop +parameters (see the [corresponding section](https://kotlinlang.org/docs/reference/building-mpp-with-gradle.html#cinterop-support) +of the multiplatform plugin documentation). The `cocoapods { ... }` code block allows you to +add dependencies on CocoaPods libraries. + +
+ +```kotlin +kotlin { + cocoapods { + // Configure a dependency on AFNetworking. + // The CocoaPods version notation is supported. + // The dependency will be added to all macOS and iOS targets. + pod("AFNetworking", "~> 3.2.0") + } +} +``` + +
+ +To use these dependencies from a Kotlin code, import a package `cocoapods.`. +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!`](https://guides.cocoapods.org/syntax/podfile.html#use_modular_headers_bang) +or [`use_frameworks!`](https://guides.cocoapods.org/syntax/podfile.html#use_frameworks_bang) +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 built this module only from an Xcode project. + Otherwise the CocoaPods library cannot be resolved by the Kotlin/Native infrastructure. + - [Subspecs](https://guides.cocoapods.org/syntax/podspec.html#group_subspecs) are not supported. diff --git a/_nav_reference.yml b/_nav_reference.yml index 4312fcf765b..5db5d226532 100644 --- a/_nav_reference.yml +++ b/_nav_reference.yml @@ -22,6 +22,10 @@ url: objc_interop.html title: "Objective-C and Swift Interop" +- md: COCOAPODS.md + url: cocoapods.html + title: "CocoaPods Integration" + - md: GRADLE_PLUGIN.md url: gradle_plugin.html title: "Gradle Plugin"