Thiết lập trình bổ trợ thư viện Android Gradle cho KMP

Trình bổ trợ Gradle com.android.kotlin.multiplatform.library là công cụ được hỗ trợ chính thức để thêm mục tiêu Android vào mô-đun thư viện Kotlin Multiplatform (KMP). Trình bổ trợ này giúp đơn giản hoá cấu hình dự án, cải thiện hiệu suất bản dựng và tích hợp tốt hơn với Android Studio.

Việc sử dụng trình bổ trợ com.android.library để phát triển KMP phụ thuộc vào các API của Trình bổ trợ Android cho Gradle đã ngừng hoạt động và yêu cầu chọn sử dụng trong Trình bổ trợ Android cho Gradle 9.0 trở lên (quý 4 năm 2025). Các API này dự kiến sẽ bị xoá trong trình bổ trợ Android cho Gradle 10.0 (nửa cuối năm 2026).

Để áp dụng trình bổ trợ này, hãy tham khảo phần Áp dụng trình bổ trợ Android-KMP. Nếu bạn cần di chuyển khỏi các API cũ, hãy xem Hướng dẫn di chuyển.

Để được trợ giúp về việc di chuyển AGP 9.0 trở lên, bạn có thể sử dụng kỹ năng của tác nhân do JetBrains tạo cho các ứng dụng KMP. Để biết thêm thông tin về cách sử dụng kỹ năng trong Android Studio, hãy xem bài viết Mở rộng Chế độ tác nhân bằng kỹ năng. Xin lưu ý rằng kết quả của AI không hoàn toàn có thể dự đoán được.

Các tính năng chính và điểm khác biệt

Trình bổ trợ Android-KMP được thiết kế riêng cho các dự án KMP và khác với trình bổ trợ com.android.library tiêu chuẩn ở một số khía cạnh chính:

  • Kiến trúc biến thể đơn: Trình bổ trợ này sử dụng một biến thể duy nhất, loại bỏ tính năng hỗ trợ cho các phiên bản sản phẩm và loại bản dựng, giúp đơn giản hoá cấu hình và nâng cao hiệu suất bản dựng.

  • Tối ưu hoá cho KMP: Trình bổ trợ này được thiết kế cho các thư viện KMP, tập trung vào mã Kotlin dùng chung và khả năng tương tác, bỏ qua tính năng hỗ trợ cho các bản dựng gốc dành riêng cho Android, AIDL và RenderScript.

  • Kiểm thử bị tắt theo mặc định: Cả kiểm thử đơn vị và kiểm thử thiết bị (đo lường) đều bị tắt theo mặc định để tăng tốc độ bản dựng. Bạn có thể bật các tính năng này nếu cần.

  • Không có tiện ích Android cấp cao nhất: Cấu hình được xử lý bằng một khối android trong DSL KMP của Gradle, duy trì cấu trúc dự án KMP nhất quán. Không có khối tiện ích android cấp cao nhất.

  • Chọn tham gia biên dịch Java: Tính năng biên dịch Java bị tắt theo mặc định. Hãy sử dụng withJava() trong khối android để bật tính năng hỗ trợ này. Điều này giúp cải thiện thời gian tạo bản dựng khi không cần biên dịch Java.

Lợi ích của trình bổ trợ thư viện Android-KMP

Trình bổ trợ Android-KMP mang lại những lợi ích sau cho các dự án KMP:

  • Cải thiện hiệu suất và độ ổn định của bản dựng: Công cụ này được thiết kế để tối ưu hoá tốc độ bản dựng và tăng cường độ ổn định trong các dự án KMP. Việc tập trung vào quy trình làm việc KMP góp phần tạo nên một quy trình xây dựng hiệu quả và đáng tin cậy hơn.

  • Tích hợp IDE nâng cao: Cung cấp khả năng hoàn thành mã, điều hướng, gỡ lỗi và trải nghiệm tổng thể tốt hơn cho nhà phát triển khi làm việc với các thư viện Android KMP.

  • Cấu hình dự án đơn giản: Trình bổ trợ này đơn giản hoá cấu hình cho các dự án KMP bằng cách loại bỏ những yếu tố phức tạp dành riêng cho Android, chẳng hạn như biến thể bản dựng. Điều này giúp các tệp bản dựng gọn gàng và dễ bảo trì hơn. Trước đây, việc sử dụng trình bổ trợ com.android.library trong dự án KMP có thể tạo ra tên nhóm tài nguyên gây nhầm lẫn, chẳng hạn như androidAndroidTest. Quy ước đặt tên này ít trực quan hơn đối với các nhà phát triển đã quen thuộc với cấu trúc dự án KMP tiêu chuẩn.

