Kotlin Tooling Cocoapods Spm Migration

CocoaPods to SwiftPM Migration for KMP

Migrate Kotlin Multiplatform projects from kotlin("native.cocoapods") to swiftPMDependencies {} DSL.

Requirements

• Kotlin: Version with Swift Import support (e.g., 2.4.0-Beta1 or later)
• Xcode: 16.4 or 26.0+
• iOS Deployment Target: 16.0+ recommended

Migration Overview

IMPORTANT: Keep the cocoapods {} block and plugin active until Phase 6. The migration adds swiftPMDependencies {} alongside the existing CocoaPods setup first, reconfigures Xcode, and only then removes CocoaPods.

Phase 1: Pre-Migration Analysis

1.0 Verify the project builds

Before starting migration, identify the module to migrate and confirm it compiles successfully.

1. Find the module that uses CocoaPods — look for build.gradle.kts files containing cocoapods:

   grep -rl "cocoapods" --include="build.gradle.kts" .

   Extract the module name from the path (e.g., ./shared/build.gradle.kts → module name is shared).

2. Build only that module (avoids building the entire multi-module project):

   ./gradlew :moduleName:build

   Replace moduleName with the directory name of the module (e.g., :shared:build).

3. If the targeted build fails, ask the user to either:

   • Provide the correct Gradle command to verify the module builds, or
   • Confirm the module is in a working state and it's safe to proceed

   If the user confirms without providing a build command, record that the pre-migration build could not be verified and warn about this at the end of migration (Phase 7).

1.0a Confirm Kotlin version with Swift Import support

Ask the user:

Does your project already use a Kotlin version with Swift Import support (swiftPMDependencies DSL)?

If yes → read their current Kotlin version from gradle/libs.versions.toml (or build.gradle.kts), record it, and skip Phase 2.2 (no version change needed).

If no → ask:

Please provide the Kotlin version to use (e.g., "2.4.0", "2.4.0-Beta1", "2.4.0-dev-123").

Record the user-provided version. Then ask:

Does this Kotlin version require a custom Maven repository (e.g., JetBrains dev repo)?

