CocoaPods 개요 및 설정

이것은 로컬 통합 방식입니다. 다음과 같은 경우에 적합합니다:

CocoaPods를 사용하는 iOS 프로젝트와 함께 모노레포(mono repository) 환경을 구성한 경우.
Kotlin 멀티플랫폼 프로젝트에 CocoaPods 의존성이 있는 경우.

Kotlin/Native는 CocoaPods 의존성 관리자(dependency manager)와의 통합을 지원합니다. Pod 라이브러리에 대한 의존성을 추가하거나 Kotlin 프로젝트를 CocoaPods 의존성으로 사용할 수 있습니다.

CocoaPods 통합 방식은 직접 통합(direct integration)에 사용되는 embedAndSignAppleFrameworkForXcode 메커니즘과 함께 사용할 수 없습니다.

IntelliJ IDEA 또는 Android Studio에서 직접 Pod 의존성을 관리하고 코드 하이라이팅 및 자동 완성 같은 추가 기능을 활용할 수 있습니다. Xcode로 전환하지 않고도 Gradle을 통해 전체 Kotlin 프로젝트를 빌드할 수 있습니다.

Swift/Objective-C 코드를 수정하거나 Apple 시뮬레이터 또는 기기에서 애플리케이션을 실행하려는 경우에만 Xcode가 필요합니다. Xcode에서 작업하려면 먼저 Podfile을 업데이트하세요.

CocoaPods 작업을 위한 환경 설정

원하는 설치 도구를 사용하여 CocoaPods 의존성 관리자를 설치하세요:

RVMRbenvDefault RubyHomebrew

아직 설치되어 있지 않다면 RVM을 설치하세요.
Ruby를 설치합니다. 특정 버전을 선택할 수 있습니다:
bash
```
rvm install ruby 3.4.7
```

CocoaPods를 설치합니다:

bash

sudo gem install -n /usr/local/bin cocoapods

아직 설치되어 있지 않다면 GitHub에서 rbenv를 설치하세요.
Ruby를 설치합니다. 특정 버전을 선택할 수 있습니다:
bash
```
rbenv install 3.4.7
```
Ruby 버전을 특정 디렉터리에 대한 로컬(local) 또는 전체 머신에 대한 글로벌(global)로 설정하세요:
bash
```
rbenv global 3.4.7
```

CocoaPods를 설치합니다:

bash

sudo gem install -n /usr/local/bin cocoapods

이 설치 방법은 Apple M 칩이 탑재된 기기에서는 작동하지 않습니다. CocoaPods 작업을 위한 환경을 설정하려면 다른 도구를 사용하세요.

macOS에서 기본적으로 사용할 수 있는 Ruby를 통해 CocoaPods 의존성 관리자를 설치할 수 있습니다:

bash

sudo gem install cocoapods

Homebrew를 통한 CocoaPods 설치는 호환성 문제를 일으킬 수 있습니다.
CocoaPods를 설치할 때 Homebrew는 Xcode 작업에 필요한 Xcodeproj gem도 함께 설치합니다. 하지만 이는 Homebrew로 업데이트할 수 없으며, 설치된 Xcodeproj가 최신 Xcode 버전을 아직 지원하지 않는 경우 Pod 설치 시 오류가 발생할 수 있습니다. 이런 경우 다른 도구를 사용하여 CocoaPods를 설치해 보세요.

아직 설치되어 있지 않다면 Homebrew를 설치하세요.
CocoaPods를 설치합니다:
bash
```
brew install cocoapods
```

설치 중 문제가 발생하면 발생 가능한 문제 및 해결 방법 섹션을 확인하세요.

프로젝트 생성

CocoaPods 환경이 설정되면 Kotlin 멀티플랫폼 프로젝트가 Pod과 연동되도록 구성할 수 있습니다. 다음 단계는 새로 생성된 프로젝트에서의 구성 방법을 보여줍니다:

