CocoaPods 개요 및 설정

이것은 로컬 통합 방식입니다. 다음 경우에 유용합니다:

CocoaPods를 사용하는 iOS 프로젝트와 함께 모노 리포지토리(mono repository)를 설정한 경우.
Kotlin Multiplatform 프로젝트에 CocoaPods 종속성이 있는 경우.

Kotlin/Native는 CocoaPods 종속성 관리자와의 통합을 제공합니다. Pod 라이브러리에 종속성을 추가하거나 Kotlin 프로젝트를 CocoaPods 종속성으로 사용할 수 있습니다.

IntelliJ IDEA 또는 Android Studio에서 직접 Pod 종속성을 관리하고 코드 하이라이팅 및 자동 완성 등 모든 추가 기능을 활용할 수 있습니다. Xcode로 전환할 필요 없이 Gradle을 사용하여 전체 Kotlin 프로젝트를 빌드할 수 있습니다.

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

CocoaPods 작업을 위한 환경 설정

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

RVMRbenvDefault RubyHomebrew

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

CocoaPods를 설치합니다:

bash

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

아직 rbenv가 없다면 GitHub에서 rbenv를 설치하세요.
Ruby를 설치합니다. 특정 버전을 선택할 수 있습니다:
bash
```
rbenv install 3.0.0
```
특정 디렉토리에는 로컬 Ruby 버전을, 전체 머신에는 전역 Ruby 버전을 설정합니다:
bash
```
rbenv global 3.0.0
```

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가 없다면 Homebrew를 설치하세요.
CocoaPods를 설치합니다:
bash
```
brew install cocoapods
```

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

프로젝트 생성

환경 설정이 완료되면 새로운 Kotlin Multiplatform 프로젝트를 생성할 수 있습니다. 이를 위해 Kotlin Multiplatform 웹 위자드(web wizard) 또는 Android Studio용 Kotlin Multiplatform 플러그인을 사용하세요.

웹 위자드 사용

웹 위자드를 사용하여 프로젝트를 생성하고 CocoaPods 통합을 구성하려면:

Kotlin Multiplatform 위자드를 열고 프로젝트의 대상 플랫폼을 선택합니다.
Download 버튼을 클릭하고 다운로드된 아카이브의 압축을 해제합니다.
Android Studio에서 메뉴에서 File | Open을 선택합니다.
압축 해제된 프로젝트 폴더로 이동한 다음 Open을 클릭합니다.
Kotlin CocoaPods Gradle 플러그인을 버전 카탈로그(version catalog)에 추가합니다. gradle/libs.versions.toml 파일의 [plugins] 블록에 다음 선언을 추가합니다:
text
```
kotlinCocoapods = { id = "org.jetbrains.kotlin.native.cocoapods", version.ref = "kotlin" }
```
프로젝트의 루트 build.gradle.kts 파일로 이동하여 plugins {} 블록에 다음 alias를 추가합니다:
kotlin
```
alias(libs.plugins.kotlinCocoapods) apply false
```
CocoaPods를 통합하려는 모듈(예: composeApp 모듈)을 열고 plugins {} 블록에 다음 alias를 추가합니다:
kotlin
```
alias(libs.plugins.kotlinCocoapods)
```

이제 Kotlin Multiplatform 프로젝트에서 CocoaPods를 구성할 준비가 되었습니다.

Android Studio에서

Android Studio에서 CocoaPods 통합과 함께 프로젝트를 생성하려면:

Android Studio에 Kotlin Multiplatform 플러그인을 설치합니다.
Android Studio 메뉴에서 File | New | New Project를 선택합니다.
프로젝트 템플릿 목록에서 Kotlin Multiplatform App을 선택한 다음 Next를 클릭합니다.
애플리케이션 이름을 지정하고 Next를 클릭합니다.
iOS 프레임워크 배포 옵션으로 CocoaPods Dependency Manager를 선택합니다.
다른 모든 옵션은 기본값으로 유지합니다. Finish를 클릭합니다.
플러그인이 CocoaPods 통합이 설정된 프로젝트를 자동으로 생성합니다.

프로젝트 구성

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

프로젝트의 공유 모듈(shared module) build.gradle(.kts)에 Kotlin Multiplatform 플러그인뿐만 아니라 CocoaPods 플러그인도 적용합니다.
이 단계는 웹 위자드 또는 Android Studio용 Kotlin Multiplatform 플러그인으로 프로젝트를 생성했다면 건너뛰세요.
kotlin
```
plugins {
    kotlin("multiplatform") version "2.2.0"
    kotlin("native.cocoapods") version "2.2.0"
}
```

cocoapods 블록에서 Podspec 파일의 version, summary, homepage, baseName을 구성합니다:

kotlin

plugins {
    kotlin("multiplatform") version "2.2.0"
    kotlin("native.cocoapods") version "2.2.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"
            
            // 선택적 속성
            // 프레임워크 연결 유형을 지정합니다. 기본적으로 동적입니다. 
            isStatic = false
            // 종속성 내보내기
            // 주석을 해제하고 다른 프로젝트 모듈이 있다면 지정합니다:
            // export(project(":<your other KMP module>"))
            transitiveExport = false // This is default.
        }

        // 사용자 지정 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)를 실행하여 프로젝트를 다시 임포트(re-import)합니다.
Xcode 빌드 중 호환성 문제를 방지하려면 Gradle wrapper를 생성합니다.

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

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

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

Xcode용 Podfile 업데이트

Kotlin 프로젝트를 Xcode 프로젝트로 임포트(import)하려면:

Kotlin 프로젝트의 iOS 부분에서 Podfile을 변경합니다:
- 프로젝트에 Git, HTTP 또는 사용자 지정 Podspec 저장소 종속성이 있는 경우, Podfile에 Podspec 경로를 지정합니다.
  예를 들어, podspecWithFilesExample에 종속성을 추가하는 경우, Podfile에 Podspec 경로를 선언합니다:
  ruby
```
target 'ios-app' do
   # ... other dependencies ...
   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
    # ... other dependencies ...
    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)를 실행하여 프로젝트를 다시 임포트(re-import)합니다.

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

가능한 문제 및 해결 방법

CocoaPods 설치

Ruby 설치

CocoaPods는 Ruby로 빌드되었으며, macOS에 기본으로 제공되는 Ruby를 사용하여 설치할 수 있습니다. Ruby 1.9 이상 버전에는 CocoaPods 종속성 관리자 설치를 돕는 RubyGems 패키지 관리 프레임워크가 내장되어 있습니다.

CocoaPods 설치 및 작동에 문제가 발생하면 이 가이드를 따라 Ruby를 설치하거나 RubyGems 웹사이트를 참조하여 프레임워크를 설치하세요.

버전 호환성

최신 Kotlin 버전을 사용하는 것을 권장합니다. 현재 버전이 1.7.0보다 이전이라면 cocoapods-generate 플러그인을 추가로 설치해야 합니다.

그러나 cocoapods-generate는 Ruby 3.0.0 이상 버전과 호환되지 않습니다. 이 경우 Ruby 버전을 낮추거나 Kotlin을 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 오류가 발생할 수 있습니다. 이러한 오류를 해결하려면 다음 해결 방법을 시도해 보세요:

패키지 업데이트

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

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에 .modulemap 파일이 포함되어 있지 않은 경우(pod("NearbyMessages")와 같이), 메인 헤더를 명시적으로 지정합니다:

kotlin

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

더 자세한 정보는 CocoaPods 문서를 확인하세요. 아무것도 작동하지 않고 이 오류가 계속 발생하면 YouTrack에 문제를 보고하세요.

Rsync 오류

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

이 문제를 해결하려면:

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

CocoaPods 개요 및 설정 ​

CocoaPods 작업을 위한 환경 설정 ​

프로젝트 생성 ​

웹 위자드 사용 ​

Android Studio에서 ​

프로젝트 구성 ​

Xcode용 Podfile 업데이트 ​

가능한 문제 및 해결 방법 ​

CocoaPods 설치 ​

Ruby 설치 ​

버전 호환성 ​

Xcode 사용 시 빌드 오류 ​

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

패키지 업데이트 ​

프레임워크 이름 지정 ​

헤더 지정 ​

Rsync 오류 ​

다음 단계 ​

CocoaPods 개요 및 설정

CocoaPods 작업을 위한 환경 설정

프로젝트 생성

웹 위자드 사용

Android Studio에서

프로젝트 구성

Xcode용 Podfile 업데이트

가능한 문제 및 해결 방법

CocoaPods 설치

Ruby 설치

버전 호환성

Xcode 사용 시 빌드 오류

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

패키지 업데이트

프레임워크 이름 지정

헤더 지정

Rsync 오류

다음 단계