• Yes → ask for the repo URL (suggest https://packages.jetbrains.team/maven/p/kt/dev as default). Phase 2.1 will add it.
• No → Phase 2.1 is skipped (no custom repo needed).

Finally, check the project's current Kotlin version. Compare major.minor against the target. If it differs significantly (e.g., 2.1.0 → 2.4.0), warn: "⚠️ Kotlin version jump — upgrading across minor versions can introduce breaking changes unrelated to this migration. Recommended: update first, verify it builds, then re-run." If the user confirms despite the mismatch, proceed.

1.1 Check for deprecated CocoaPods workaround property

Search gradle.properties for the deprecated property:

kotlin.apple.deprecated.allowUsingEmbedAndSignWithCocoaPodsDependencies=true

This property was a workaround (see KT-64096) for projects using embedAndSign alongside CocoaPods dependencies. It suppresses an error about unsupported configurations that can cause runtime crashes or symbol duplication. After migrating to SwiftPM import, this property is no longer needed and must be removed in Phase 6. Record its presence if found.

1.2 Check for EmbedAndSign disablers

Search all build.gradle.kts files for code that disables EmbedAndSign tasks (e.g., TaskGraph.whenReady filters, tasks.matching blocks). This is a CocoaPods-era workaround that breaks the migration because integrateEmbedAndSign (needed in Phase 5) gets disabled too. Record any such code — it must be removed in Phase 6, and may need to be removed earlier. See troubleshooting.md § "integrateEmbedAndSign Skipped" for patterns.

1.3 Check for third-party KMP libraries with bundled cinterop klibs

Some KMP libraries ship pre-built cinterop klibs with cocoapods.* package namespaces. After migration, the swiftPMDependencies cinterop generator detects these existing bindings and skips generating new bindings for those Clang modules to avoid duplicates. This means cocoapods.* imports for those modules must be kept as-is — they resolve to the third-party library's bundled klib, not to actual CocoaPods.

Known libraries with bundled cocoapods.* klibs:

How to detect: Search Gradle dependency declarations for known libraries, then cross-reference their bundled namespaces against the import cocoapods.* statements found in step 4. Mark any matches — these imports will NOT be transformed in Phase 4.

If unsure whether a third-party KMP library bundles cinterop klibs, check if it has a linkOnly = true pod dependency in the project — this is a strong indicator that the library provides its own klib for those classes.

To inspect klib contents and verify bundled bindings, see troubleshooting.md § "Third-Party KMP Libraries with Bundled Klibs".

Find and record:

1. CocoaPods configuration - Search for cocoapods in build.gradle.kts files
2. Pod dependencies - Extract pod names, versions from cocoapods {} blocks
3. Framework configuration - Record baseName, isStatic, deployment target from cocoapods.framework {}
4. linkOnly pods - Record pods declared with linkOnly = true. These pods provide native linking only — cinterop bindings come from a KMP wrapper library (e.g., dev.gitlive:firebase-*). See common-pods-mapping.md for implications.
5. Kotlin imports - Find all import cocoapods.* statements. Cross-reference with step 1.3 to identify which imports come from bundled klibs (and must be preserved) vs. which come from direct pod cinterop (and must be transformed).
6. Map pods to SPM - See common-pods-mapping.md
7. Locate iOS project directory - Find the directory containing Podfile and .xcworkspace:

   find . -name "Podfile" -type f

   Record this path (e.g., iosApp/, ios/, or project root) - needed for Phase 5
8. Check for non-KMP CocoaPods - Determine if the project uses CocoaPods for dependencies other than KMP. This affects cleanup strategy in Phase 5.
9. Check Xcode build phases - Open the .xcodeproj's project.pbxproj and search for the Gradle build phase script. Check if embedAndSignAppleFrameworkForXcode is present but commented out (prefixed with #). If commented out, it must be uncommented during Phase 5 — the integrateEmbedAndSign task may or may not handle this automatically.
10. Check for existing Crashlytics dSYM upload script - If using FirebaseCrashlytics, search project.pbxproj for a dSYM upload shell script phase. Record its current path (CocoaPods-era scripts reference ${PODS_ROOT}/FirebaseCrashlytics/upload-symbols). This must be updated to the SPM path in Phase 5.
11. Identify CocoaPods-related extras in build scripts - Search all build.gradle.kts files for CocoaPods workarounds beyond the standard cocoapods {} block (custom tasks hooking into podInstall, Pods.xcodeproj patching, podspec metadata, extraSpecAttributes, noPodspec(), etc.). See cocoapods-extras-patterns.md for the full pattern list. Record all findings — these will be handled in Phase 6.

Phase 2: Gradle Configuration

Important scope note: Do NOT upgrade the Gradle wrapper version, update KSP, or update any other dependencies during this migration. Those are separate concerns and out of scope. Only change what is listed below.

2.1 Add custom Maven repository (if needed)

Skip this step if the user indicated in Phase 1.0a that their Kotlin version does not require a custom Maven repository (i.e., it is an official release, Beta, or RC available from Maven Central).

For dev/custom builds, add the custom Maven repository (URL from Phase 1.0a) to settings.gradle.kts:

pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
        maven("<custom-repo-url>")  // ADD
    }
}

dependencyResolutionManagement {
    repositories {
        mavenCentral()
        maven("<custom-repo-url>")  // ADD
    }
}

2.2 Update Kotlin version

Skip this step if the user's project already uses a Kotlin version with Swift Import support (recorded in Phase 1.0a).

Update to the version recorded in Phase 1.0a:

# gradle/libs.versions.toml
[versions]
kotlin = "<kotlin-version>"

2.3 Add buildscript constraint (if swiftPMDependencies not recognized)

// root build.gradle.kts
buildscript {
    dependencies.constraints {
        "classpath"("org.jetbrains.kotlin:kotlin-gradle-plugin:<kotlin-version>!!")
    }
}

Replace <kotlin-version> with the version recorded in Phase 1.0a. The !! suffix forces strict version resolution, ensuring no other dependency pulls in a different Kotlin Gradle plugin version.

Phase 3: Add swiftPMDependencies (Keep CocoaPods)

Do NOT remove the cocoapods {} block or kotlin("native.cocoapods") plugin yet. Add swiftPMDependencies {} alongside the existing CocoaPods configuration.

3.1 Add group property

group = "org.example.myproject"  // Required for import namespace

3.2 Add swiftPMDependencies block alongside cocoapods

For each pod dependency, add the equivalent SwiftPM package declaration. Use common-pods-mapping.md to map each pod to its SPM package URL, product name, and importedModules.

Key concepts: products = SPM product names (controls linking). importedModules = Clang module names for cinterop bindings (only when discoverModulesImplicitly = false). discoverModulesImplicitly defaults to true (bindings for all Clang modules); set false when transitive C/C++ modules fail cinterop (Firebase, gRPC), then list needed modules explicitly.

Important: SPM product names and Clang module names don't always match. Always consult common-pods-mapping.md for correct values.

Do not mix the same library suite across CocoaPods and SPM. Libraries that share a common repository (e.g., all Firebase products) share transitive dependencies. Having some products linked via CocoaPods and others via SPM causes duplicate/conflicting symbols and dyld crashes at runtime. When migrating such a suite, move all pods from that suite to SPM at once — including Swift-only pods that Kotlin doesn't use directly. Add Swift-only pods as products entries (no importedModules needed). After adding new products, re-run integrateLinkagePackage to regenerate the linkage Swift package.

kotlin {
    // Keep existing targets
    iosArm64()
    iosSimulatorArm64()
    iosX64()

    swiftPMDependencies {
        iosDeploymentVersion.set("16.0")

        // If using KMP IntelliJ plugin, specify the .xcodeproj path:
        // xcodeProjectPathForKmpIJPlugin.set(
        //     layout.projectDirectory.file("../iosApp/iosApp.xcodeproj")
        // )

        swiftPackage(
            url = url("https://github.com/owner/repo.git"),
            version = from("1.0.0"),
            products = listOf(product("ProductName")),
        )
    }

    cocoapods {
        // ... keep existing cocoapods block for now
    }
}

3.3 Move framework configuration out of cocoapods block

If the cocoapods block contains a framework {} configuration, move it to the binaries API on each target. isStatic = true is recommended — dynamic frameworks have known edge cases with SwiftPM import that can cause linker errors, dyld crashes, or duplicate class warnings:

listOf(iosArm64(), iosSimulatorArm64(), iosX64()).forEach { iosTarget ->
    iosTarget.binaries.framework { baseName = "Shared"; isStatic = true }
}

3.4 Handle dev.gitlive/firebase-kotlin-sdk and similar CocoaPods-era KMP wrappers

If the project uses dev.gitlive:firebase-* or similar KMP wrapper libraries, two additional steps are required:

A. Switch to isStatic = true — dynamic frameworks + Firebase SPM = runtime dyld crash. After switching: re-run integrateLinkagePackage, remove any "Embed Frameworks" copy phase, move linker flags to OTHER_LDFLAGS.

B. Add framework search paths — add conditional -F linkerOpts in build.gradle.kts and matching FRAMEWORK_SEARCH_PATHS in the Xcode project.

See common-pods-mapping.md § dev.gitlive and troubleshooting.md for code snippets and the full product list.

3.5 Add opt-in for cinterop API

kotlin.compilerOptions {
    optIn.add("kotlinx.cinterop.ExperimentalForeignApi")
}

For full DSL reference, see dsl-reference.md.

Phase 4: Kotlin Source Updates

Import Namespace Formula

swiftPMImport.<group>.<module>.<ClassName>

Where:
- group: build.gradle.kts `group` property, dashes (-) → dots (.)
- module: Gradle module name, dashes (-) → dots (.)
- ClassName: Objective-C class name (FIR* for Firebase, GMS* for Google Maps)