Cách giải quyết cho các tính năng không được hỗ trợ

Khi so sánh với việc tích hợp KMP với trình bổ trợ com.android.library, một số tính năng bị thiếu trong trình bổ trợ com.android.kotlin.multiplatform.library. Sau đây là các giải pháp tạm thời cho những tính năng không được hỗ trợ:

  • Các biến thể bản dựng

    Loại bản dựng và phiên bản sản phẩm không được hỗ trợ. Điều này là do trình bổ trợ mới sử dụng cấu trúc biến thể đơn, giúp đơn giản hoá cấu hình và cải thiện hiệu suất bản dựng.

    Nếu bạn cần các biến thể bản dựng, bạn nên tạo một mô-đun thư viện Android độc lập riêng biệt bằng cách sử dụng trình bổ trợ com.android.library, định cấu hình các loại bản dựng và phiên bản sản phẩm trong mô-đun đó, sau đó sử dụng mô-đun đó làm phần phụ thuộc dự án tiêu chuẩn từ nhóm tài nguyên androidMain của thư viện Kotlin Multiplatform. Để biết thêm thông tin, hãy xem bài viết Tạo thư viện Android và Định cấu hình biến thể bản dựng.

  • Liên kết dữ liệu và Liên kết khung hiển thị

    Đây là các tính năng khung giao diện người dùng dành riêng cho Android, được liên kết chặt chẽ với hệ thống Khung hiển thị Android và bố cục XML. Với trình bổ trợ thư viện Android-KMP mới, bạn nên xử lý giao diện người dùng bằng một khung đa nền tảng như Compose Multiplatform. Liên kết dữ liệu và Liên kết khung hiển thị được coi là thông tin triển khai của một ứng dụng Android hoàn chỉnh, chứ không phải là một thư viện có thể chia sẻ.

  • Hỗ trợ bản dựng gốc

    Trình bổ trợ mới tập trung vào việc tạo một AAR chuẩn cho mục tiêu Android. Tính năng tích hợp mã gốc trong Kotlin Multiplatform được xử lý trực tiếp bằng các mục tiêu gốc của KMP (chẳng hạn như androidNativeArm64 và androidNativeX86) và khả năng tương tác C của KMP. Nếu cần đưa mã C/C++ gốc vào, bạn nên xác định mã đó là một phần của nhóm tài nguyên gốc hoặc chung và định cấu hình khả năng tương tác C trong khối kotlin, thay vì sử dụng cơ chế externalNativeBuild dành riêng cho Android.

    Ngoài ra, nếu cần hỗ trợ bản dựng gốc thông qua externalNativeBuild, bạn nên tạo một mô-đun com.android.library độc lập riêng biệt, nơi bạn có thể tích hợp mã gốc và sử dụng thư viện độc lập đó từ nhóm tài nguyên androidMain của dự án thư viện Kotlin Multiplatform. Để biết thêm thông tin, hãy xem bài viết Tạo thư viện Android và Thêm mã C và C++ vào dự án của bạn.

  • Lớp BuildConfig

    Tính năng BuildConfig hữu ích nhất trong môi trường có nhiều biến thể. Vì trình bổ trợ thư viện Kotlin Multiplatform mới không phụ thuộc vào biến thể và không hỗ trợ các loại bản dựng cũng như phiên bản sản phẩm, nên tính năng này không được triển khai. Thay vào đó, bạn nên sử dụng trình bổ trợ BuildKonfig hoặc các giải pháp tương tự của cộng đồng để tạo siêu dữ liệu cho tất cả mục tiêu.

Điều kiện tiên quyết

Để sử dụng trình bổ trợ com.android.kotlin.multiplatform.library, bạn phải định cấu hình dự án bằng các phiên bản tối thiểu sau đây trở lên:

  • Trình bổ trợ Android cho Gradle (AGP): 8.10.0
  • Trình bổ trợ Kotlin cho Gradle (KGP): 2.0.0

Áp dụng trình bổ trợ Android-KMP cho một mô-đun hiện có

Để áp dụng trình bổ trợ Android-KMP cho một mô-đun thư viện KMP hiện có, hãy làm theo các bước sau:

  1. Khai báo trình bổ trợ trong danh mục phiên bản. Mở tệp TOML của danh mục phiên bản (thường là gradle/libs.versions.toml) rồi thêm phần định nghĩa trình bổ trợ:

    # To check the version number of the latest Kotlin release, go to
# https://kotlinlang.org/docs/releases.html

[versions]
androidGradlePlugin = "9.4.0"
kotlin = "KOTLIN_VERSION"

[plugins]
kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
android-kotlin-multiplatform-library = { id = "com.android.kotlin.multiplatform.library", version.ref = "androidGradlePlugin" }

  2. Áp dụng nội dung khai báo trình bổ trợ trong tệp bản dựng gốc. Mở tệp build.gradle.kts nằm trong thư mục gốc của dự án. Thêm bí danh trình bổ trợ vào khối plugins bằng apply false. Thao tác này giúp tất cả các dự án phụ đều có thể sử dụng bí danh của trình bổ trợ mà không cần áp dụng logic của trình bổ trợ cho chính dự án gốc.

    Kotlin

    // Root build.gradle.kts file

plugins {
   alias(libs.plugins.kotlin.multiplatform) apply false

   // Add the following
   alias(libs.plugins.android.kotlin.multiplatform.library) apply false
}

    Groovy

    // Root build.gradle file

plugins {
   alias(libs.plugins.kotlin.multiplatform) apply false

   // Add the following
   alias(libs.plugins.android.kotlin.multiplatform.library) apply false
}

  3. Áp dụng trình bổ trợ trong tệp bản dựng mô-đun thư viện KMP. Mở tệp build.gradle.kts trong mô-đun thư viện KMP và áp dụng trình bổ trợ ở đầu tệp trong khối plugins:

    Kotlin

    // Module-specific build.gradle.kts file

plugins {
   alias(libs.plugins.kotlin.multiplatform)

   // Add the following
   alias(libs.plugins.android.kotlin.multiplatform.library)
}

    Groovy

    // Module-specific build.gradle file

plugins {
   alias(libs.plugins.kotlin.multiplatform)

   // Add the following
   alias(libs.plugins.android.kotlin.multiplatform.library)
}

  4. Định cấu hình mục tiêu KMP cho Android. Định cấu hình khối Kotlin Multiplatform (kotlin) để xác định mục tiêu Android. Trong khối kotlin, hãy chỉ định mục tiêu Android bằng android:

    Kotlin

    kotlin {
   android {
       namespace = "com.example.kmpfirstlib"
       compileSdk = 33
       minSdk = 24

       withJava() // enable java compilation support
       withHostTestBuilder {}.configure {}
       withDeviceTestBuilder {
           sourceSetTreeName = "test"
       }

       compilerOptions.configure {
           jvmTarget.set(
               org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8
           )
       }
   }

   sourceSets {
       androidMain {
           dependencies {
               // Add Android-specific dependencies here
           }
       }
       getByName("androidHostTest") {
           dependencies {
           }
       }

       getByName("androidDeviceTest") {
           dependencies {
           }
       }
   }
   // ... other targets (JVM, iOS, etc.) ...
}

    Groovy

    kotlin {
   android {
       namespace = "com.example.kmpfirstlib"
       compileSdk = 33
       minSdk = 24

       withJava() // enable java compilation support
       withHostTestBuilder {}.configure {}
       withDeviceTestBuilder {
           it.sourceSetTreeName = "test"
       }

       compilerOptions.options.jvmTarget.set(
           org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8
       )
   }

   sourceSets {
       androidMain {
           dependencies {
           }
       }
       androidHostTest {
           dependencies {
           }
       }
       androidDeviceTest {
           dependencies {
           }
       }
   }
   // ... other targets (JVM, iOS, etc.) ...
}

  5. Áp dụng các thay đổi. Sau khi áp dụng trình bổ trợ và định cấu hình khối kotlin, hãy đồng bộ hoá dự án Gradle để áp dụng các thay đổi.

Di chuyển từ trình bổ trợ cũ

Hướng dẫn này giúp bạn di chuyển từ trình bổ trợ com.android.library cũ sang trình bổ trợ com.android.kotlin.multiplatform.library.

1. Di chuyển nguồn

Trình bổ trợ cũ cho phép bạn sử dụng các nhóm tài nguyên src/main, src/test và src/androidTest, ngoài src/androidMain, src/androidHostTest và src/androidDeviceTest. Trình bổ trợ mới chỉ sử dụng các thư mục nguồn sau, vì vậy, bạn cần di chuyển các nguồn từ src/main sang src/androidMain, từ src/test sang src/androidHostTest và từ src/androidTest sang src/androidDeviceTest.

2. Định cấu hình thư mục tài nguyên và nguồn tuỳ chỉnh

Nếu có nguồn hoặc tài nguyên trong các thư mục không chuẩn, thì trước đây bạn đã định cấu hình các nguồn hoặc tài nguyên đó bằng khối sourceSets. Với trình bổ trợ mới, hãy sử dụng tiện ích androidComponents để thêm thư mục nguồn tĩnh vào biến thể.

Xin lưu ý rằng với trình bổ trợ mới, phương thức addStaticSourceDirectory sẽ thêm thư mục vào danh sách thư mục nguồn hiện có. Với trình bổ trợ cũ, phương thức setSrcDirs thay thế danh sách, còn phương thức srcDir thêm vào danh sách.

Android-KMP

Với trình bổ trợ mới, hãy sử dụng khối onVariants để tương tác với các nguồn của biến thể.

// build.gradle.kts

androidComponents {
    onVariants { variant ->
        // Add a directory for Kotlin sources
        variant.sources.kotlin?.addStaticSourceDirectory("other/kotlin")

        // Add a directory for Android assets
        variant.sources.assets?.addStaticSourceDirectory("other/assets")
    }
}

Trình bổ trợ cũ

Với trình bổ trợ com.android.library, khối sourceSets được dùng để đặt hoặc thêm thư mục nguồn.

// build.gradle.kts

android {
    sourceSets {
        getByName("main") {
            // Replaces the directory for Kotlin sources.
            kotlin.setSrcDirs(listOf("other/kotlin"))

            // Appends a directory for assets.
            assets.srcDir("other/assets")
        }
    }
}

3. Khai báo phần phụ thuộc

Một nhiệm vụ phổ biến là khai báo các phần phụ thuộc cho nhóm tài nguyên dành riêng cho Android. Trình bổ trợ mới yêu cầu các phần phụ thuộc này phải được đặt rõ ràng trong khối sourceSets, không giống như khối dependencies chung được sử dụng trước đây.

Android-KMP

Trình bổ trợ mới giúp cấu trúc rõ ràng hơn bằng cách nhóm các phần phụ thuộc Android trong nhóm tài nguyên androidMain. Ngoài nhóm tài nguyên chính, còn có hai nhóm tài nguyên kiểm thử được tạo theo yêu cầu: androidDeviceTest và androidHostTest (xem phần định cấu hình máy chủ lưu trữ và kiểm thử thiết bị để biết thêm thông tin).

// build.gradle.kts

kotlin {
    android {}
    //... other targets

    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")
        }

        // Dependencies are now scoped to the specific Android source set
        androidMain.dependencies {
            implementation("androidx.appcompat:appcompat:1.7.0")
            implementation("com.google.android.material:material:1.11.0")
        }
    }
}

Các nhóm tài nguyên có bản biên dịch Kotlin tương ứng tên là main, deviceTest và hostTest. Bạn có thể định cấu hình nhóm tài nguyên và bản biên dịch trong tập lệnh bản dựng như sau:

// build.gradle.kts

kotlin {
    android {
        compilations.getByName("deviceTest") {
            kotlinOptions.languageVersion = "2.0"
        }
    }
}

Trình bổ trợ cũ

Với trình bổ trợ cũ, bạn có thể khai báo các phần phụ thuộc dành riêng cho Android trong khối phần phụ thuộc cấp cao nhất. Đôi khi, việc này có thể gây nhầm lẫn trong mô-đun đa nền tảng.

// build.gradle.kts

kotlin {
  androidTarget()
  //... other targets
}

// Dependencies for all source sets were often mixed in one block
dependencies {
  // Common dependencies
  commonMainImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")

  // Android-specific dependencies
  implementation("androidx.appcompat:appcompat:1.7.0")
  implementation("com.google.android.material:material:1.11.0")
}

4. Bật tài nguyên Android

Tính năng hỗ trợ Tài nguyên Android (thư mục res) không được bật theo mặc định với trình bổ trợ mới để tối ưu hoá hiệu suất bản dựng. Bạn phải chọn sử dụng các tính năng này. Thay đổi này giúp đảm bảo rằng các dự án không yêu cầu tài nguyên dành riêng cho Android sẽ không bị gánh nặng bởi chi phí xây dựng liên quan.

