KMMBridgespmUsing Swift Package Manager

Using Swift Package Manager

Swift Package Manager (SPM) is Apple’s official dependency manager for Xcode. It is in some ways simpler to use than CocoaPods, but is also fairly restrictive.

Out of the box, the official Kotlin tools have no integration with SPM. Publishing binaries for SPM using KMMBridge is fairly straightforward, but local development using SPM has no official Kotlin tooling support. KMMBridge provides some support for local SPM development.

If you have never published a custom private SPM library or tried to use one from Xcode, it is highly recommended that you follow the KMMBridge SPM Quick Start to become familiar with a working example before attempting a manual setup.

Kotlin Project Configuration

After setting up KMMBridge in your Kotlin project, you should configure SPM for library publishing. Some critical points to understand about SPM:

  • It uses git repos as the organization unit for a dependency. One dependency, one git repo.
  • SPM expects the metadata file Package.swift to be in the root of the git repo. We strongly suggest not attempting to put it somewhere else.
  • SPM uses git tags for versions. It also expects those versions to conform to strict semantic versioning conventions.

If you plan to publish your SPM binaries from an Android repo and your Android repo uses git tags (or GitHub releases, which are based on git tags) for anything else, you should consider using an external repo to version your SPM builds.

On the other hand, if you are using a separate repo for your KMP builds, we would recommend using that repo’s git tags for SPM versions.

KMMBridge itself does not version your SPM builds. You’ll need to commit and tag the repo where your SPM publications live. The only exception to this is with the GitHub release artifact manager. It creates a GitHub release to publish the XCFramework.zip binary to, which automatically generates a tag. However, it’s a bit more complicated than that. See the doc for details.

Configuration

In the kmmbridge block, add spm().

kmmbridge {
    spm()
    // Other config...
}

Package.swift path

You can specify the relative path to where KMMBridge should write the updated Package.swift file. KMMBridge assumes you want the Package.swift file at the root of your repo. If unspecified, KMMBridge will query git to find the root.

SPM expects to find Package.swift at the root of your repo. The only reasonable case to put it somewhere else is if your main SPM Package.swift file explicitly includes it.

kmmbridge {
    spm(spmDirectory = "../")
}

Specifying Swift tools version

You can specify the Swift tools version. The current default is 5.3, but you can specify the value:

kmmbridge {
    spm(swiftToolVersion = "5.10")
}

Specifying platform versions

You can specify platform versions in the spm config:

kmmbridge {
    spm {
        iOS("17.1")
        tvOS("10")
    }
}

Platforms that you can specify:

  • iOS - default “16”
  • macOS - default “13”
  • tvOS - default “16.1”
  • watchOS - default “9”

If you specify a platform in the SPM config, but do not define a build target to generate a binary for that platform, KMMBridge does not add that platform to Package.swift.

Using a custom package file

By default, KMMBridge fully manages your Package.swift file. This might not be what you want, if your published library needs to include more than just your Kotlin framework. If you need to customize your package file, pass the useCustomPackageFile flag when configuring SPM in KMMBridge:

kmmbridge {
    ...
    spm(useCustomPackageFile = true)
}

When this flag is set, rather than regenerating your entire package file during publication, KMMBridge will only update the variables it sets at the top of the package file. You are now responsible for using them correctly when making changes.

This works by replacing a block of code that begins with the comment // BEGIN KMMBRIDGE VARIABLES BLOCK (do not edit) and ends with the comment // END KMMBRIDGE BLOCK.

The local dev flow using the spmDevBuild gradle task is disabled when useCustomPackageFile is true. To support local dev in this mode, you will need to manually configure your Package.swift to point at your local build.

Artifact Authentication

For artifacts that are kept in private storage, you may need to add authentication information so your ~/.netrc file or your Mac’s Keychain Access. See Xcode and Binary File Authentication for a description of how to set up private file access.

Xcode Configuration

Open or create an Xcode project. To add an SPM package, go to File > Add Packages in the Xcode menu. Add your source control account. You can usually browse for the package at that point, but depending on how many repos you have, it may be easier to copy/paste the repo URL in the top/right search bar. After finding the package, you should generally add the package by version (“Up to Next Major Version” suggested).

Once added, you should be able to import the Kotlin module into Swift/Objc files and build!

Local Kotlin Dev

If you are going to locally build and test Kotlin with SPM, see SPM Local Dev Flow.