CocoaPods Plugin — 정의, KMM용 플러그인 및 설정

CocoaPods Plugin이란?

CocoaPods Plugin(kotlin.cocoapods라고도 함)은 CocoaPods를 Kotlin Multiplatform Mobile과 통합하기 위한 JetBrains의 공식 플러그인입니다. 이 플러그인은 Kotlin Gradle DSL의 일부이며 KMM 모듈의 build.gradle.kts에서 직접 구성됩니다. Podfile 생성 및 유지 관리, .xcworkspace 생성, 포드 종속성 관리를 자동화하여 수동 Xcode 프로젝트 구성의 필요성을 없앱니다.

CocoaPods Plugin 이전에는 KMM 개발자가 수동으로 Podfile을 만들고, pod install을 실행하고, 브리지 헤더를 구성하고, Gradle 종속성과 별도로 포드 버전을 추적해야 했습니다. 이로 인해 버전 불일치와 CI/CD 파이프라인의 어려움이 발생했습니다. 플러그인은 iOS 종속성 관리를 Android 모듈의 Gradle 종속성 관리만큼 간단하게 만들어 이러한 문제를 해결했습니다.

플러그인은 CocoaPods Trunk의 공개 포드와 개인 저장소의 사용자 정의 포드를 모두 지원합니다. 로컬 Podspec 및 git 기반 저장소 작업도 지원됩니다. 플러그인은 Kotlin 1.6.0 이상과 호환되며 개발 머신에 CocoaPods(gem install cocoapods)가 설치되어 있어야 합니다.

CocoaPods Plugin 작동 방식

CocoaPods Plugin은 Gradle 태스크 그래프 수준에서 작동하며 CocoaPods 작업을 위한 특수 태스크를 추가합니다. 주요 태스크로는 podInstall(포드 설치), podGenXcodeWorkspace(.xcworkspace 생성), podBuildDebugFramework(프레임워크의 Debug 버전 빌드)가 있습니다. 플러그인은 build.gradle.kts의 cocoapods 섹션을 분석하고 선언된 종속성을 기반으로 Podfile을 만든 다음 필요한 매개변수로 pod install을 실행합니다.

플러그인 아키텍처에는 세 가지 구성 요소가 있습니다: build.gradle.kts용 DSL 확장, Podfile 생성을 위한 Podfile 생성기, .xcworkspace 구성을 위한 Xcode 통합 계층입니다. DSL 확장은 종속성 선언을 위한 중첩 pod() 함수, 개인 저장소 지정을 위한 specRepo(), 출력 프레임워크 구성을 위한 framework { }와 함께 cocoapods { } 블록을 제공합니다. Podfile 생성기는 이러한 선언을 CocoaPods가 이해하는 Ruby 구문으로 변환합니다.

kotlin {
    cocoapods {
        summary = "Shared module for iOS project"
        homepage = "https://itsectr.com"
        framework {
            baseName = "Shared"
            isStatic = true
            export(project(":core"))
        }
        pod("Alamofire") {
            version = "~> 5.9"
        }
        pod("Kingfisher") {
            version = "7.12"
        }
    }
}

podInstall 태스크 수명 주기

podInstall을 실행하면 플러그인이 순차적으로: 프로젝트 루트에 Podfile을 생성하고, 명령줄을 통해 pod install을 실행하고, .xcworkspace를 생성하고, 포드 버전이 선언된 것과 일치하는지 확인하고, Podfile.lock을 캐시합니다. 구성 변경 없이 후속 실행할 때 Podfile.lock이 변경되지 않은 경우 podInstall을 건너뜁니다. 이는 깨끗한 설치에 pod install이 최대 2-3분이 소요될 수 있는 CI/CD에서 시간을 절약합니다.

KMM 프로젝트에서 CocoaPods Plugin 설정

CocoaPods Plugin 설정에는 여러 단계가 필요합니다. 개발 머신에 CocoaPods 설치(gem install cocoapods)가 필수 조건입니다. 그런 다음 공유 모듈의 build.gradle.kts에 프레임워크 구성 및 종속성과 함께 cocoapods { } 블록을 추가합니다. 구성 후 podInstall 태스크를 실행하면 Podfile이 생성되고 포드가 설치됩니다. 생성된 .xcworkspace는 Podfile 옆 프로젝트 루트에 위치합니다.

플러그인은 Xcode Build Phases와 통합됩니다. iOS 앱을 빌드할 때 Xcode는 embedAndSignAppleFrameworkForXcode를 실행합니다. 이는 Kotlin/Native 프레임워크를 앱 번들에 복사하는 태스크입니다. CocoaPods Plugin은 .xcworkspace를 생성할 때 이 빌드 단계를 자동으로 추가합니다. .xcworkspace가 생성된 경우 포드 종속성으로 올바르게 빌드하려면 .xcodeproj 대신 열어야 합니다.

코드 예제: 포드 구성

CocoaPods Plugin에서 포드를 선언하는 다양한 시나리오를 살펴보겠습니다. 기본 사례는 버전을 지정하여 CocoaPods Trunk에서 공개 포드를 연결하는 것입니다. 더 복잡한 시나리오에는 사용자 정의 podspec, 로컬 포드 및 git 저장소의 포드 사용이 포함됩니다.

