设置多平台库发布

您可以将多平台库发布到不同位置：

• 到本地 Maven 版本库
• 到 Maven Central 版本库。了解如何在我们的教程中设置账户凭据、自定义库元数据以及配置发布插件。
• 到 GitHub 版本库。有关更多信息，请参阅 GitHub 关于 GitHub packages 的文档。

发布到本地 Maven 版本库

您可以使用 maven-publish Gradle 插件将多平台库发布到本地 Maven 版本库：

1. 在 shared/build.gradle.kts 文件中，添加 maven-publish Gradle 插件。

2. 指定库的 group 和 version，以及应发布到的版本库：

   plugins {
       // ...
       id("maven-publish")
   }
   
   group = "com.example"
   version = "1.0"
   
   publishing {
       repositories {
           maven {
               //...
           }
       }
   }

与 maven-publish 结合使用时，Kotlin 插件会自动为可在当前主机上构建的每个目标创建发布项，但 Android 目标除外，它需要一个额外步骤来配置发布。

发布项的结构

Kotlin Multiplatform 库的发布项包含多个 Maven 发布项，每个都对应一个特定目标。此外，一个伞形 root 发布项 kotlinMultiplatform（代表整个库）也会被发布。

当作为依赖项添加到公共源代码集时，根发布项会自动解析为相应的平台特有构件。

目标特有与根发布项

Kotlin Multiplatform Gradle 插件为每个目标配置独立的发布项。考虑以下项目配置：

// projectName = "lib"
group = "test"
version = "1.0"

kotlin {
    jvm()
    iosX64()
    iosArm64()
}

此设置会生成以下 Maven 发布项：

目标特有的发布项

• 对于 jvm 目标：test:lib-jvm:1.0
• 对于 iosX64 目标：test:lib-iosx64:1.0
• 对于 iosArm64 目标：test:lib-iosarm64:1.0

每个目标特有的发布项都是独立的。例如，运行 publishJvmPublicationTo<MavenRepositoryName> 只发布 JVM 模块，使其他模块保持未发布状态。

根发布项

kotlinMultiplatform 根发布项：test:lib:1.0。

根发布项作为入口点，引用所有目标特有的发布项。它包含元数据构件，并通过包含对其他发布项的引用（即各个平台构件的预期 URL 和坐标）来确保正确的依赖项解析。

• 一些版本库，例如 Maven Central，要求根模块包含不带分类器的 JAR 构件，例如 kotlinMultiplatform-1.0.jar。Kotlin Multiplatform 插件会自动生成所需的构件，其中包含嵌入式元数据构件。这意味着您无需在库的根模块中添加一个空构件来满足版本库的要求。

  详细了解如何使用 Gradle 和 Maven 构建系统生成 JAR 构件。

• 如果版本库需要，kotlinMultiplatform 发布项也可能需要源代码和文档构件。在这种情况下，请在发布项的作用域中使用 artifact()。

发布完整库

要一步发布所有必需的构件，请使用 publishAllPublicationsTo<MavenRepositoryName> 伞形任务。例如：

./gradlew publishAllPublicationsToGithubPackagesRepository

发布到 Maven Local 时，您可以使用特殊任务：

./gradlew publishToMavenLocal

这些任务确保所有目标特有和根发布项一起发布，使库完全可用于依赖项解析。

或者，您可以使用独立的发布任务。首先运行根发布项：

./gradlew publishKotlinMultiplatformPublicationToMavenLocal

此任务发布一个 *.module 文件，其中包含关于目标特有发布项的信息，但目标本身仍未发布。要完成此过程，请单独发布每个目标特有的发布项：

./gradlew publish<TargetName>PublicationToMavenLocal

这保证所有构件都可用并被正确引用。

主机要求

Kotlin/Native 支持交叉编译，允许任何主机生成必要的 .klib 构件。但是，您仍需注意一些局限性。

针对 Apple 目标的编译

您可以使用任何主机为带有 Apple 目标的项目生成构件。但是，如果您仍需使用 Mac 机器，则需要满足以下条件：