Kotlin Multiplatform IDE 플러그인 또는 Kotlin Multiplatform 웹 위저드를 사용하여 Android 및 iOS용 새 프로젝트를 생성하세요. 웹 위저드를 사용하는 경우 압축을 풀고 IDE에서 프로젝트를 가져오세요(import).
버전 카탈로그(version catalog, gradle/libs.versions.toml 파일)의 [plugins] 블록에 Kotlin CocoaPods Gradle 플러그인을 추가하세요:
toml
```
[plugins]
kotlinCocoapods = { id = "org.jetbrains.kotlin.native.cocoapods", version.ref = "kotlin" }
```
프로젝트의 루트 build.gradle.kts 파일로 이동하여 plugins {} 블록에 다음 별칭(alias)을 추가하세요:
kotlin
```
alias(libs.plugins.kotlinCocoapods) apply false
```
CocoaPods를 통합하려는 모듈(예: sharedLogic 모듈)을 열고 build.gradle.kts 파일의 plugins {} 블록에 다음 별칭을 추가하세요:
kotlin
```
alias(libs.plugins.kotlinCocoapods)
```

이제 Kotlin 멀티플랫폼 프로젝트에서 CocoaPods를 구성할 준비가 되었습니다.

프로젝트 구성

멀티플랫폼 프로젝트에서 Kotlin CocoaPods Gradle 플러그인을 구성하려면:

프로젝트의 공유 모듈(shared module) build.gradle(.kts)에서 Kotlin 멀티플랫폼 플러그인과 함께 CocoaPods 플러그인을 적용하세요.
IDE 플러그인 또는 웹 위저드로 프로젝트를 생성했다면 이 단계는 건너뛰세요.
kotlin
```
plugins {
    kotlin("multiplatform") version "2.3.0"
    kotlin("native.cocoapods") version "2.3.0"
}
```

cocoapods 블록에서 Podspec 파일의 version, summary, homepage, baseName을 구성하세요:

kotlin

plugins {
    kotlin("multiplatform") version "2.3.0"
    kotlin("native.cocoapods") version "2.3.0"
}

kotlin {
    cocoapods {
        // 필수 속성
        // 여기에 필요한 Pod 버전을 지정하세요.
        // 지정하지 않으면 Gradle 프로젝트 버전이 사용됩니다.
        version = "1.0"
        summary = "Some description for a Kotlin/Native module"
        homepage = "Link to a Kotlin/Native module homepage"

        // 선택적 속성
        // Gradle 프로젝트 이름을 변경하는 대신 여기서 Pod 이름을 구성하세요.
        name = "MyCocoaPod"

        framework {
            // 필수 속성              
            // 프레임워크 이름 구성. 더 이상 사용되지 않는 'frameworkName' 대신 이 속성을 사용하세요.
            baseName = "MyFramework"
            
            // 선택적 속성
            // 프레임워크 연결 유형을 지정합니다. 기본값은 dynamic입니다. 
            isStatic = false
            // 의존성 내보내기(Export)
            // 다른 프로젝트 모듈이 있는 경우 주석을 해제하고 지정하세요:
            // export(project(":<your other KMP module>"))
            transitiveExport = false // 기본값입니다.
        }

        // 커스텀 Xcode 구성을 NativeBuildType에 매핑합니다.
        xcodeConfigurationToNativeBuildType["CUSTOM_DEBUG"] = NativeBuildType.DEBUG
        xcodeConfigurationToNativeBuildType["CUSTOM_RELEASE"] = NativeBuildType.RELEASE
    }
}

Kotlin DSL의 전체 구문은 Kotlin Gradle 플러그인 저장소에서 확인할 수 있습니다.

IntelliJ IDEA에서 Build | Reload All Gradle Projects(또는 Android Studio에서 File | Sync Project with Gradle Files)를 실행하여 프로젝트를 다시 가져오세요.
Xcode 빌드 중 호환성 문제를 방지하려면 Gradle 래퍼(wrapper)를 생성하세요.

플러그인을 적용하면 CocoaPods 플러그인은 다음을 수행합니다:

모든 macOS, iOS, tvOS, watchOS 타겟에 대해 debug 및 release 프레임워크를 출력 바이너리로 추가합니다.
프로젝트에 대한 Podspec 파일을 생성하는 podspec 태스크를 만듭니다.

Podspec 파일에는 출력 프레임워크에 대한 경로와 Xcode 프로젝트의 빌드 프로세스 중에 이 프레임워크를 자동으로 빌드하는 스크립트 단계가 포함됩니다.

Xcode를 위한 Podfile 업데이트

Kotlin 프로젝트를 Xcode 프로젝트로 가져오려는 경우:

Kotlin 프로젝트의 iOS 부분에서 Podfile을 다음과 같이 수정하세요:
- 프로젝트에 Git, HTTP 또는 커스텀 Podspec 저장소 의존성이 있는 경우 Podfile에 Podspec 경로를 지정하세요.
  예를 들어 podspecWithFilesExample에 대한 의존성을 추가하는 경우 Podfile에 해당 Podspec의 경로를 선언합니다:
  ruby
