Derleme bağımlılıkları ekleme

Not: Bağımlılık eklerken indirdiğiniz ve projenize dahil ettiğiniz bağımlılıkların beklediğiniz gibi olmasını sağlamak için

bağımlılık doğrulamayı etkinleştirmeyi düşünebilirsiniz.

Android Studio'daki Gradle derleme sistemi, harici ikili dosyaları veya diğer kitaplık modüllerini bağımlılık olarak derlemenize dahil etmenize olanak tanır. Bağımlılıklar makinenizde veya uzak bir depoda bulunabilir ve bildirdikleri tüm geçişli bağımlılıklar da otomatik olarak dahil edilir. Bu sayfada, Android Gradle eklentisine (AGP) özgü davranışlar ve yapılandırmalarla ilgili ayrıntılar da dahil olmak üzere, Android projenizde bağımlılıkları kullanma şekli açıklanmaktadır. Gradle bağımlılıklarıyla ilgili daha ayrıntılı bir kavramsal kılavuz için Bağımlılık yönetimiyle ilgili Gradle kılavuzuna göz atın. Ancak Android projenizin yalnızca bu sayfada tanımlanan bağımlılık yapılandırmalarını kullanması gerektiğini unutmayın.

Dikkat: Bağımlılıkları belirtirken 'com.android.tools.build:gradle:3.+' gibi dinamik sürüm numaralarını kullanmamalısınız. Bu özelliğin kullanılması beklenmedik sürüm güncellemelerine, sürüm farklılıklarının çözülmesinde zorluğa ve düşük performansa neden olabilir.

Kitaplık veya eklenti bağımlılığı ekleme

Derleme bağımlılıklarını eklemenin ve yönetmenin en iyi yolu, yeni projelerin varsayılan olarak kullandığı yöntem olan sürüm kataloglarını kullanmaktır. Bu bölümde, Android projelerinde kullanılan en yaygın yapılandırma türleri ele alınmaktadır. Daha fazla seçenek için Gradle belgelerine bakın. Sürüm kataloglarını kullanan bir uygulama örneği için Now in Android'e bakın. Halihazırda sürüm katalogları olmadan oluşturma bağımlılıkları ayarladıysanız ve çok modüllü bir projeniz varsa taşımanızı öneririz.

Yerel bağımlılıkları (yaygın değildir) ekleme ve yönetme hakkında bilgi edinmek için Yerel bağımlılıklar başlıklı makaleyi inceleyin.

Aşağıdaki örnekte, projemize bir uzak ikili program bağımlılığı (Jetpack Macrobenchmark kitaplığı), yerel kitaplık modülü bağımlılığı (myLibrary) ve bir eklenti bağımlılığı (Android Gradle eklentisi) ekliyoruz. Bu bağımlılıkları projenize eklemek için genel adımlar şunlardır:

Not: Sürüm kataloglarını ayarlar dosyasında bildirmek mümkündür. Ancak Android Studio'dan kod önerileri ve vurgulama konusunda daha fazla destek almak için ayrı bir toml dosyası kullanmanızı öneririz.

1. Bağımlılığın istediğiniz sürümü için [versions] adlı sürüm kataloğu dosyasının [versions] bölümüne bir takma ad ekleyin (Proje görünümündeki gradle dizini veya Android görünümündeki Gradle Komut Dosyaları altında):libs.versions.toml

   [versions]
   agp = "8.3.0"
   androidx-macro-benchmark = "1.2.2"
   my-library = "1.4"
   
   [libraries]
   ...
   
   [plugins]
   ...
   

   Takma adlar tire veya alt çizgi içerebilir. Bu takma adlar, derleme komut dosyalarında referans verebileceğiniz iç içe yerleştirilmiş değerler oluşturur. Referanslar, kataloğun adıyla, yani libs.versions.toml bölümünün libs kısmıyla başlar. Tek sürüm kataloğu kullanırken varsayılan "libs." değerini korumanızı öneririz.

2. [libraries] (uzak ikililer veya yerel kitaplık modülleri için) ya da [plugins] (eklentiler için) bölümlerinde bağımlılık için bir diğer ad ekleyin.libs.versions.toml

   [versions]
   ...
   
   [libraries]
   androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "androidx-macro-benchmark" }
   my-library = { group = "com.myapplication", name = "mylibrary", version.ref = "my-library" }
   
   [plugins]
   androidApplication = { id = "com.android.application", version.ref = "agp" }
   

   Bazı kitaplıklar, kitaplık ailelerini ve sürümlerini gruplandıran yayınlanmış bir malzeme listesinde (BOM) bulunur. Sürüm kataloğunuza ve derleme dosyalarınıza bir BOM ekleyebilir ve bu sürümleri sizin için yönetmesine izin verebilirsiniz. Ayrıntılar için Malzeme Listesi'ni Kullanma başlıklı makaleyi inceleyin.

