KMP için Android Gradle Library Plugin'i ayarlama

com.android.kotlin.multiplatform.library Gradle eklentisi, Kotlin Multiplatform (KMP) kitaplık modülüne Android hedefi eklemek için resmi olarak desteklenen araçtır. Proje yapılandırmasını basitleştirir, derleme performansını artırır ve Android Studio ile daha iyi entegrasyon sunar.

Önceki yaklaşım, Android-KMP eklentisi olarak da bilinen eklenti lehine artık kullanımdan kaldırılmıştır. KMP için com.android.library eklentisinin kullanımı artık JetBrains tarafından desteklenmeyecek ve gelecekteki güncellemelerden ve iyileştirmelerden yararlanmayacak.

Bu eklentiyi uygulamak için Android-KMP eklentisini uygulama bölümüne bakın. Eski API'lerden taşıma yapmanız gerekiyorsa Taşıma Rehberi'ni inceleyin.

Temel özellikler ve farklar

Android-KMP eklentisi, özellikle KMP projeleri için tasarlanmıştır ve standart com.android.library eklentisinden birkaç önemli açıdan farklıdır:

• Tek varyantlı mimari: Eklenti, tek bir varyant kullanır. Bu sayede, ürün çeşitleri ve derleme türleri için destek kaldırılır. Böylece yapılandırma basitleştirilir ve derleme performansı artırılır.

• KMP için optimize edildi: Eklenti, KMP kitaplıkları için tasarlanmıştır. Android'e özgü yerel derlemeler, AIDL ve RenderScript desteğini atlayarak paylaşılan Kotlin kodu ve birlikte çalışabilirliğe odaklanır.

• Varsayılan olarak devre dışı bırakılan testler: Derleme hızını artırmak için hem birim hem de cihaz (enstrümantasyon) testleri varsayılan olarak devre dışı bırakılır. Gerekirse bunları etkinleştirebilirsiniz.

• Üst düzey Android uzantısı yok: Yapılandırma, Gradle KMP DSL'deki bir androidLibrary bloğuyla yapılır ve tutarlı bir KMP proje yapısı korunur. Üst düzey android uzantı engellemesi yok.

• Java derlemesini etkinleştirme: Java derlemesi varsayılan olarak devre dışıdır. Etkinleştirmek için androidLibrary bloğunda withJava() simgesini kullanın. Bu, Java derlemesi gerekmediğinde derleme sürelerini kısaltır.

Android-KMP kitaplığı eklentisinin avantajları

Android-KMP eklentisi, KMP projeleri için aşağıdaki avantajları sunar:

• Daha iyi derleme performansı ve kararlılık: Optimize edilmiş derleme hızları ve KMP projelerinde daha iyi kararlılık için tasarlanmıştır. KMP iş akışlarına odaklanması, daha verimli ve güvenilir bir derleme sürecine katkıda bulunur.

• Gelişmiş IDE entegrasyonu: KMP Android kitaplıklarıyla çalışırken daha iyi kod tamamlama, gezinme, hata ayıklama ve genel geliştirici deneyimi sağlar.

• Basitleştirilmiş proje yapılandırması: Eklenti, derleme varyantları gibi Android'e özgü karmaşıklıkları kaldırarak KMP projelerinin yapılandırmasını basitleştirir. Bu sayede daha temiz ve bakımı daha kolay derleme dosyaları elde edilir. Daha önce, KMP projesinde com.android.library eklentisinin kullanılması, androidAndroidTest gibi kafa karıştırıcı kaynak grubu adlarının oluşturulmasına neden olabiliyordu. Bu adlandırma kuralı, standart KMP proje yapılarına aşina olan geliştiriciler için daha az sezgiseldi.

Ön koşullar

com.android.kotlin.multiplatform.library eklentisini kullanmak için projenizin aşağıdaki minimum sürümler veya daha yüksek sürümlerle yapılandırılması gerekir:

• Android Gradle Plugin (AGP): 8.10.0
• Kotlin Gradle Plugin (KGP): 2.0.0

Android-KMP eklentisini mevcut bir modüle uygulama

Android-KMP eklentisini mevcut bir KMP kitaplık modülüne uygulamak için aşağıdaki adımları uygulayın:

1. Sürüm kataloğunda eklentileri bildirin. Sürüm kataloğu TOML dosyasını (genellikle gradle/libs.versions.toml) açın ve eklenti tanımları bölümünü ekleyin:

   # To check the version number of the latest Kotlin release, go to
   # https://kotlinlang.org/docs/releases.html
   
   [versions]
   androidGradlePlugin = "8.13.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. Eklenti bildirimini kök derleme dosyasına uygulayın. Projenizin kök dizininde bulunan build.gradle.kts dosyasını açın. plugins kullanarak eklenti takma adlarını plugins bloğuna ekleyin.apply false Bu sayede, eklenti mantığı kök projeye uygulanmadan eklenti takma adları tüm alt projelerde kullanılabilir.

   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. Eklentiyi bir KMP kitaplık modülü derleme dosyasında uygulayın. KMP kitaplık modülünüzde build.gradle.kts dosyasını açın ve eklentiyi plugins bloğundaki dosyanızın en üstüne uygulayın:

   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. Android KMP hedefini yapılandırın. Android hedefini tanımlamak için Kotlin Multiplatform bloğunu (kotlin) yapılandırın. kotlin bloğunda, androidLibrary kullanarak Android hedefini belirtin:

   Kotlin

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

   Groovy

   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. Değişiklikleri uygulayın. Eklentiyi uygulayıp kotlin bloğunu yapılandırdıktan sonra değişiklikleri uygulamak için Gradle projenizi senkronize edin.

Eski eklentiden taşıma

Bu kılavuz, eski com.android.library eklentisinden com.android.kotlin.multiplatform.library eklentisine geçiş yapmanıza yardımcı olur.

1. Bağımlılıkları Bildirme

Sık karşılaşılan bir görev, Android'e özgü kaynak kümeleri için bağımlılıkları bildirmektir. Yeni eklenti, daha önce kullanılan genel dependencies bloğunun aksine bunların sourceSets bloğuna açıkça yerleştirilmesini gerektirir.

// 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 Kaynaklarını Etkinleştirme

Derleme performansını optimize etmek için yeni eklentide Android kaynakları (res klasörleri) desteği varsayılan olarak etkinleştirilmez. Bu özellikleri kullanmak için etkinleştirmeniz gerekir. Bu değişiklik, Android'e özgü kaynaklar gerektirmeyen projelerin ilişkili derleme ek yükünden etkilenmemesini sağlar.

// 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. Ana makine ve cihaz testlerini yapılandırma

Yeni eklentideki önemli bir değişiklik, Android ana tarafı (birim) ve cihaz tarafı (enstrümanlı) testlerinin varsayılan olarak devre dışı bırakılmasıdır. Test kaynağı kümelerini ve yapılandırmalarını oluşturmak için açıkça kabul etmeniz gerekir. Eski eklenti ise bunları otomatik olarak oluşturuyordu.

Bu etkinleştirme modeli, projenizin yalın kalmasına ve yalnızca etkin olarak kullandığınız derleme mantığını ve kaynak kümelerini içermesine yardımcı olur.

// 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. Java kaynak derlemesini etkinleştirme

KMP kitaplığınızın Android hedefi için Java kaynaklarını derlemesi gerekiyorsa bu işlevi yeni eklentiyle açıkça etkinleştirmeniz gerekir. Bu işlemin, bağımlılıkları için değil, doğrudan projenizde bulunan Java dosyaları için derlemeyi etkinleştirdiğini unutmayın. Java ve Kotlin derleyicisinin JVM hedef sürümünü ayarlama yöntemi de değişir.

// 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 kullanarak derleme varyantlarıyla etkileşim kurma

androidComponents uzantısı, derleme yapılarıyla programatik olarak etkileşim kurmak için kullanılmaya devam edebilir. Variant API'nin büyük bir kısmı aynı kalsa da eklenti yalnızca tek bir varyant ürettiğinden yeni AndroidKotlinMultiplatformVariant arayüzü daha sınırlıdır.

Sonuç olarak, derleme türleri ve ürün çeşitleriyle ilgili özellikler artık varyant nesnesinde kullanılamaz.

// build.gradle.kts

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

// build.gradle.kts

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

6. Android kitaplık bağımlılıklarının varyantlarını seçme

KMP kitaplığınız Android için tek bir varyant oluşturur. Ancak, birden fazla varyantı olan standart bir Android kitaplığına (com.android.library) bağımlı olabilirsiniz (ör. free/paid ürün aromaları). Projenizin bu bağımlılıktan nasıl bir varyant seçeceğini kontrol etmek yaygın bir gereksinimdir.

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

Plugin API referansı

Yeni eklentinin API yüzeyi, com.android.library'dan farklıdır. Yeni DSL ve arayüzler hakkında ayrıntılı bilgi için API referanslarına bakın:

• KotlinMultiplatformAndroidLibraryExtension
• KotlinMultiplatformAndroidLibraryTarget
• KotlinMultiplatformAndroidDeviceTest
• KotlinMultiplatformAndroidHostTest
• KotlinMultiplatformAndroidVariant