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.
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.
Starting with 1.3.30, Kotlin has provided a gradle plugin which allows the Kotlin Native library to
be referenced as a Cocoapods dependency. The integration adds a
gradle task that generates a podspec
that includes everything needed to be referenced by
Cocoapods. Our podspec is located in the shared/build.gradle
.
cocoapods {
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 native.cocoapods
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, for
example the previews don't work). On the other hand, we encountered problems with dynamic frameworks
on Arm64 based simulators, so use isStatic = true
if you need to use a Arm64 simulator. 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 will generate the
podspec in the root library folder.
For more detailed information about the integration, see more here
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, '12.4'
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 KaMP Kit iOS sample
app, that would be KaMPKitiOS
.
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 KaMP Kit 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.
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