```
target 'ios-app' do
   # ... 기타 의존성 ...
   pod 'podspecWithFilesExample', :path => 'cocoapods/externalSources/url/podspecWithFilesExample' 
end
```
  :path에는 Pod의 파일 경로가 포함되어야 합니다.
- 커스텀 Podspec 저장소에서 라이브러리를 추가하는 경우 Podfile 시작 부분에 spec의 위치를 지정하세요:
  ruby
```
source 'https://github.com/Kotlin/kotlin-cocoapods-spec.git'

target 'kotlin-cocoapods-xcproj' do
    # ... 기타 의존성 ...
    pod 'example'
end
```
프로젝트 디렉터리에서 pod install을 실행하세요.
pod install을 처음 실행하면 .xcworkspace 파일이 생성됩니다. 이 파일에는 원래의 .xcodeproj와 CocoaPods 프로젝트가 포함됩니다.
기존 .xcodeproj를 닫고 대신 새로운 .xcworkspace 파일을 여세요. 이렇게 하면 프로젝트 의존성 문제를 피할 수 있습니다.
IntelliJ IDEA에서 Build | Reload All Gradle Projects(또는 Android Studio에서 File | Sync Project with Gradle Files)를 실행하여 프로젝트를 다시 가져오세요.

Podfile에서 이러한 변경을 수행하지 않으면 podInstall 태스크가 실패하고 CocoaPods 플러그인이 로그에 오류 메시지를 표시합니다.

발생 가능한 문제 및 해결 방법

CocoaPods 설치

Ruby 설치

CocoaPods는 Ruby로 구축되었으며, macOS에서 기본적으로 제공되는 Ruby로 설치할 수 있습니다. Ruby 1.9 이상에는 CocoaPods 의존성 관리자 설치를 도와주는 RubyGems 패키지 관리 프레임워크가 내장되어 있습니다.

CocoaPods를 설치하고 실행하는 데 문제가 있는 경우, 이 가이드를 따라 Ruby를 설치하거나 RubyGems 웹사이트를 참조하여 프레임워크를 설치하세요.

버전 호환성

최신 버전의 Kotlin을 사용하는 것이 좋습니다. 이 CocoaPods 설정을 위한 최소 요구 버전은 1.7.0입니다.

Xcode 사용 시 빌드 오류

CocoaPods 설치 방식에 따라 Xcode에서 빌드 오류가 발생할 수 있습니다. 일반적으로 Kotlin Gradle 플러그인은 PATH에서 pod 실행 파일을 찾아내지만, 이는 환경에 따라 일관되지 않을 수 있습니다.

CocoaPods 설치 경로를 명시적으로 설정하려면 프로젝트의 local.properties 파일에 수동으로 추가하거나 셸 명령을 사용하여 추가할 수 있습니다:

코드 에디터를 사용하는 경우 local.properties 파일에 다음 줄을 추가하세요:
text
```
kotlin.apple.cocoapods.bin=/Users/Jane.Doe/.rbenv/shims/pod
```

터미널을 사용하는 경우 다음 명령을 실행하세요:

shell

echo -e "kotlin.apple.cocoapods.bin=$(which pod)" >> local.properties

모듈 또는 프레임워크를 찾을 수 없음

Pod 설치 시 C interop 이슈와 관련된 module 'SomeSDK' not found 또는 framework 'SomeFramework' not found 오류가 발생할 수 있습니다. 이러한 오류를 해결하려면 다음 방법들을 시도해 보세요:

패키지 업데이트

설치 도구와 설치된 패키지(gems)를 업데이트하세요:

RVMRbenvHomebrew

RVM 업데이트:
bash
```
rvm get stable
```
Ruby 패키지 관리자인 RubyGems 업데이트:
bash
```
gem update --system
```
설치된 모든 gem을 최신 버전으로 업그레이드:
bash
```
gem update
```

Rbenv 업데이트:
bash
```
cd ~/.rbenv
git pull
```
Ruby 패키지 관리자인 RubyGems 업데이트:
bash
```
gem update --system
```
설치된 모든 gem을 최신 버전으로 업그레이드:
bash
```
gem update
```