3. Bağımlılığı gerektiren modüllerin derleme komut dosyasına bağımlılık takma adına referans ekleyin. Bir derleme komut dosyasından referans verirken takma adın alt çizgilerini ve tirelerini noktalara dönüştürün. Modül düzeyindeki derleme komut dosyamız şu şekilde görünür:

   Kotlin

   plugins {
     alias(libs.plugins.androidApplication)
   }
   
   dependencies {
     implementation(libs.androidx.benchmark.macro)
     implementation(libs.my.library)
   }

   Groovy

   plugins {
     alias 'libs.plugins.androidApplication'
   }
   
   dependencies {
     implementation libs.androidx.benchmark.macro
     implementation libs.my.library
   }

   Eklenti referansları, katalog adından sonra plugins içerir. Sürüm referansları ise katalog adından sonra versions içerir (sürüm referansları yaygın değildir. Sürüm referansları örnekleri için Aynı sürüm numaralarına sahip bağımlılıklar bölümüne bakın). Kitaplık referansları libraries niteleyicisi içermediğinden kitaplık takma adının başında versions veya plugins kullanamazsınız.

Bağımlılıkları yapılandırma

dependencies bloğunda, birkaç farklı bağımlılık yapılandırmasından (ör. daha önce gösterilen implementation) birini kullanarak kitaplık bağımlılığı bildirebilirsiniz. Her bağımlılık yapılandırması, bağımlılığın nasıl kullanılacağıyla ilgili Gradle'a farklı talimatlar sağlar. Aşağıdaki tabloda, Android projenizdeki bir bağımlılık için kullanabileceğiniz yapılandırmaların her biri açıklanmaktadır.

Yapılandırma	Davranış
implementation	Gradle, bağımlılığı derleme sınıf yoluna ekler ve bağımlılığı derleme çıkışına paketler. Modülünüz bir implementation bağımlılığı yapılandırdığında Gradle'a, modülün derleme zamanında bağımlılığı diğer modüllere sızdırmasını istemediğinizi bildirir. Yani bağımlılık, mevcut modüle bağlı olan diğer modüller tarafından kullanılamaz. api yerine bu bağımlılık yapılandırmasını kullanmak, derleme sisteminin yeniden derlemesi gereken modül sayısını azalttığı için derleme süresinde önemli iyileşmeler sağlayabilir. Örneğin, bir implementation bağımlılığı API'sini değiştirirse Gradle yalnızca bu bağımlılığı ve doğrudan bu bağımlılığa bağlı olan modülleri yeniden derler. Çoğu uygulama ve test modülü bu yapılandırmayı kullanmalıdır.
api	Gradle, bağımlılığı derleme sınıf yolu ve derleme çıkışına ekler. Bir modül api bağımlılığı içerdiğinde, Gradle'a modülün bu bağımlılığı diğer modüllere geçişli olarak aktarmak istediği bildirilir. Böylece bu bağımlılık, hem çalışma zamanında hem de derleme zamanında diğer modüller tarafından kullanılabilir. Bu yapılandırmayı dikkatli bir şekilde ve yalnızca diğer yukarı akış tüketicilerine geçişli olarak aktarmanız gereken bağımlılıklarla kullanın. Bir api bağımlılığı harici API'sini değiştirirse Gradle, derleme sırasında bu bağımlılığa erişimi olan tüm modülleri yeniden derler. Çok sayıda api bağımlılığının olması derleme süresini önemli ölçüde artırabilir. Bir bağımlılığın API'sini ayrı bir modüle sunmak istemiyorsanız kitaplık modülleri bunun yerine implementation bağımlılıklarını kullanmalıdır.
compileOnly	Gradle, bağımlılığı yalnızca derleme sınıf yoluna ekler (yani derleme çıkışına eklenmez). Bu, bir Android modülü oluşturduğunuzda ve derleme sırasında bağımlılığa ihtiyacınız olduğunda yararlıdır ancak çalışma zamanında bağımlılığın mevcut olması isteğe bağlıdır. Örneğin, yalnızca derleme zamanı ek açıklamalarını içeren bir kitaplığa bağlıysanız (genellikle kod oluşturmak için kullanılır ancak çoğu zaman derleme çıktısına dahil edilmez) bu kitaplığı compileOnly olarak işaretleyebilirsiniz. Bu yapılandırmayı kullanıyorsanız kitaplık modülünüzde, bağımlılığın kullanılabilir olup olmadığını kontrol etmek için bir çalışma zamanı koşulu bulunmalıdır. Ardından, bağımlılık sağlanmadığı takdirde yine çalışabilmesi için davranışını sorunsuz bir şekilde değiştirmelidir. Bu, kritik olmayan geçici bağımlılıkları eklemeyerek nihai uygulamanın boyutunu küçültmeye yardımcı olur. Not: compileOnly yapılandırmasını Android Arşivi (AAR) bağımlılıklarıyla kullanamazsınız.
runtimeOnly	Gradle, bağımlılığı yalnızca derleme çıkışına ekler. Bu bağımlılık, çalışma zamanında kullanılır. Yani derleme sınıf yolu eklenmez. Bu özellik Android'de nadiren kullanılır ancak günlüğe kaydetme uygulamaları sağlamak için sunucu uygulamalarında yaygın olarak kullanılır. Örneğin, bir kitaplık, uygulama içermeyen bir günlük kaydı API'si kullanabilir. Bu kitaplığın tüketicileri, kitaplığı implementation bağımlılığı olarak ekleyebilir ve kullanılacak gerçek günlük kaydı uygulaması için runtimeOnly bağımlılığı içerebilir.
ksp kapt annotationProcessor	Bu yapılandırmalar, kodunuz derlenmeden önce ek açıklamaları ve diğer sembolleri işleyen kitaplıklar sağlar. Genellikle kodunuzu doğrular veya ek kod oluşturarak yazmanız gereken kodu azaltır. Böyle bir bağımlılığı eklemek için ksp, kapt veya annotationProcessor yapılandırmalarını kullanarak ek açıklama işleme sınıf yoluna eklemeniz gerekir. Bu yapılandırmaların kullanılması, derleme sınıf yolunu ek açıklama işlemcisi sınıf yolundan ayırarak derleme performansını artırır. Gradle, derleme sınıf yolunda ek açıklama işlemcileri bulursa derleme sınıf yolunda bulunan ek açıklama işlemcilerini yoksayarak derleme önlemeyi devre dışı bırakır. Bu durum, derleme süresini olumsuz etkiler (Gradle 5.0 ve sonraki sürümleri, derleme sınıf yolunda bulunan ek açıklama işlemcilerini yoksayar). Android Gradle eklentisi, JAR dosyasında aşağıdaki dosya varsa bağımlılığın bir ek açıklama işlemcisi olduğunu varsayar: META-INF/services/javax.annotation.processing.Processor Eklenti, derleme sınıf yolunda bir ek açıklama işlemcisi algılarsa derleme hatası oluşturur. ksp, Kotlin Sembol İşlemcisi'dir ve Kotlin derleyicisi tarafından çalıştırılır. kapt ve apt, Kotlin veya Java derleyicileri yürütülmeden önce açıklamaları işleyen ayrı araçlardır. Hangi yapılandırmayı kullanacağınıza karar verirken aşağıdakileri göz önünde bulundurun: Bir işlemci Kotlin Sembol İşlemcisi olarak kullanılabiliyorsa bunu ksp bağımlılığı olarak kullanın. Kotlin Sembol İşleyicileri'ni kullanma hakkında ayrıntılı bilgi için kapt'tan ksp'ye taşıma başlıklı makaleyi inceleyin. İşlemci, Kotlin Sembol İşlemcisi olarak kullanılamıyorsa: Projeniz Kotlin kaynağı içeriyorsa (Java kaynağı da içerebilir) kapt kullanarak projeye dahil edin. Projenizde yalnızca Java kaynağı kullanılıyorsa bunu dahil etmek için annotationProcessor kullanın. Açıklama işlemcilerini kullanma hakkında daha fazla bilgi için Açıklama işlemcileri ekleme başlıklı makaleyi inceleyin.
lintChecks	Bu yapılandırmayı, Android uygulama projenizi oluştururken Gradle'ın yürütmesini istediğiniz lint kontrollerini içeren bir kitaplığı dahil etmek için kullanın. lint.jar dosyası içeren AAR'ların, bu lint.jar dosyasında tanımlanan kontrolleri otomatik olarak çalıştıracağını unutmayın. Açık bir lintChecks bağımlılığı eklemeniz gerekmez. Bu sayede, kitaplıkları ve ilişkili lint kontrollerini tek bir bağımlılıkta tanımlayabilir, tüketiciler kitaplığınızı kullandığında kontrollerinizin çalıştırılmasını sağlayabilirsiniz.
lintPublish	Gradle'ın lint.jar dosyasına derlemesini ve AAR'nize paketlemesini istediğiniz lint kontrollerini dahil etmek için Android kitaplık projelerinde bu yapılandırmayı kullanın. Bu durum, AAR'nizi kullanan projelerin de bu lint kontrollerini uygulamasına neden olur. Yayınlanan AAR'ye lint kontrollerini dahil etmek için daha önce lintChecks bağımlılık yapılandırmasını kullanıyorsanız bu bağımlılıkları lintChecks yapılandırmasını kullanacak şekilde taşımanız gerekir.lintPublish Kotlin dependencies { // Executes lint checks from the ":checks" project at build time. lintChecks(project(":checks")) // Compiles lint checks from the ":checks-to-publish" into a // lint.jar file and publishes it to your Android library. lintPublish(project(":checks-to-publish")) } Groovy dependencies { // Executes lint checks from the ':checks' project at build time. lintChecks project(':checks') // Compiles lint checks from the ':checks-to-publish' into a // lint.jar file and publishes it to your Android library. lintPublish project(':checks-to-publish') }

Belirli bir derleme çeşidi için bağımlılıkları yapılandırma

Yukarıdaki yapılandırmaların tümü, tüm derleme varyantlarına bağımlılıklar uygular. Bunun yerine yalnızca belirli bir build variant kaynak kümesi veya testing source set için bağımlılık bildirmek istiyorsanız yapılandırma adını büyük harflerle yazıp başına derleme varyantının veya test kaynağı kümesinin adını eklemeniz gerekir.

Örneğin, implementation yapılandırmasını kullanarak yalnızca "free" ürün çeşnisine uzak bir ikili bağımlılık eklemek için şunu kullanın:

Kotlin

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

Groovy

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

Ancak bir ürün aroması ve derleme türünü birleştiren bir varyant için bağımlılık eklemek istiyorsanız yapılandırma adını başlatmanız gerekir:

Kotlin

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

Groovy

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

Yerel testleriniz ve enstrümanlı testleriniz için implementation bağımlılıkları eklemek isterseniz:

Kotlin

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation("junit:junit:4.12")

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1")
}

Groovy

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation 'junit:junit:4.12'

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.6.1'
}

Ancak bazı yapılandırmalar bu durumda anlamlı değildir. Örneğin, diğer modüller androidTest modülüne bağlı olamayacağından androidTestApi yapılandırmasını kullanırsanız aşağıdaki uyarıyı alırsınız:

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.

Bağımlılık sırası

Bağımlılıklarınızı listelediğiniz sıra, her birinin önceliğini gösterir: İlk kitaplık, ikinciden daha yüksek önceliğe, ikinci kitaplık da üçüncüden daha yüksek önceliğe sahiptir. Bu sıra, kitaplıklardan uygulamanıza kaynaklar birleştirildiğinde veya manifest öğeleri birleştirildiğinde önemlidir.

Örneğin, projeniz aşağıdakileri bildiriyorsa:

• LIB_A ve LIB_B'ye (bu sırayla) bağımlılık
• Ayrıca LIB_A, LIB_C ve LIB_D'ye (bu sırayla) bağlıdır.
• Ayrıca LIB_B, LIB_C SDK'sına da bağlıdır.

Bu durumda, düz bağımlılık sırası aşağıdaki gibi olur:

1. LIB_A
2. LIB_D
3. LIB_B
4. LIB_C

Bu sayede hem LIB_A hem de LIB_B, LIB_C'yi geçersiz kılabilir. Ayrıca LIB_A (LIB_D'ye bağlıdır) LIB_B'den daha yüksek önceliğe sahip olduğundan LIB_D, LIB_B'den daha yüksek önceliğe sahip olmaya devam eder.

Farklı proje kaynaklarından/bağımlılıklarından gelen manifestlerin nasıl birleştirildiği hakkında daha fazla bilgi için Birden fazla manifest dosyasını birleştirme başlıklı makaleyi inceleyin.

