Skip to content

Latest commit

 

History

History
94 lines (62 loc) · 4.77 KB

IOS_PROJ_INTEGRATION.md

File metadata and controls

94 lines (62 loc) · 4.77 KB
Raw

Integrating with Existing iOS Projects

There are two primary ways to add a KMP library to your existing iOS project: with or without Cocoapods. Cocoapods is the much simpler method of adding your library. By generating a file in gradle you can easily insert your library into your iOS project without worrying about build phases or targets. It's simple and ease-of-use, and we recommend that you use Cocoapods.

If you don't want to use Cocoapods to add a KMP library to your iOS project, then you can follow the steps in this guide from Jetbrains about how to add the library to your iOS project manually.

If you don't have Cocoapods installed, then follow the instructions in their official installation guide.

Cocoapods Overview

Explaining all of cocoapods is not within the scope of this document, however a basic introduction could be helpful in understanding how to integrate Kotlin Native into your iOS Project. In short, cocoapods is a dependency manager which uses a Podfile to reference a list of dependencies, or pods, that are to be injected. Each pod has a reference spec document, or a podspec, which details the pods name, version, source, and other information. By using cocoapods, we can reference our shared library and have it directly injected into the iOS Project.

Cocoapods gradle Integration

Starting with 1.3.30, Kotlin has provided a gradle plugin which allows the Kotlin Native library to be referenced as a Cocoapods dependency (As of #76, KampKit uses a Touchlab fork of this plugin to expand it's capabilities). The integration adds a gradle task that generates a podspec that includes everything needed to be referenced by cocoapods. We are using an extension of the available cocoapods code block to customize our podspec, which is located in the shared/build.gradle.

cocoapodsext {
    summary = "Common library for the KaMP starter kit"
    homepage = "https://github.com/touchlab/KaMPKit"
    framework {
        isStatic = false
        export(Deps.kermit)
        transitiveExport = true
    }
}

Note that you need to apply the co.touchlab.native.cocoapods plugin for the forked plugin.

The framework block is used to configure the framework generated by cocoapods. In this case we use isStatic = false to build a dynamic framework (Debugging has issues in static frameworks). The export settings allow configuring and logging with Kermit in swift. Normally dependencies of your shared module aren't included in the export.

To generate the podspec, run the podspec command, or ./gradlew podspec. This wil generate the podspec in the root library folder.

For more detailed information about the integration, see more here

Create Podfile

If your iOS project doesn't have a Podfile yet, you'll need one. If your project is already using Cocoapods, then skip ahead to the next section.

In the command line, run touch Podfile in your iOS project's root directory. Then paste the following into your new Podfile:

use_frameworks!

platform :ios, '9.0'

install! 'cocoapods', :deterministic_uuids => false

target 'YourIosAppTargetName' do
   // Pods go here
end

Now, replace YourIosAppTargetName with, you guessed it, your iOS app's target name. In the KaMPKit iOS sample app, that would be KaMPKitIos.

Add KMP Pod

Add the following line in your target block (replace // Pods go here in our example above):

    pod 'shared', :path => '~/[PATH_TO_KaMPKit/shared/]'

Next, replace ~/[PATH_TO_KaMPKit/shared/] with the path to your KaMPKit/shared/ directory. For example:

    pod 'shared', :path => '~/Desktop/KaMPKit/shared/'

This path can be either absolute or relative, but we realize that your KaMPKit project and your existing iOS project might be in very different places, so we're using an absolute path as an example for simplicity's sake.

Install and Run

Save the changes to your Podfile. Go back to the command line, and in your iOS project's root directory, run pod install.

This command will create a Pods/ folder and a .xcworkspace file in your iOS project's root directory. Open the .xcworkspace file. Remember that if your project was already using Cocoapods, and you had your .xcworkspace file open in Xcode, you need to close and reopen it.

From now on, you will work out of the .xcworkspace file instead of the .xcodeproj file (which is part of your .xcworkspace). To use code from your shared KMP library, at the top of the .swift file where you want to use it, add:

import shared