Homebrew 패키지 관리자 업데이트:
bash
```
brew update
```
설치된 모든 패키지를 최신 버전으로 업그레이드:
bash
```
brew upgrade
```

프레임워크 이름 지정

다운로드된 Pod 디렉터리 [shared_module_name]/build/cocoapods/synthetic/IOS/Pods/...에서 module.modulemap 파일을 찾습니다.
모듈 내부의 프레임워크 이름(예: SDWebImageMapKit {})을 확인합니다. 프레임워크 이름이 Pod 이름과 일치하지 않으면 명시적으로 지정하세요:
kotlin
```
pod("SDWebImage/MapKit") {
    moduleName = "SDWebImageMapKit"
}
```

헤더 지정

pod("NearbyMessages")와 같이 Pod에 .modulemap 파일이 포함되어 있지 않은 경우, 메인 헤더를 명시적으로 지정하세요:

kotlin

pod("NearbyMessages") {
    version = "1.1.1"
    headers = "GNSMessages.h"
}

더 자세한 정보는 CocoaPods 문서를 확인하세요. 모든 방법을 시도해도 오류가 계속 발생하면 YouTrack에 이슈를 제보해 주세요.

앱 번들의 리소스 누락

iOS 앱이 성공적으로 빌드되지만 실행 시 크래시가 발생하거나, 커스텀 폰트 및 이미지와 같은 리소스가 최종 .ipa 패키지에서 누락된 경우 Pod이 프로젝트와 통합되는 방식에 문제가 있을 수 있습니다.

이 문제를 방지하려면: pod install 명령을 직접 실행하는 대신, Kotlin CocoaPods Gradle 플러그인에서 제공하는 Gradle podInstall 태스크를 사용하세요. 이 태스크는 필요한 디렉터리를 생성하고 모든 구성을 자동으로 수행합니다:

bash

./gradlew podInstall
open iosApp/iosApp.xcworkspace

문제 발생 원인: 클린 프로젝트(예: 저장소를 새로 클론한 후 또는 CI/CD 파이프라인에서 작업할 때)에서 네이티브 pod install 명령을 실행하면 리소스 디렉터리가 아직 생성되지 않은 상태일 수 있습니다. Compose Multiplatform Gradle 플러그인은 생성된 .podspec 파일에 리소스 위치를 다음과 같이 지정합니다: spec.resources = ['build/compose/cocoapods/compose-resources']. 하지만 이 경로는 빌드 후에만 존재합니다. 결과적으로 CocoaPods는 누락된 디렉터리를 무시하고 이러한 리소스 없이 Xcode 프로젝트를 구성합니다. 프로젝트가 빌드되고 리소스가 생성되어도 Xcode는 이를 최종 번들에 복사하지 않습니다.

Rsync 오류

rsync error: some files could not be transferred 오류가 발생할 수 있습니다. 이는 Xcode의 애플리케이션 타겟에서 사용자 스크립트의 샌드박싱(sandboxing)이 활성화되어 있을 때 발생하는 알려진 이슈입니다.

이 문제를 해결하려면:

애플리케이션 타겟에서 사용자 스크립트의 샌드박싱을 비활성화하세요:
샌드박싱되었을 수 있는 Gradle 데몬 프로세스를 중지합니다:
shell
```
./gradlew --stop
```

CocoaPods 개요 및 설정 ​

CocoaPods 작업을 위한 환경 설정 ​

프로젝트 생성 ​

프로젝트 구성 ​

Xcode를 위한 Podfile 업데이트 ​

발생 가능한 문제 및 해결 방법 ​

CocoaPods 설치 ​

Ruby 설치 ​

버전 호환성 ​

Xcode 사용 시 빌드 오류 ​

모듈 또는 프레임워크를 찾을 수 없음 ​

패키지 업데이트 ​

프레임워크 이름 지정 ​

헤더 지정 ​

앱 번들의 리소스 누락 ​

Rsync 오류 ​

다음 단계 ​

CocoaPods 개요 및 설정

CocoaPods 작업을 위한 환경 설정

프로젝트 생성

프로젝트 구성

Xcode를 위한 Podfile 업데이트

발생 가능한 문제 및 해결 방법

CocoaPods 설치

Ruby 설치

버전 호환성

Xcode 사용 시 빌드 오류

모듈 또는 프레임워크를 찾을 수 없음

패키지 업데이트

프레임워크 이름 지정

헤더 지정

앱 번들의 리소스 누락

Rsync 오류

다음 단계