kotlin {
    iosArm64()
    iosSimulatorArm64()

    cocoapods {
        framework {
            baseName = "Shared"
            isStatic = false
        }

        // CocoaPods Trunk의 공개 포드
        pod("Alamofire") { version = "5.9.0" }

        // 연산자가 포함된 사용자 정의 버전
        pod("SnapKit") { version = "~> 5.6" }

        // 개인 저장소의 포드
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // 경로가 있는 로컬 포드
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

        // git 저장소의 포드
        pod(name = "PrivateSDK",
            git = "https://git.itsectr.com/ios/sdk.git",
            tag = "2.1.0")
    }
}

포드 연결은 구성의 일부일 뿐입니다. 플러그인은 다른 Kotlin 모듈의 종속성을 iOS 프레임워크로 내보내기도 가능합니다. export(project(":core")) 함수는 :core 모듈의 모든 공개 API가 생성된 프레임워크의 Objective-C 헤더에서 액세스 가능해야 함을 지정합니다. 이는 공유 Kotlin 코드가 다른 모듈의 클래스를 사용하고 Swift에서 액세스할 수 있어야 할 때 필요합니다.

cocoapods {
    framework {
        baseName = "Shared"
        // 모듈을 iOS 프레임워크로 내보내기
        export(project(":network"))
        export(project(":domain"))

        // 정적 또는 동적 링킹
        isStatic = true
    }

    // 내보낸 모듈에 필요한 포드
    pod("Moya") { version = "15.0" }
}

빌드 및 테스트

구성 후 Podfile을 생성하고 종속성을 설치하려면 podInstall을 실행해야 합니다. 그런 다음 생성된 .xcworkspace를 Xcode에서 열어 표준 방식으로 앱을 빌드할 수 있습니다. CI/CD의 경우 빌드 머신에 CocoaPods와 Ruby가 설치되어 있는지 확인하세요. 플러그인은 CI 환경에서 작업하기 위한 --no-daemon 플래그를 지원합니다.

// 포드 설치 시 Podfile + xcworkspace 생성
./gradlew :shared:podInstall

// 테스트용 디버그 프레임워크 빌드
./gradlew :shared:podBuildDebugFramework

// 명령줄에서 전체 iOS 빌드
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager(SPM)는 Apple의 대체 종속성 관리자로 인기를 얻고 있으며 iOS 커뮤니티에서 점차 CocoaPods를 대체하고 있습니다. 그러나 CocoaPods Plugin은 여러 이유로 여전히 중요합니다. SPM은 KMM 컨텍스트에서 동적 프레임워크를 지원하지 않으며 SPM을 통한 Kotlin/Native 프레임워크 통합에는 추가 설정이 필요합니다. CocoaPods Plugin은 더 성숙하고 문서화된 통합 경로를 제공합니다.

CocoaPods Plugin과 직접 SPM 통합의 비교는 전자가 자동화에서 우세하고 후자가 기본 Apple 지원에서 우세함을 보여줍니다. CocoaPods Plugin은 Podfile을 자동으로 생성하고, 버전을 관리하며, Xcode Build Phases를 구성합니다. SPM은 Package.swift를 통해 Kotlin 프레임워크를 수동으로 연결해야 하므로 대규모 KMM 프로젝트에서 유지 관리가 더 어렵습니다. JetBrains는 Kotlin/Native용 SPM 지원을 작업 중이지만 2025년 현재 SPM 통합은 실험적입니다.

일반적인 문제 및 해결 방법

CocoaPods Plugin을 사용할 때 KMM 개발자는 몇 가지 일반적인 문제에 직면합니다. 포드 버전 충돌은 가장 흔한 문제로, 두 포드가 동일한 종속성의 다른 버전을 필요로 하는 경우입니다. 해결 방법은 pod("Dependency") { version = "x.x" }를 통해 충돌하는 종속성의 버전을 명시적으로 지정하는 것입니다. 두 번째 일반적인 경우는 포드가 KMM 프로젝트의 최소 버전보다 최신 iOS SDK를 필요로 하는 버전 비호환성입니다.

.xcworkspace 문제는 플러그인 구성 후 .xcodeproj 대신 .xcworkspace를 열지 않을 때 발생합니다. 플러그인은 podInstall 로그에서 이에 대해 경고합니다. 또 다른 빈번한 오류는 개발 머신에 CocoaPods가 없는 경우입니다. 플러그인은 podInstall을 실행하기 전에 pod 명령의 존재를 확인하고 명확한 오류 메시지를 표시합니다. CI/CD의 경우 CocoaPods를 설치하세요: gem install cocoapods.

// 버전 충돌 해결
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // 충돌을 명시적으로 해결
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// Gradle을 통해 CocoaPods 설치 확인
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("CocoaPods 버전: $result")
    }
}

podInstall 디버깅

podInstall이 실패하면 자세한 출력을 위해 --info 플래그를 사용하세요: ./gradlew podInstall --info. 플러그인은 각 단계(Podfile 생성, pod install 실행, Podfile.lock 파싱)를 로그에 기록합니다. 대부분의 경우 오류는 네트워크 문제(CocoaPods Trunk를 사용할 수 없음) 또는 잘못된 Podfile 구문과 관련됩니다. 이러한 경우 CocoaPods에서 더 자세한 오류 메시지를 얻기 위해 프로젝트 루트에서 수동으로 pod install을 실행해 보세요.