راه‌اندازی افزایه کتابخانه Android Gradle برای KMP

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

استفاده از افزونه com.android.library برای توسعه KMP به میاناهای برنامه‌سازی کاربردی افزونه Android Gradle بستگی دارد که منسوخ شده‌اند و در افزونه Android Gradle نسخه ۹.۰ و بالاتر (سه‌ماهه چهارم ۲۰۲۵) نیاز به موافقت دارند. انتظار می‌رود این میاناهای برنامه‌سازی کاربردی در افزایه Android Gradle نسخه ۱۰.۰ (نیمه دوم ۲۰۲۶) برداشته شوند.

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

برای دریافت راهنمایی درباره انتقال AGP 9.0+‎، می‌توانید از مهارت عامل ایجادشده توسط JetBrains برای برنامه‌های KMP استفاده کنید. برای اطلاعات بیشتر درباره استفاده از مهارت‌ها در Android Studio، به گسترش دادن «حالت عامل» با مهارت‌ها مراجعه کنید. به‌خاطر داشته باشید که نتایج هوش مصنوعی کاملاً قابل‌پیش‌بینی نیست.

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

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

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

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

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

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

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

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

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

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

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

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

راه‌حل‌های جایگزین برای ویژگی‌های پشتیبانی‌نشده

درمقایسه با ادغام KMP با افزونه com.android.library، برخی‌از ویژگی‌ها در افزونه com.android.kotlin.multiplatform.library وجود ندارد. در اینجا راهکارهایی برای ویژگی‌های پشتیبانی‌نشده ارائه شده است:

  • تنوع‌های ساخت

    از انواع ساخت و نسخه‌های ویژه محصول پشتیبانی نمی‌شود. دلیلش این است که افزونه جدید از معماری تک‌متغیره استفاده می‌کند که پیکربندی را ساده می‌کند و عملکرد ساخت را بهبود می‌بخشد.

    اگر به تنوع ساخت نیاز دارید، توصیه ما این است که بااستفاده از افزونه com.android.library، یک واحد کتابخانه Android مستقل جداگانه ایجاد کنید، انواع ساخت و نسخه‌های ویژه محصول را در آن واحد پیکربندی کنید، و سپس آن را به‌عنوان وابستگی پروژه استاندارد از مجموعه منبع androidMain کتابخانه Kotlin Multiplatform خود مصرف کنید. برای جزئیات بیشتر، ایجاد کتابخانه Android و پیکربندی تنوع‌های ساخت را ببینید.

  • ترابست داده‌ها و ترابست View

    این‌ها ویژگی‌های چارچوب میانای کاربری مختص Android هستند که به‌طور تنگاتنگی با سیستم «نمای Android» و چیدمان‌های XML مرتبط هستند. با افزونه جدید کتابخانه Android-KMP، توصیه می‌کنیم که میانای کاربری را بااستفاده از چارچوب چندپلاتفرمی مانند Compose Multiplatform مدیریت کنید. اتصال داده و اتصال نما جزو جزئیات پیاده‌سازی برنامه Android نهایی درنظر گرفته می‌شوند، نه کتابخانه قابل‌هم‌رسانی.

  • پشتیبانی از ساخت بومی

    افزونه جدید بر تولید یک AAR استاندارد برای هدف Android تمرکز دارد. ادغام کد بومی در Kotlin چندپلاتفرمی مستقیماً توسط هدف‌های بومی خود KMP (مانند androidNativeArm64 و androidNativeX86) و قابلیت‌های C-interop آن انجام می‌شود. اگر لازم است کد C/C++‎ بومی را اضافه کنید، باید آن را به‌عنوان بخشی از مجموعه منبع مشترک یا بومی تعریف کنید و C-interop را در بلوک kotlin پیکربندی کنید، نه اینکه از سازوکار externalNativeBuild مختص Android استفاده کنید.

    یا اگر به پشتیبانی ساخت بومی ازطریق externalNativeBuild نیاز دارید، توصیه می‌کنیم یک واحد مستقل com.android.library جداگانه ایجاد کنید که در آن بتوانید کد بومی را ادغام کنید و از آن کتابخانه مستقل در مجموعه منبع androidMain پروژه کتابخانه Kotlin Multiplatform خود استفاده کنید. برای جزئیات بیشتر، ایجاد کتابخانه Android و افزودن کد C و C++‎ به پروژه را ببینید.

  • کلاس BuildConfig

    ویژگی BuildConfig در محیط‌های چندمتغیره بیشترین کاربرد را دارد. ازآنجایی‌که افزایه جدید کتابخانه Kotlin Multiplatform مستقل از گونه است و از انواع ساخت و نسخه‌های ویژه محصول پشتیبانی نمی‌کند، این ویژگی پیاده‌سازی نشده است. به‌عنوان جایگزین، توصیه می‌کنیم از افزونه BuildKonfig یا راه‌حل‌های مشابه انجمن برای تولید فراداده برای همه هدف‌ها استفاده کنید.

پیش‌نیازها

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

  • افزایه Android Gradle‏ (AGP): 8.10.0
  • Kotlin Gradle Plugin (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 = "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. اعلامیه افزایه را در فایل ساخت ریشه اعمال کنید. فایل 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. پیکربندی هدف KMP در Android. بلوک Kotlin Multiplatform را پیکربندی کنید (kotlin) تا هدف Android را تعریف کنید. در بلوک kotlin، هدف Android را بااستفاده از android مشخص کنید:

    کاتلین

    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.) ...
}

    شیک

    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. تغییرات را اعمال کنید. پس‌از اعمال افزایه و پیکربندی بلوک kotlin، پروژه Gradle خود را همگام‌سازی کنید تا تغییرات اعمال شوند.

انتقال از افزونه قدیمی

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

۱. انتقال منابع

افزونه قدیمی به شما اجازه می‌داد از مجموعه‌های منبع src/main،‏ src/test، و src/androidTest، علاوه‌بر src/androidMain،‏ src/androidHostTest، و src/androidDeviceTest استفاده کنید. افزونه جدید فقط از دایرکتوری‌های منبع دوم استفاده می‌کند، بنابراین باید منابع را از src/main به src/androidMain، از src/test به src/androidHostTest، و از src/androidTest به src/androidDeviceTest منتقل کنید.

۲. پیکربندی فهرست‌های راهنمای منبع و منابع سفارشی

اگر منابع یا منابعی در دایرکتوری‌های غیراستاندارد دارید، قبلاً آن‌ها را بااستفاده از بلوک sourceSets پیکربندی کرده‌اید. با افزایه جدید، از افزونه androidComponents برای افزودن دایرکتوری‌های منبع ایستا به متغیر استفاده کنید.

توجه داشته باشید که با افزونه جدید، روش addStaticSourceDirectory دایرکتوری را به فهرست موجود دایرکتوری‌های منبع اضافه می‌کند. با افزونه قدیمی، روش setSrcDirs جایگزین فهرست می‌شود، درحالی‌که روش srcDir به آن اضافه می‌کند.

Android-KMP

با افزونه جدید، از بلوک onVariants برای تعامل با منابع نسخه استفاده کنید.

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

افزایه قدیمی

با افزونه com.android.library، از بلوک sourceSets برای تنظیم یا افزودن دایرکتوری‌های منبع استفاده شد.

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

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

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

Android-KMP

افزونه جدید با گروه‌بندی وابستگی‌های Android در مجموعه منبع androidMain، ساختار تمیزتری را ترویج می‌کند. علاوه‌بر مجموعه منبع اصلی، دو مجموعه منبع آزمایشی وجود دارد که درصورت درخواست ایجاد می‌شوند: androidDeviceTest و androidHostTest (برای اطلاعات بیشتر، پیکربندی آزمایش‌های میزبان و دستگاه را بررسی کنید).

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

مجموعه‌های منبع دارای کامپایل‌های Kotlin متناظر با نام‌های main، deviceTest، و hostTest هستند. مجموعه‌های منبع و کامپایل‌ها را می‌توان در اسکریپت ساخت به این صورت پیکربندی کرد:

// build.gradle.kts

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

افزایه قدیمی

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

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

۴. فعال کردن منابع Android

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

Android-KMP

باید پردازش منابع Android را صریحاً فعال کنید. منابع باید در 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

افزایه قدیمی

پردازش منبع به‌طور پیش‌فرض فعال بود. می‌توانید فوراً یک دایرکتوری res در src/main اضافه کنید و شروع به افزودن 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

۵. پیکربندی آزمایش‌های میزبان و دستگاه

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

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

Android-KMP

با افزونه جدید، آزمایش‌ها را در بلوک kotlin.android فعال و پیکربندی می‌کنید. این کار راه‌اندازی را صریح‌تر می‌کند و از ایجاد مؤلفه‌های آزمایشی استفاده‌نشده جلوگیری می‌کند. مجموعه منبع androidUnitTest به androidHostTest تبدیل می‌شود (دایرکتوری آزمایش از src/androidUnitTest به src/androidHostTest تغییر می‌کند)، و androidInstrumentedTest به androidDeviceTest تبدیل می‌شود (دایرکتوری آزمایش از src/androidInstrumentedTest به 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

افزایه قدیمی

با افزایه com.android.library، مجموعه‌های منبع androidUnitTest و androidInstrumentedTest به‌طور پیش‌فرض ایجاد می‌شوند. رفتار آن‌ها را در بلوک android پیکربندی می‌کنید، معمولاً بااستفاده از 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

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

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

Android-KMP

باید با فراخوانی withJava()، با کامپایل Java موافقت کنید. هدف JVM اکنون مستقیماً در بلوک kotlin { android {} } پیکربندی می‌شود تا راه‌اندازی یکپارچه‌تر باشد. تنظیم jvmTarget در اینجا هم برای Kotlin و هم برای Java برای هدف 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

افزایه قدیمی

کامپایل Java به‌طور پیش‌فرض فعال بود. هدف JVM برای هر دو منبع Java و Kotlin در بلوک android بااستفاده از compileOptions تنظیم شده بود.

// build.gradle.kts

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

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

‫۷. تعامل با تنوع‌های ساخت بااستفاده از androidComponents

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

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

Android-KMP

بلوک onVariants اکنون روی یک متغیر تکرار می‌شود. همچنان می‌توانید به ویژگی‌های رایج مثل name و artifacts دسترسی داشته باشید، اما به ویژگی‌های مختص نوع ساخت دسترسی ندارید.

// build.gradle.kts

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

افزایه قدیمی

با چند نوع، می‌توانید به ویژگی‌های خاص نوع ساخت برای پیکربندی تکالیف دسترسی داشته باشید.

// build.gradle.kts

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

‫۸. انواع وابستگی‌های کتابخانه Android را انتخاب کنید

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

Android-KMP

افزونه جدید این منطق را در بلوک kotlin.android.localDependencySelection متمرکز و شفاف می‌کند. این کار باعث می‌شود که مشخص شود کدام‌یک از انواع وابستگی‌های خارجی برای کتابخانه KMP تک‌نوعی شما انتخاب خواهد شد.

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

افزایه قدیمی

استراتژی‌های انتخاب وابستگی را در بلوک‌های buildTypes and productFlavors پیکربندی کرده‌اید. این کار اغلب شامل استفاده از missingDimensionStrategy برای ارائه یک نوع پیش‌فرض برای بعدی بود که کتابخانه شما نداشت، یا matchingFallbacks در یک نوع خاص برای تعریف ترتیب جستجو.

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

‫۹. افزودن وابستگی‌های پیش‌نمای Compose

معمولاً می‌خواهیم کتابخانه‌های خاصی را در محیط توسعه محلی خود داشته باشیم تا از نشت ابزارهای داخلی به محصول نهایی منتشرشده جلوگیری کنیم. این موضوع با افزایه جدید KMP Android به چالشی تبدیل می‌شود زیرا معماری نوع ساخت را که برای جدا کردن وابستگی‌های توسعه از کد انتشار استفاده می‌شود برمی‌دارد.

Android-KMP

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

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

افزایه قدیمی

پروژه‌های Kotlin Multiplatform که از افزونه com.android.library برای هدف Android استفاده می‌کنند باید از پیکربندی debugImplementation استفاده کنند، که وابستگی را به نوع ساخت اشکال‌زدایی محدود می‌کند و از گنجانده شدن آن در نسخه انتشار کتابخانه که توسط مصرف‌کنندگان استفاده می‌شود جلوگیری می‌کند.

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

‫۱۰. پیکربندی هدف JVM برای هدف KMP Android

افزایه KMP Android هدف JVM را بااستفاده از android.compilerOptions.jvmTarget تنظیم می‌کند که هم برای Java و هم برای Kotlin اعمال می‌شود و پیکربندی را درمقایسه با بلوک‌های جداگانه compileOptions و kotlinOptions در پروژه‌های Android خالص ساده می‌کند.

Android-KMP

When working with a Kotlin Multiplatform (KMP) project that includes an Android target, you have several ways to configure the JVM target version for both Kotlin and Java compiler. درک دامنه و سلسله‌مراتب این پیکربندی‌ها کلید مدیریت سازگاری بایت‌کد پروژه شما است.

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

استفاده از زنجیره ابزار kotlin (پایین‌ترین اولویت)

رایج‌ترین روش برای تنظیم هدف JVM، مشخص کردن زنجیره ابزار در بلوک kotlin فایل build.gradle.kts است. این رویکرد هدف را برای هر دو تکلیف کامپایل Kotlin و Java در همه هدف‌های مبتنی بر JVM در پروژه شما، ازجمله Android، تنظیم می‌کند.

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

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

استفاده از گزینه‌های کامپایلر سطح هدف Android (اولویت متوسط)

می‌توانید هدف JVM را به‌طور خاص برای هدف KMP Android در بلوک android مشخص کنید. این تنظیمات پیکربندی jvmToolchain در سطح پروژه را لغو می‌کند و برای همه کامپایل‌های Android اعمال می‌شود.

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

در این حالت، حتی اگر jvmToolchain روی نسخه دیگری تنظیم شده باشد، کد Kotlin و Java هدف Android برای هدف قرار دادن JVM 11 کامپایل خواهد شد.

استفاده از گزینه‌های کامپایلر در سطح کامپایل (بالاترین اولویت)

برای دقیق‌ترین کنترل، می‌توانید گزینه‌های کامپایلر را براساس هر کامپایل پیکربندی کنید (برای مثال فقط در androidMain یا androidHostTest). این ویژگی زمانی مفید است که یک کامپایل خاص نیاز به هدف قرار دادن نسخه متفاوتی از JVM داشته باشد. این تنظیم هم زنجیره ابزار Kotlin و هم گزینه‌های سطح هدف Android را لغو می‌کند.

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

این پیکربندی کمک می‌کند تا اطمینان حاصل شود که همه کامپایل‌ها در هدف Android از JVM 11 استفاده می‌کنند و کنترل دقیقی را فراهم می‌کند.

افزایه قدیمی

در پروژه KMP که از افزایه کتابخانه استاندارد Android (com.android.library) استفاده می‌کند، پیکربندی کمی با زمانی‌که از افزایه KMP Android استفاده می‌کنید متفاوت است (اما ازنظر مفهومی مشابه است).

استفاده از زنجیره ابزار kotlin

روش kotlin.jvmToolchain() به‌طور یکسان عمل می‌کند و sourceCompatibility و targetCompatibility را برای جاوا و jvmTarget را برای Kotlin تنظیم می‌کند. توصیه می‌کنیم از این رویکرد استفاده کنید.

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

compileOptions و kotlinOptions

اگر از زنجیره ابزار Kotlin استفاده نمی‌کنید، باید اهداف JVM را بااستفاده از بلوک‌های جداگانه برای Java و Kotlin پیکربندی کنید.

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

    kotlinOptions {
        jvmTarget = "11"
    }
}

‫۱۱. انتشار قوانین نگهداری مصرف‌کننده

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

Android-KMP

با افزونه جدید، باید optimization.consumerKeepRules.publish = true را تنظیم کنید و فایل‌های قانون را در بلوک consumerKeepRules مشخص کنید تا قوانین نگهداری مصرف‌کننده را منتشر کنید.

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

افزایه قدیمی

با com.android.library، هر فایل قانونی که با consumerProguardFiles در android.defaultConfig مشخص شده باشد، به‌طور پیش‌فرض در مصنوعات کتابخانه منتشر می‌شود.

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

‫۱۲. انتشار کتابخانه در Maven

اگر قصد دارید کتابخانه KMP خود را برای استفاده در پروژه‌های دیگر در Maven منتشر کنید، فرایند بسته به اینکه از افزونه جدید Android-KMP یا افزونه قدیمی استفاده می‌کنید متفاوت است.

Android-KMP

افزایه com.android.kotlin.multiplatform.library با سازوکارهای انتشار استاندارد Kotlin Multiplatform ادغام می‌شود. هیچ مرحله خاصی برای Android فراتر از فرایند استاندارد انتشار کتابخانه KMP لازم نیست.

برای انتشار کتابخانه‌تان، اسناد رسمی JetBrains را دنبال کنید: راه‌اندازی انتشار برای کتابخانه چندپلاتفرمی.

افزایه قدیمی

هنگام استفاده از com.android.library برای هدف Android در پروژه KMP، باید راهنمای استاندارد انتشار کتابخانه Android را دنبال کنید تا مصنوعات خاص Android (.aar) را آماده و منتشر کنید.

برای دستورالعمل‌های دقیق، آماده‌سازی کتابخانه برای انتشار را ببینید.

مرجع میانای برنامه‌سازی کاربردی افزایه

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

مشکلات شناخته‌شده با افزونه کتابخانه Android-KMP

این‌ها مشکلات شناخته‌شده‌ای هستند که ممکن است هنگام اعمال کردن افزونه جدید com.android.kotlin.multiplatform.library رخ دهند: