پلاگین Android Gradle Library را برای KMP تنظیم کنید

پلاگین com.android.kotlin.multiplatform.library Gradle ابزار رسمی پشتیبانی شده برای افزودن هدف اندروید به ماژول کتابخانه چند پلتفرمی Kotlin (KMP) است. این پیکربندی پروژه را ساده می کند، عملکرد ساخت را بهبود می بخشد و ادغام بهتری با Android Studio ارائه می دهد.

رویکرد قبلی اکنون به نفع این افزونه منسوخ شده است که به آن افزونه Android-KMP نیز گفته می شود. ادامه استفاده از افزونه com.android.library برای KMP دیگر توسط JetBrains پشتیبانی نمی‌شود و از به‌روزرسانی‌ها و بهبودهای آینده بهره‌مند نخواهد شد.

برای اعمال این افزونه به قسمت Apply the Android-KMP افزونه مراجعه کنید. اگر نیاز به مهاجرت از APIهای قدیمی دارید، راهنمای مهاجرت را بررسی کنید.

ویژگی ها و تفاوت های کلیدی

افزونه Android-KMP به طور خاص برای پروژه های KMP طراحی شده است و از چندین جنبه کلیدی با پلاگین استاندارد com.android.library متفاوت است:

• معماری تک نوع: این افزونه از یک نوع استفاده می‌کند، که پشتیبانی از طعم‌های محصول و انواع ساخت را حذف می‌کند، که پیکربندی را ساده می‌کند و عملکرد ساخت را افزایش می‌دهد.

• بهینه‌سازی شده برای KMP: این افزونه برای کتابخانه‌های KMP طراحی شده است، با تمرکز بر روی کد Kotlin مشترک و قابلیت همکاری، پشتیبانی از ساخت‌های بومی خاص اندروید، AIDL و RenderScript را حذف می‌کند.

• تست‌ها به‌طور پیش‌فرض غیرفعال می‌شوند: تست‌های واحد و دستگاه (دستگاه ابزار دقیق) به‌طور پیش‌فرض غیرفعال هستند تا سرعت ساخت را افزایش دهند. در صورت نیاز می توانید آنها را فعال کنید.

• بدون برنامه افزودنی اندروید سطح بالا: پیکربندی با یک بلوک androidLibrary در Gradle KMP DSL انجام می شود و ساختار پروژه KMP یکنواخت را حفظ می کند. هیچ بلوک برنامه افزودنی android در سطح بالا وجود ندارد.

• Opt-in Compilation Java: کامپایل جاوا به طور پیش فرض غیرفعال است. withJava() در بلوک androidLibrary برای فعال کردن آن استفاده کنید. این باعث بهبود زمان‌های ساخت زمانی می‌شود که به کامپایل جاوا نیازی نیست.

مزایای افزونه کتابخانه Android-KMP

افزونه Android-KMP مزایای زیر را برای پروژه های KMP فراهم می کند:

• عملکرد و پایداری ساخت بهبود یافته: برای سرعت ساخت بهینه و پایداری افزایش یافته در پروژه های KMP مهندسی شده است. تمرکز آن بر گردش کار KMP به فرآیند ساخت کارآمدتر و قابل اعتمادتر کمک می کند.

• یکپارچه سازی IDE پیشرفته: تکمیل کد، پیمایش، اشکال زدایی و تجربه کلی توسعه دهنده را هنگام کار با کتابخانه های KMP Android فراهم می کند.

• پیکربندی پروژه ساده شده: این افزونه با حذف پیچیدگی های خاص اندروید مانند انواع ساخت، پیکربندی پروژه های KMP را ساده می کند. این منجر به ساخت فایل های تمیزتر و قابل نگهداری تر می شود. قبلاً، استفاده از افزونه com.android.library در پروژه KMP می‌توانست نام مجموعه منبع گیج‌کننده‌ای مانند androidAndroidTest ایجاد کند. این قرارداد نامگذاری برای توسعه دهندگانی که با ساختارهای استاندارد پروژه KMP آشنا بودند کمتر بصری بود.

پیش نیازها

برای استفاده از افزونه com.android.kotlin.multiplatform.library ، پروژه شما باید با حداقل نسخه های زیر یا بالاتر پیکربندی شود:

• پلاگین Android Gradle (AGP) : 8.10.0
• پلاگین Kotlin Gradle (KGP) : 2.0.0

افزونه Android-KMP را روی یک ماژول موجود اعمال کنید

برای اعمال افزونه Android-KMP در یک ماژول کتابخانه KMP موجود، این مراحل را دنبال کنید:

1. پلاگین ها را در کاتالوگ نسخه اعلام کنید. فایل TOML کاتالوگ نسخه (معمولاً gradle/libs.versions.toml ) را باز کنید و بخش تعاریف افزونه را اضافه کنید:

   # To check the version number of the latest Kotlin release, go to
   # https://kotlinlang.org/docs/releases.html
   
   [versions]
   androidGradlePlugin = "8.12.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. اعلان پلاگین را در فایل ساخت ریشه اعمال کنید. فایل build.gradle.kts واقع در دایرکتوری ریشه پروژه خود را باز کنید. نام مستعار افزونه را با استفاده از apply false به بلوک plugins اضافه کنید. این باعث می شود که نام مستعار افزونه برای همه زیر پروژه ها بدون اعمال منطق پلاگین در خود پروژه ریشه در دسترس باشد.

   کاتلین

   // 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
   }

   شیار

   // 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. افزونه را در فایل ساخت ماژول کتابخانه KMP اعمال کنید. فایل build.gradle.kts را در ماژول کتابخانه KMP خود باز کنید و افزونه را در بالای فایل خود در بلوک plugins اعمال کنید:

   کاتلین

   // Module-specific build.gradle.kts file
   
   plugins {
      alias(libs.plugins.kotlin.multiplatform)
   
      // Add the following
      alias(libs.plugins.android.kotlin.multiplatform.library)
   }

   شیار

   // Module-specific build.gradle file
   
   plugins {
      alias(libs.plugins.kotlin.multiplatform)
   
      // Add the following
      alias(libs.plugins.android.kotlin.multiplatform.library)
   }

4. هدف Android KMP را پیکربندی کنید. بلوک چند پلتفرمی Kotlin ( kotlin ) را برای تعریف هدف اندروید پیکربندی کنید. در بلوک kotlin ، هدف Android را با استفاده از androidLibrary مشخص کنید:

   کاتلین

   kotlin {
      androidLibrary {
          namespace = "com.example.kmpfirstlib"
          compileSdk = 33
          minSdk = 24
   
          withJava() // enable java compilation support
          withHostTestBuilder {}.configure {}
          withDeviceTestBuilder {
              sourceSetTreeName = "test"
          }
   
          compilations.configureEach {
              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.) ...
   }

   شیار

   kotlin {
      androidLibrary {
          namespace = "com.example.kmpfirstlib"
          compileSdk = 33
          minSdk = 24
   
          withJava() // enable java compilation support
          withHostTestBuilder {}.configure {}
          withDeviceTestBuilder {
              it.sourceSetTreeName = "test"
          }
   
          compilations.configureEach {
              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. اعمال تغییرات پس از اعمال افزونه و پیکربندی بلوک kotlin ، پروژه Gradle خود را برای اعمال تغییرات همگام کنید.

از افزونه قدیمی مهاجرت کنید

این راهنما به شما کمک می کند از افزونه قدیمی com.android.library به افزونه com.android.kotlin.multiplatform.library مهاجرت کنید.

1. اعلام وابستگی ها

یک کار رایج، اعلام وابستگی برای مجموعه‌های منبع خاص اندروید است. افزونه جدید نیاز دارد که اینها به صراحت در بلوک sourceSets قرار گیرند، برخلاف بلوک dependencies عمومی که قبلاً استفاده می شد.

// 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")
        }
    }
}

// build.gradle.kts

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

// 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")
}