• 您的库或依赖模块具有 cinterop 依赖项。
• 您的项目中设置了 CocoaPods 集成。
• 您需要为 Apple 目标构建或测试最终二进制文件。

重复发布项

为避免版本库中出现任何重复发布项，请从单个主机发布所有构件。例如，Maven Central 明确禁止重复发布项，如果创建了重复项，则会导致进程失败。

发布 Android 库

要发布 Android 库，您需要提供额外配置。默认情况下，不发布 Android 库的任何构件。

本节假设您正在使用 Android Gradle 库插件。 有关如何设置插件或从旧版 com.android.library 插件迁移的指南，请参阅 Android 文档中的设置 Android Gradle 库插件页面。

要发布构件，请将 androidLibrary {} 代码块添加到 shared/build.gradle.kts 文件中，并使用 KMP DSL 配置发布。例如：

kotlin {
    androidLibrary {
        namespace = "org.example.library"
        compileSdk = libs.versions.android.compileSdk.get().toInt()
        minSdk = libs.versions.android.minSdk.get().toInt()

        // 启用 Java 编译支持。
        // 这在不需要 Java 编译时可以缩短构建时间
        withJava()

        compilations.configureEach {
            compilerOptions.configure {
                jvmTarget.set(
                    JvmTarget.JVM_11
                )
            }
        }
    }
}

请注意，Android Gradle 库插件不支持产品风味和构建变体，从而简化了配置。因此，您需要选择启用以创建测试源代码集和配置。例如：

kotlin {
    androidLibrary {
        // ...

        // 选择启用并配置主机端（单元）测试
        withHostTestBuilder {}.configure {}

        // 选择启用设备测试，指定源代码集名称
        withDeviceTestBuilder {
            sourceSetTreeName = "test"
        }

        // ...
    }
}

以前，例如，使用 GitHub action 运行测试需要单独指定 debug 和 release 变体：

- target: testDebugUnitTest
  os: ubuntu-latest
- target: testReleaseUnitTest
  os: ubuntu-latest

使用 Android Gradle 库插件，您只需指定带源代码集名称的通用目标：

- target: testAndroidHostTest
  os: ubuntu-latest

禁用源代码发布

默认情况下，Kotlin Multiplatform Gradle 插件会为所有指定目标发布源代码。但是，您可以在 shared/build.gradle.kts 文件中使用 withSourcesJar() API 配置并禁用源代码发布：

• 要为所有目标禁用源代码发布：

  kotlin {
      withSourcesJar(publish = false)
  
      jvm()
      linuxX64()
  }

• 要仅为指定目标禁用源代码发布：

  kotlin {
       // 仅为 JVM 禁用源代码发布：
      jvm {
          withSourcesJar(publish = false)
      }
      linuxX64()
  }

• 要为除指定目标外的所有目标禁用源代码发布：

  kotlin {
      // 为除 JVM 外的所有目标禁用源代码发布：
      withSourcesJar(publish = false)
  
      jvm {
          withSourcesJar(publish = true)
      }
      linuxX64()
  }

禁用 JVM 环境属性发布

从 Kotlin 2.0.0 开始，Gradle 属性 org.gradle.jvm.environment 会随所有 Kotlin 变体自动发布，以帮助区分 Kotlin Multiplatform 库的 JVM 和 Android 变体。此属性指示哪个库变体适用于哪个 JVM 环境，Gradle 会使用此信息帮助您项目中的依赖项解析。目标环境可以是 "android"、"standard-jvm" 或 "no-jvm"。

您可以通过将以下 Gradle 属性添加到您的 gradle.properties 文件来禁用此属性的发布：

kotlin.publishJvmEnvironmentAttribute=false

推广您的库

您的库可以在 JetBrains 的多平台库目录上展示。它旨在方便根据目标平台查找 Kotlin Multiplatform 库。

符合标准的库会自动添加。有关如何确保您的库在目录中展示的更多信息，请参阅常见问题。

下一步

• 了解如何将您的 Kotlin Multiplatform 库发布到 Maven Central 版本库
• 参阅库作者指南，了解为 Kotlin Multiplatform 设计库的最佳实践和技巧