# 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
        linkerOpts("-lsqlite3")
        export(libs.touchlab.kermit.simple)       
    }
    extraSpecAttributes["swift_version"] = "\"5.0\"" // <- SKIE Needs this!
    podfile = project.file("../ios/Podfile")
}
```
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
```