Android-KMP

Bạn phải bật rõ ràng tính năng xử lý tài nguyên Android. Tài nguyên phải được đặt trong src/androidMain/res.

// build.gradle.kts

kotlin {
  android {
    // ...
    // Enable Android resource processing
    androidResources {
      enable = true
    }
  }
}

// Project Structure
// └── src
//     └── androidMain
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.xml

Trình bổ trợ cũ

Tính năng xử lý tài nguyên được bật theo mặc định. Bạn có thể thêm ngay thư mục res trong src/main và bắt đầu thêm các giá trị, đối tượng có thể vẽ XML, v.v.

// build.gradle.kts

android {
    namespace = "com.example.library"
    compileSdk = 34
    // No extra configuration was needed to enable resources.
}

// Project Structure
// └── src
//     └── main
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.xml

5. Định cấu hình kiểm thử máy chủ và thiết bị

Theo mặc định, trình bổ trợ mới sẽ tắt các bài kiểm thử phía máy chủ (đơn vị) và phía thiết bị (đo lường) của Android. Bạn phải chọn sử dụng một cách rõ ràng để tạo các nhóm tài nguyên và cấu hình kiểm thử, trong khi trình bổ trợ cũ tạo các nhóm tài nguyên và cấu hình kiểm thử một cách tự động.

Mô hình chọn sử dụng này giúp xác minh rằng dự án của bạn vẫn tinh gọn và chỉ bao gồm logic bản dựng cũng như nhóm tài nguyên mà bạn chủ động sử dụng.

Android-KMP

Với trình bổ trợ mới, bạn có thể bật và định cấu hình các hoạt động kiểm thử bên trong khối kotlin.android. Điều này giúp việc thiết lập trở nên rõ ràng hơn và tránh tạo các thành phần kiểm thử không dùng đến. Nhóm tài nguyên androidUnitTest trở thành androidHostTest (thư mục kiểm thử thay đổi từ src/androidUnitTest thành src/androidHostTest) và androidInstrumentedTest trở thành androidDeviceTest (thư mục kiểm thử thay đổi từ src/androidInstrumentedTest thành src/androidDeviceTest).

// build.gradle.kts

kotlin {
  android {
    // ...

    // Opt-in to enable and configure host-side (unit) tests
    withHostTest {
      isIncludeAndroidResources = true
    }

    // Opt-in to enable and configure device-side (instrumented) tests
    withDeviceTest {
      instrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
      execution = "HOST"
    }
  }
}

// Project Structure (After Opt-in)
// └── src
//     ├── androidHostTest
//     └── androidDeviceTest

Trình bổ trợ cũ

Với trình bổ trợ com.android.library, các nhóm tài nguyên androidUnitTest và androidInstrumentedTest được tạo theo mặc định. Bạn định cấu hình hành vi của các phần phụ thuộc này bên trong khối android, thường là bằng cách sử dụng testOptions DSL.

// build.gradle.kts

android {
  defaultConfig {
    // Runner was configured in defaultConfig
    testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
  }

  testOptions {
    // Configure unit tests (for the 'test' source set)
    unitTests.isIncludeAndroidResources = true

    // Configure device tests (for the 'androidTest' source set)
    execution = "HOST"
  }
}

// Project Structure (Defaults)
// └── src
//     ├── test
//     └── androidTest

6. Bật tính năng biên dịch nguồn Java

Nếu thư viện KMP cần biên dịch các nguồn Java cho mục tiêu Android, bạn phải bật chức năng này một cách rõ ràng bằng trình bổ trợ mới. Xin lưu ý rằng việc này cho phép biên dịch các tệp Java nằm trực tiếp trong dự án của bạn, chứ không phải cho các phần phụ thuộc của dự án. Phương thức đặt phiên bản mục tiêu JVM của trình biên dịch Java và Kotlin cũng thay đổi.

Android-KMP

Bạn phải chọn sử dụng tính năng biên dịch Java bằng cách gọi withJava(). Mục tiêu JVM hiện được định cấu hình trực tiếp bên trong khối kotlin { android {} } để thiết lập hợp nhất hơn. Việc đặt jvmTarget tại đây sẽ áp dụng cho cả quá trình biên dịch Kotlin và Java cho mục tiêu Android.

// build.gradle.kts