2. فعال کردن منابع اندروید

پشتیبانی از منابع Android (پوشه‌های res ) به‌طور پیش‌فرض در افزونه جدید برای بهینه‌سازی عملکرد ساخت فعال نیست. برای استفاده از آنها باید انتخاب کنید. این تغییر کمک می‌کند تا اطمینان حاصل شود که پروژه‌هایی که به منابع اختصاصی Android نیاز ندارند، توسط سربار ساخت مرتبط تحت فشار قرار نخواهند گرفت.

// build.gradle.kts

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

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

// 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

3. پیکربندی تست هاست و دستگاه

یک تغییر قابل توجه در افزونه جدید این است که تست های سمت میزبان (واحد) و سمت دستگاه (دستگاهی) اندروید به طور پیش فرض غیرفعال هستند . برای ایجاد مجموعه‌ها و پیکربندی‌های منبع آزمایشی باید صریحاً شرکت کنید، در حالی که افزونه قدیمی آنها را به‌طور خودکار ایجاد کرده است.

این مدل انتخاب به تأیید کمک می‌کند که پروژه شما ناب باقی بماند و فقط شامل منطق ساخت و مجموعه‌های منبعی است که فعالانه استفاده می‌کنید.

// 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 = "ANDROIDX_TEST_ORCHESTRATOR"
    }
  }
}

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

// 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 = "ANDROIDX_TEST_ORCHESTRATOR"
  }
}

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

4. کامپایل منبع جاوا را فعال کنید

اگر کتابخانه KMP شما نیاز به کامپایل منابع جاوا برای هدف اندرویدی خود دارد، باید این قابلیت را به صراحت با افزونه جدید فعال کنید. توجه داشته باشید که این کار کامپایل را برای فایل‌های جاوا که مستقیماً در پروژه شما قرار دارند، فعال می‌کند، نه برای وابستگی‌های آن. روش تنظیم نسخه هدف JVM کامپایلر جاوا و کاتلین نیز تغییر می کند.

// 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

// build.gradle.kts

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

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

5. با نسخه های ساخت با استفاده از androidComponents تعامل داشته باشید

افزونه androidComponents همچنان برای تعامل با مصنوعات ساخت به صورت برنامه‌ریزی در دسترس است. در حالی که بسیاری از Variant API یکسان باقی می‌مانند، رابط AndroidKotlinMultiplatformVariant جدید محدودتر است، زیرا این افزونه تنها یک نسخه را تولید می‌کند.

در نتیجه، ویژگی‌های مربوط به انواع ساخت و طعم‌های محصول دیگر در شیء مختلف موجود نیست.

// build.gradle.kts

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

// build.gradle.kts

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

6. انواع وابستگی های کتابخانه اندروید را انتخاب کنید

کتابخانه KMP شما یک نسخه واحد را برای Android تولید می کند. با این حال، ممکن است به یک کتابخانه استاندارد Android ( com.android.library ) وابسته باشید که انواع مختلفی دارد (مثلاً طعم محصول free/paid ). کنترل اینکه چگونه پروژه شما یک نوع از آن وابستگی را انتخاب می کند یک نیاز رایج است.

// 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"))
      }
    }
  }
}

مرجع API پلاگین

پلاگین جدید سطح API متفاوتی نسبت به com.android.library دارد. برای اطلاعات دقیق در مورد DSL و رابط های جدید، به مراجع API مراجعه کنید:

• KotlinMultiplatformAndroidLibraryExtension
• KotlinMultiplatformAndroidLibraryTarget
• KotlinMultiplatformAndroidDeviceTest
• KotlinMultiplatformAndroidHostTest
• KotlinMultiplatformAndroidVariant