Play Console için bağımlılık bilgileri

AGP, uygulamanızı oluştururken uygulamanıza derlenen kitaplık bağımlılıklarını açıklayan meta verileri içerir. Play Console, uygulamanızı yüklerken uygulamanızın kullandığı SDK'lar ve bağımlılıklarla ilgili bilinen sorunlar için uyarılar sağlamak ve bazı durumlarda bu sorunları çözmek için uygulanabilir geri bildirimler sağlamak üzere bu meta verileri inceler.

Veriler sıkıştırılır, Google Play imzalama anahtarıyla şifrelenir ve yayın uygulamanızın imzalama bloğunda saklanır. Güvenli ve olumlu bir kullanıcı deneyimi için bu bağımlılıklar dosyasını saklamanızı öneririz. Modülünüzün build.gradle.kts dosyasına aşağıdaki dependenciesInfo bloğunu ekleyerek bu özelliği devre dışı bırakabilirsiniz.

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

Politikalarımız ve bağımlılıklarla ilgili olası sorunlar hakkında daha fazla bilgi için uygulamanızda üçüncü taraf SDK kullanma başlıklı destek sayfamıza göz atın.

SDK analizleri

Android Studio, aşağıdaki sorunlar geçerli olduğunda Google Play SDK Dizini'ndeki herkese açık SDK'lar için sürüm kataloğu dosyasında ve Proje Yapısı iletişim kutusunda lint uyarıları gösterir:

• SDK'lar yazarları tarafından güncel olmayan olarak işaretlenir.
• SDK'lar, Play politikalarını ihlal ediyor.
• SDK'larda bilinen güvenlik açıkları var.
• SDK'lar, yazarları tarafından kullanımdan kaldırılmıştır.

Uyarılar, bu bağımlılıkları güncellemeniz gerektiğine dair sinyallerdir. Çünkü eski sürümleri kullanmak, gelecekte Google Play Console'da yayın yapmanızı engelleyebilir.

Sürüm katalogları olmadan derleme bağımlılıkları ekleme

Bağımlılıkları eklemek ve yönetmek için sürüm kataloglarını kullanmanızı öneririz ancak basit projelerde bu kataloglara ihtiyaç duyulmayabilir. Aşağıda, sürüm kataloglarının kullanılmadığı bir derleme dosyası örneği verilmiştir:

Kotlin

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation("com.example.android:app-magic:12.3")
    // Dependency on a local library module
    implementation(project(":mylibrary"))
}

Groovy

plugins {
    id 'com.android.application'
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation 'com.example.android:app-magic:12.3'
    // Dependency on a local library module
    implementation project(':mylibrary')
}

Bu derleme dosyası, "com.example.android" ad alanı grubundaki "app-magic" kitaplığının 12.3 sürümüne bağımlılığı bildirir. Uzak ikili bağımlılık bildirimi, aşağıdakilerin kısaltmasıdır:

Kotlin

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

Groovy

implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

Derleme dosyası, "mylibrary" adlı bir Android kitaplık modülüne bağımlılığı da bildirir. Bu ad, include: ile tanımlanan kitaplık adıyla eşleşmelidir.settings.gradle.kts Uygulamanızı oluşturduğunuzda derleme sistemi, kitaplık modülünü derler ve derlenen içerikleri uygulamada paketler.

Derleme dosyası, Android Gradle eklentisine (com.application.android) bağımlılığı da bildirir. Aynı eklentiyi kullanan birden fazla modülünüz varsa tüm modüllerde derleme sınıf yolunda eklentinin yalnızca tek bir sürümü olabilir. Sürümü her bir modül derleme komut dosyasında belirtmek yerine, eklenti bağımlılığını sürümle birlikte kök derleme komut dosyasına ekleyip uygulanmaması gerektiğini belirtmeniz gerekir. apply false eklemek, Gradle'a eklentinin sürümünü not etmesini ancak kök derlemede kullanmamasını söyler. Genellikle kök derleme komut dosyası, bu plugins bloğu dışında boştur.

Kotlin

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

Groovy

plugins {
    id ‘com.android.application’ version ‘8.3.0-rc02’ apply false
}

Tek modüllü bir projeniz varsa sürümü modül düzeyindeki derleme komut dosyasında açıkça belirtebilir ve proje düzeyindeki derleme komut dosyasını boş bırakabilirsiniz:

Kotlin

plugins {
    id("com.android.application") version "8.3.0"
}

Groovy

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}