kotlin {
  android {
    //  Opt-in to enable Java source compilation
    withJava()
    // Configure the JVM target for both Kotlin and Java sources
    compilerOptions {
      jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8)
    }
  }
  // ...
}

// Project Structure:
// └── src
//     └── androidMain
//         ├── kotlin
//         │   └── com/example/MyKotlinClass.kt
//         └── java
//             └── com.example/MyJavaClass.java

Trình bổ trợ cũ

Tính năng biên dịch Java được bật theo mặc định. Mục tiêu JVM cho cả nguồn Java và Kotlin được đặt trong khối android bằng compileOptions.

// build.gradle.kts

android {
  // ...
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
  }
}

kotlin {
  androidTarget {
    compilations.all {
      kotlinOptions.jvmTarget = "1.8"
    }
  }
}

7. Tương tác với các biến thể bản dựng bằng androidComponents

Tiện ích androidComponents vẫn có sẵn để tương tác với cấu phần phần mềm bản dựng theo phương thức lập trình. Mặc dù phần lớn API Variant vẫn giữ nguyên, nhưng giao diện AndroidKotlinMultiplatformVariant mới bị hạn chế hơn vì trình bổ trợ chỉ tạo ra một biến thể duy nhất.

Do đó, các thuộc tính liên quan đến loại bản dựng và phiên bản sản phẩm không còn có sẵn trên đối tượng biến thể.

Android-KMP

Khối onVariants hiện lặp lại trên một biến thể duy nhất. Bạn vẫn có thể truy cập vào các thuộc tính phổ biến như name và artifacts, nhưng không thể truy cập vào các thuộc tính dành riêng cho loại bản dựng.

// build.gradle.kts

androidComponents {
  onVariants { variant ->
      val artifacts = variant.artifacts
  }
}

Trình bổ trợ cũ

Với nhiều biến thể, bạn có thể truy cập vào các thuộc tính dành riêng cho loại bản dựng để định cấu hình tác vụ.

// build.gradle.kts

androidComponents {
  onVariants(selector().withBuildType("release")) { variant ->
    // ...
  }
}

8. Chọn biến thể của phần phụ thuộc thư viện Android

Thư viện KMP của bạn tạo ra một biến thể duy nhất cho Android. Tuy nhiên, bạn có thể phụ thuộc vào một thư viện Android tiêu chuẩn (com.android.library) có nhiều biến thể (ví dụ: free/paid phiên bản sản phẩm). Kiểm soát cách dự án của bạn chọn một biến thể từ phần phụ thuộc đó là một yêu cầu phổ biến.

Android-KMP

Trình bổ trợ mới tập trung và làm rõ logic này trong khối kotlin.android.localDependencySelection. Điều này giúp bạn biết rõ hơn biến thể nào của phần phụ thuộc bên ngoài sẽ được chọn cho thư viện KMP biến thể đơn.

// build.gradle.kts
kotlin {
  android {
    localDependencySelection {
      // For dependencies with multiple build types, select 'debug' first, and 'release' in case 'debug' is missing
      selectBuildTypeFrom.set(listOf("debug", "release"))

      // For dependencies with a 'type' flavor dimension...
      productFlavorDimension("type") {
        // ...select the 'typeone' flavor.
        selectFrom.set(listOf("typeone"))
      }
    }
  }
}

Trình bổ trợ cũ

Bạn đã định cấu hình chiến lược lựa chọn phần phụ thuộc bên trong các khối buildTypes and productFlavors. Việc này thường liên quan đến việc sử dụng missingDimensionStrategy để cung cấp phiên bản mặc định cho một nhóm phiên bản mà thư viện của bạn không có, hoặc matchingFallbacks trong một phiên bản cụ thể để xác định thứ tự tìm kiếm.

Hãy tham khảo bài viết Giải quyết lỗi so khớp để biết thêm thông tin chi tiết về cách sử dụng API.

9. Thêm phần phụ thuộc của bản xem trước Compose

Thông thường, chúng ta muốn có các thư viện cụ thể trong phạm vi môi trường phát triển cục bộ để ngăn các công cụ nội bộ rò rỉ vào cấu phần phần mềm được xuất bản cuối cùng. Điều này trở thành một thách thức với plugin Android KMP mới vì plugin này loại bỏ cấu trúc loại bản dựng dùng để tách biệt các phần phụ thuộc phát triển khỏi mã phát hành.

Android-KMP

