coco
114 lines
4.7 KiB
Markdown
114 lines
4.7 KiB
Markdown
# 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](https://play.kotlinlang.org/hands-on/Targeting%20iOS%20and%20Android%20with%20Kotlin%20Multiplatform/01_Introduction)
|
|
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](https://guides.cocoapods.org/using/getting-started.html).
|
|
|
|
## 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. 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](https://kotlinlang.org/docs/reference/native/cocoapods.html)
|
|
|
|
## 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, '15.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 KaMP Kit 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 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.
|
|
|
|
|
|
## 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
|
|
```
|