CocoaPods 概述与设置

设置 CocoaPods 环境

使用你选择的安装工具, 安装 CocoaPods 依赖项管理器:

sudo gem install cocoapods

如果你在安装过程中遇到问题, 请参见 可能发生的问题与解决方案 小节.

创建项目

环境设置完成后, 你可以创建新的 Kotlin Multiplatform 项目. 要创建项目, 可以使用 Kotlin Multiplatform Web 向导, 或使用 Android Studio 中的 Kotlin Multiplatform plugin.

配置已有的项目

如果你已经有了项目, 你可以手动添加并配置 Kotlin CocoaPods Gradle plugin:

1. 在你的项目的 build.gradle(.kts) 文件中, 应用 CocoaPods 插件和 Kotlin Multiplatform 插件:

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

2. 在 cocoapods 代码段中, 配置 Podspec 文件的 version, summary, homepage, 和 baseName.

   plugins {
       kotlin("multiplatform") version "2.1.0"
       kotlin("native.cocoapods") version "2.1.0"
   }
   
   kotlin {
       cocoapods {
           // 必须属性
           // 在这里指定需要的 Pod 版本. 否则, 会使用 Gradle 项目的版本.
           version = "1.0"
           summary = "Some description for a Kotlin/Native module"
           homepage = "Link to a Kotlin/Native module homepage"
   
           // 可选属性
           // 在这里配置 Pod 名称, 而不是修改 Gradle 项目名称
           name = "MyCocoaPod"
   
           framework {
               // 必须属性
               // 配置框架名称. 'frameworkName' 属性已废弃, 请改为使用这个属性
               baseName = "MyFramework"
   
               // 可选属性
               // 指定框架的链接类型. 默认为 dynamic.
               isStatic = false
               // 导出依赖项
               // 对下面这行取消注释, 并指定另一个项目模块(如果有):
               // export(project(":<你的其它 KMP 模块>"))
               transitiveExport = false // 这是默认值.
           }
   
           // 将自定义的 Xcode 配置对应到 NativeBuildType
           xcodeConfigurationToNativeBuildType["CUSTOM_DEBUG"] = NativeBuildType.DEBUG
           xcodeConfigurationToNativeBuildType["CUSTOM_RELEASE"] = NativeBuildType.RELEASE
       }
   }

   note

   Kotlin DSL 的完整语法请参见 Kotlin Gradle plugin 代码仓库.

3. 在 IntelliJ IDEA 中, 运行 Reload All Gradle Projects (如果是 Android Studio, 请运行 Sync Project with Gradle Files), 重新导入项目.

4. 生成 Gradle wrapper, 以免在 Xcode 构建时发生兼容性问题.

应用 CocoaPods 插件后, 它会完成如下工作:

• 对所有的 macOS, iOS, tvOS, 和 watchOS 编译目标, 将 debug 和 release 框架添加为输出的二进制文件.

• 创建 podspec 任务, 它会为项目生成一个 Podspec 文件.

Podspec 文件包含输出框架的路径, 以及一段脚本, 负责在 Xcode 项目的构建过程中, 自动构建这个框架.

为 Xcode 更新 Podfile 文件

如果要将你的 Kotlin 项目导入到一个 Xcode 项目中, 请执行以下步骤:

1. 修改你的 Podfile 文件:

   • 如果你的项目存在任何 Git, HTTP, 或 自定义 Podspec 仓库的依赖项, 那么还需要在 Podfile 中指定 Podspec 的路径.

     例如, 如果添加了 podspecWithFilesExample 的依赖, 需要在 Podfile 文件中声明 Podspec 路径:

     target 'ios-app' do
         # ... 其他依赖项 ...
         pod 'podspecWithFilesExample', :path => 'cocoapods/externalSources/url/podspecWithFilesExample'
     end

     :path 应该包含 Pod 的文件路径.

   • 如果添加一个来自自定义 Podspec 仓库的库, 那么还需要在 Podfile 文件的最开始指定 spec 的位置:

     source 'https://github.com/Kotlin/kotlin-cocoapods-spec.git'
     
     target 'kotlin-cocoapods-xcproj' do
         # ... 其他依赖项 ...
         pod 'example'
     end

2. 在你的项目目录中运行 pod install.

   当你第一次运行 pod install 时, 它会创建 .xcworkspace 文件. 这个文件包含你原来的 .xcodeproj 和 CocoaPods 项目.

3. 关闭你的 .xcodeproj, 改为打开新的 .xcworkspace 文件. 这样可以避免项目依赖项的问题.

4. 在 IntelliJ IDEA 中, 运行 Reload All Gradle Projects (如果是 Android Studio, 请运行 Sync Project with Gradle Files), 重新导入项目.

如果不在 Podfile 文件中进行这些修改, podInstall 任务将会失败, CocoaPods plugin 会在 log 中显示错误消息.

可能发生的问题与解决方案

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