Để chỉ thêm phần phụ thuộc cho quá trình phát triển và kiểm thử cục bộ, hãy thêm phần phụ thuộc trực tiếp vào cấu hình classpath thời gian chạy (trong khối dependencies cấp cao nhất) của quá trình biên dịch Android chính. Việc này giúp đảm bảo phần phụ thuộc có sẵn trong thời gian chạy (ví dụ: đối với các công cụ như Xem trước trong Compose) nhưng không thuộc classpath biên dịch hoặc API đã phát hành của thư viện.

// build.gradle.kts
dependencies {
  "androidRuntimeClasspath"(libs.androidx.compose.ui.tooling)
}

Trình bổ trợ cũ

Các dự án Kotlin Multiplatform sử dụng trình bổ trợ com.android.library cho mục tiêu Android nên sử dụng cấu hình debugImplementation. Cấu hình này sẽ đặt phạm vi của phần phụ thuộc vào loại bản gỡ lỗi và ngăn phần phụ thuộc này được đưa vào biến thể phát hành của thư viện mà người dùng sử dụng.

// build.gradle.kts
dependencies {
  debugImplementation(libs.androidx.compose.ui.tooling)
}

10. Định cấu hình mục tiêu JVM cho mục tiêu Android KMP

Trình bổ trợ KMP Android đặt mục tiêu JVM bằng android.compilerOptions.jvmTarget, áp dụng cho cả Java và Kotlin, giúp đơn giản hoá cấu hình so với các khối compileOptions và kotlinOptions riêng biệt trong các dự án Android thuần tuý.

Android-KMP

Khi xử lý một dự án Kotlin Multiplatform (KMP) có mục tiêu Android, bạn có một số cách để định cấu hình phiên bản mục tiêu JVM cho cả trình biên dịch Kotlin và Java. Việc hiểu rõ phạm vi và hệ phân cấp của các cấu hình này là yếu tố then chốt để quản lý khả năng tương thích của mã byte trong dự án.

Dưới đây là ba cách chính để đặt mục tiêu JVM, được sắp xếp theo thứ tự ưu tiên từ thấp nhất đến cao nhất. Các giá trị mục tiêu JVM có mức độ ưu tiên cao hơn sẽ áp dụng cho một nhóm nhỏ hơn trong số các mục tiêu đã định cấu hình và ghi đè các giá trị có mức độ ưu tiên thấp hơn. Điều này có nghĩa là bạn có thể đặt các phiên bản JVM khác nhau cho các mục tiêu và bản biên dịch khác nhau trong các mục tiêu của dự án.

Sử dụng chuỗi công cụ Kotlin (mức độ ưu tiên thấp nhất)

Cách chung nhất để đặt mục tiêu JVM là chỉ định chuỗi công cụ trong khối kotlin của tệp build.gradle.kts. Phương pháp này đặt mục tiêu cho cả tác vụ biên dịch Kotlin và Java trên tất cả các mục tiêu dựa trên JVM trong dự án của bạn, bao gồm cả Android.

// build.gradle.kts
kotlin {
    jvmToolchain(21)
}

Cấu hình này giúp cả kotlinc và javac đều nhắm đến JVM 21. Đây là một cách hiệu quả để thiết lập đường cơ sở nhất quán cho toàn bộ dự án.

Sử dụng các tuỳ chọn trình biên dịch cấp mục tiêu của Android (mức độ ưu tiên trung bình)

Bạn có thể chỉ định mục tiêu JVM dành riêng cho mục tiêu KMP Android trong khối android. Chế độ cài đặt này ghi đè cấu hình jvmToolchain trên toàn dự án và áp dụng cho tất cả các bản biên dịch Android.

// build.gradle.kts
kotlin {
    android {
        compilerOptions {
            jvmTarget.set(JvmTarget.JVM_11)
        }
    }
}

Trong trường hợp này, ngay cả khi jvmToolchain được đặt thành một phiên bản khác, mã Kotlin và Java của mục tiêu Android sẽ được biên dịch để nhắm đến JVM 11.

Sử dụng các tuỳ chọn trình biên dịch ở cấp biên dịch (mức độ ưu tiên cao nhất)

Để có quyền kiểm soát chi tiết nhất, bạn có thể định cấu hình các tuỳ chọn trình biên dịch trên cơ sở mỗi lần biên dịch (ví dụ: chỉ trên androidMain hoặc androidHostTest). Điều này rất hữu ích nếu một bản biên dịch cụ thể cần nhắm đến một phiên bản JVM khác. Chế độ cài đặt này ghi đè cả chuỗi công cụ Kotlin và các tuỳ chọn cấp mục tiêu của Android.

// build.gradle.kts
kotlin {
    android {
        compilations.all {
            compileTaskProvider.configure {
                compilerOptions.jvmTarget.set(JvmTarget.JVM_11)
            }
        }
    }
}

Cấu hình này giúp đảm bảo rằng tất cả các bản biên dịch trong mục tiêu Android đều sử dụng JVM 11, mang lại khả năng kiểm soát chi tiết.

Trình bổ trợ cũ

Trong một dự án KMP sử dụng trình bổ trợ thư viện Android tiêu chuẩn (com.android.library), cấu hình sẽ hơi khác so với khi bạn sử dụng Plugin Android KMP (nhưng về mặt khái niệm thì tương tự).

Sử dụng chuỗi công cụ Kotlin

Phương thức kotlin.jvmToolchain() hoạt động giống hệt nhau, đặt sourceCompatibility và targetCompatibility cho Java và jvmTarget cho Kotlin. Bạn nên sử dụng phương pháp này.

// build.gradle.kts
kotlin {
    jvmToolchain(21)
}

compileOptions và kotlinOptions

Nếu không sử dụng chuỗi công cụ Kotlin, bạn phải định cấu hình các mục tiêu JVM bằng cách sử dụng các khối riêng biệt cho Java và Kotlin.

// build.gradle.kts
android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }

    kotlinOptions {
        jvmTarget = "11"
    }
}

11. Xuất bản quy tắc giữ lại cho người dùng

Nếu thư viện KMP cần cung cấp quy tắc lưu giữ của người dùng (chẳng hạn như quy tắc ProGuard cho R8) cho người dùng, thì bạn cần bật tính năng xuất bản một cách rõ ràng bằng trình bổ trợ mới. Trước đây, các quy tắc giữ lại của người dùng được xuất bản theo mặc định nếu được chỉ định.

Android-KMP

Với trình bổ trợ mới, bạn phải đặt optimization.consumerKeepRules.publish = true và chỉ định các tệp quy tắc trong khối consumerKeepRules để xuất bản quy tắc giữ lại của người dùng.

// build.gradle.kts
kotlin {
  android {
    optimization {
      consumerKeepRules.apply {
        publish = true
        file("consumer-proguard-rules.pro")
      }
    }
  }
}

Trình bổ trợ cũ

Với com.android.library, mọi tệp quy tắc được chỉ định bằng consumerProguardFiles trong android.defaultConfig đều được xuất bản trong cấu phần phần mềm của thư viện theo mặc định.

// build.gradle.kts
android {
  defaultConfig {
    consumerProguardFiles("consumer-proguard-rules.pro")
  }
}

12. Xuất bản thư viện lên Maven

Nếu bạn dự định phát hành thư viện KMP lên Maven để các dự án khác sử dụng, thì quy trình sẽ khác nhau tuỳ thuộc vào việc bạn đang sử dụng trình bổ trợ Android-KMP mới hay trình bổ trợ cũ.

Android-KMP

Trình bổ trợ com.android.kotlin.multiplatform.library tích hợp với các cơ chế phát hành Kotlin Multiplatform tiêu chuẩn. Bạn không cần thực hiện bước nào dành riêng cho Android ngoài quy trình phát hành thư viện KMP tiêu chuẩn.

Để xuất bản thư viện, hãy làm theo tài liệu chính thức của JetBrains: Thiết lập tính năng xuất bản cho thư viện đa nền tảng.

Trình bổ trợ cũ

Khi sử dụng com.android.library cho mục tiêu Android trong dự án KMP, bạn cần làm theo hướng dẫn xuất bản thư viện Android tiêu chuẩn để chuẩn bị và xuất bản cấu phần phần mềm dành riêng cho Android (.aar).

Để biết hướng dẫn chi tiết, hãy xem bài viết Chuẩn bị phát hành thư viện.

Tài liệu tham khảo API trình bổ trợ

Trình bổ trợ mới có nền tảng API khác với com.android.library. Để biết thông tin chi tiết về DSL và giao diện mới, hãy xem tài liệu tham khảo API:

Các vấn đề đã biết về trình bổ trợ thư viện Android-KMP

Dưới đây là các vấn đề đã biết có thể xảy ra khi bạn áp dụng trình bổ trợ com.android.kotlin.multiplatform.library mới: